review-docs

実際の読者の視点で、プロジェクトの顔となるドキュメント（デフォルトは README.md。ユーザーがパスを指定した場合はそれに従う）をレビューしてください。作者の視点ではありません。作者はすべての行の意味を理解していますが、初めて読む人はそうではありません。特定の読者がどこで混乱するか、必要な情報が足りないと感じるか、読むのをやめるかを明らかにし、採点して、具体的な改善案を提示するのが目的です。

この方法はファンアウトです。ペルソナごとにサブエージェントを1つずつ並列で起動し、それぞれがその読者になりきって先入観なく読みます。読者によって気づく点は異なります。同時に実行すれば時間を短縮でき、各自の読みがほかの意見に影響されません。

実施方法

1. まず対象ドキュメントを自分で読む

ドキュメント全体を読み、リンク先のドキュメントにもざっと目を通します（「リンク先のドキュメントが約束した深さに達していない」という点を確認できるようにするためです）。ペルソナの指摘を評価し、後で修正を適用するために必要です。

2. ペルソナごとにサブエージェントを1つずつ並列で起動する

以下のペルソナを1つのメッセージで（複数のAgent/Task呼び出しを同時に）起動し、並列で実行します。高速で低コストのモデル（SonnetまたはHaiku）を使います。これは重い統合作業ではなく、読解と判断のタスクであることを、起動時に1行で伝えてください。

各サブエージェントには、ペルソナだけを変え、同じ評価基準を渡してください。

あなたは**<PERSONA>**です。<path>を読んでください（冒頭にあるHTMLコメントブロックは、ユーザー向けの文面ではなく作者向けのメモなので無視してください）。この読者になりきって、先入観なく読んでください。読者の目標、語彙、忍耐度を意識してください。厳しく評価してください。ほとんどのREADMEは3点です。5/5は、実際に行動に移す気になり、最初から最後まで明快な場合に限ります。以下のみを返してください：

1. スコア：x/5
2. **30秒テスト：**最初の画面だけを読んで、このツールが何をするものだと思ったかを1文で述べ、それが正しいか、間違っているか、曖昧かを示してください。
3. 具体的な問題トップ3 — それぞれ、該当箇所を正確に引用し、具体的な書き換え案を示してください（わかりにくい専門用語、複数の要点を詰め込みすぎた文、魅力が伝わらない表現、流し読みしにくい書式、信頼を損なう誇張など）。
4. **専門用語の確認：**読む手を止めた単語をすべて挙げてください（harness、spec、eval、subagent、rings、recall/precision…など）。文脈で定義されていますか、それとも推測するしかありませんか？
5. 良い点 — 改訂で失われないよう、残すべき点を挙げてください。
6. 最も効果の大きい変更を1つ。該当する文面を正確に引用してください。遠慮せず、役立つ指摘をしてください。

3. ペルソナ（ファンアウト対象）

ユーザーが対象を絞っていない限り、以下すべてを実行してください。ドキュメントに合わせて対象を自由に調整してください。これはvigilesのトップページを読む標準的な読者です。

1. Claude Codeの初心者 — エージェント型ツールに不慣れで、未定義の用語が出ると読むのをやめます。理論ではなく、「まず何をすればよいか」を知りたい読者です。定義前に専門用語が使われている箇所を見つけます。
2. Claude Codeのパワーユーザー — Claude Codeを常用し、タスクの合間にスマートフォンで流し読みします。最初の画面でWOWを知りたく、数秒でコピー＆ペーストできるインストール手順を求めます。余計な説明は好みません。
3. プラグイン／スキルの作者 — TypeScriptには慣れているものの、ルールエンフォーサーや型の専門家ではない、中堅の開発者です。自分のスキルをテストできるという説明を見て、このツールにたどり着きました。「新しい理論を学ばなくても、自分のリポジトリで動くのか」を重視します。
4. 懐疑的なシニア／スタッフエンジニア — 約20秒で要点を確認し、promptfoo／ESLint／ast-grepと頭の中で比較します。曖昧な説明や誇張は信頼を損ない、重要な主張にはすべて根拠へのリンクが必要です。
5. 意思決定者（コマンドを実行しない） — チームに導入するかどうかを判断しています。コスト、リスク、作業量を重視します。「無料の決定論的チェックと、トークンごとに料金が発生するチェック」の違いや、リスクを抑えた段階的な導入方法を、何も実行せずに理解できる必要があります。
6. Codexユーザー（任意） — Claude CodeではなくAGENTS.mdを使います。これが「Claude専用」ではないかと疑っています。Codexのサポートは早い段階で明示されていますか、それとも脚注に埋もれていますか？

4. 総合

スコアとレポートを集めます。その後、次のようにします。

• まず、複数の観点に共通する問題を挙げます。 複数のペルソナに影響する2～4個の問題は、最も効果の高い修正箇所です。最初に取り上げます。
• 最も低いスコアが上限です。 ドキュメントの評価は、最も読みづらさを感じた読者の評価を超えられません。そのペルソナの理解を妨げている要因を明示します。
• 修正リストを優先順位順に作成します。 読者への影響が大きいものから並べ、それぞれに該当行を引用した1行の対応策を記載します。

5. 目標に達するまで反復する（依頼があった場合のみ）

ユーザーが「N/5にして」（または「5/5になるまで」）と依頼した場合は、まず自分で効果の高い修正を適用します。その後、再度評価を依頼し（変更点を伝えて同じサブエージェントを再開するか、新たに起動して）、新しいスコアを集めます。すべてのペルソナが目標に達するか、スコアが変化しなくなるまで繰り返します。反復には上限を設けます。 1回の反復で改善がない場合、または約3回反復した場合は、そこで終了し、最後の1点を妨げている要因を報告します。デフォルトではこのスキルは報告のみを行います。明示的に「修正して／N/5にして」と依頼された場合に限り、修正と反復のループを開始します。

出力形式

# Doc review — <file>

## Scores
<persona> — x/5   (one-line verdict each)

## Cross-cutting issues (highest leverage)
The 2–4 problems hitting multiple personas, each with the line + the fix.

## Per-persona highlights
The sharpest single finding from each reader (don't dump the full reports).

## Ranked fixes
Ordered, highest reader-impact first — each a one-line action.

要点をすばやく把握でき、実行に移せる形にしてください。各指摘には、該当行と修正内容を必ず記載します。レビューでは、ドキュメント自身の基準に照らして評価します。READMEの場合は、最初に読む人向けの簡潔さが基準です（利点を先に示す、1文につき1つの内容にする、専門用語は初出時に説明する、詳しい情報はリンク先のドキュメントに委ねる）。ユーザーが反復による修正を依頼しない限り、ドキュメント自体は書き換えません。このスキルはデフォルトでは報告のみを行います。