document-review

ドキュメントレビュー

構造化されたレビューを通じて、ブレインストーミングや計画のドキュメントを改善します。

作業ルール

• 編集前に評価し、実装に関わる制約や根拠を維持したうえで、軽微な編集と実質的な判断を区別します。
• レビューのみの依頼で認められるのは指摘の提示までです。変更を適用するのは、ユーザーが編集を依頼した場合、または提案された変更を承認した場合に限ります。すでに承認されている変更について、再度確認を求めないでください。

ステップ 1：ドキュメントを取得する

ドキュメントのパスが指定されている場合： そのドキュメントを読み、ステップ 2 に進みます。

ドキュメントが指定されていない場合： レビューするドキュメントを尋ねます（Claude Code では AskUserQuestion、Codex では request_user_input を使用し、どちらも使えない場合はチャットで番号付きの選択肢を提示します）。または、docs/brainstorms/ や docs/plans/ から最新のブレインストーミングまたは計画のドキュメントを探します。

ステップ 2：評価する

ドキュメントを読み、以下の点を確認します。

• 不明瞭な点は何ですか？
• 不要なものは何ですか？
• どの判断が先送りされていますか？
• 明示されていない前提は何ですか？
• スコープが意図せず拡大する可能性がある箇所はどこですか？
• 現在のアーキテクチャで技術的に実現可能ですか？
• 現行システムについての記述は事実と合っていますか？確認可能な主張（ファイルパス、関数、コマンドや設定の名前、エンドポイント、参照されている PR や issue、数値、「再試行する」のような動詞から推測される動作など）をそれぞれ情報源までたどり、読み取りのみで確認します。長いドキュメントでは、確認範囲を抽出して、その範囲を明記します。
• 提案内容にセキュリティ上の影響はありますか？

これらの質問を通じて問題点を明らかにします。まだ修正せず、指摘事項を記録します。

ステップ 3：レビューの視点を適用する

ドキュメントの内容に応じて、専門的なレビューの視点を適用します。兆候を確認し、該当する視点を使います。

視点	兆候	確認する内容
プロダクト	ユーザー向け機能、顧客向けの表現、市場に関する主張、スコープの判断	問題設定、価値提案の明確さ、スコープが明示された目標に合っているか
デザイン	UI/UX への言及、ユーザーフロー、ワイヤーフレーム、操作の説明	フローの完全性、操作上の抜け、アクセシビリティへの配慮
セキュリティ	認証／認可、API エンドポイント、PII、決済、トークン、暗号化	認証モデルの不足、データ漏えいのリスク、脅威に関する考慮事項の欠落
スコープ管理	優先度の段階（P0/P1/P2）が複数ある、大量の要件（8 件超）、ストレッチゴール	スコープの肥大化、時期尚早な抽象化、要件を装った機能
敵対的レビュー	要件が 5 件を超える、明示的なアーキテクチャ上の判断、重大な影響を伴う分野	明示されていない前提、楽観的な見積もり、単一障害点、考慮されていない障害モード

いずれかの兆候に当てはまる場合、その視点を適用します。ほとんどのドキュメントで該当する視点は 1～2 個ですが、ブレインストーミングのメモでは該当しないこともあります。視点を適用する場合は、別途レビューするのではなく、評価と検証の各ステップにその観点を織り込みます。

ステップ 4：評価する

以下の基準に沿ってドキュメントを評価します。

基準	確認する内容
明確さ	問題の説明が明確で、「おそらく」「検討する」「試してみる」といった曖昧な表現がない
完全性	必要なセクションがそろい、制約が明記され、未解決の質問が示されている
具体性	次の段階に進めるだけの具体性がある（ブレインストーミング → 計画を立てられる、計画 → 実装できる）
YAGNI	仮定上の機能がなく、最もシンプルな方法が選ばれている
正確性	確認した主張が情報源と一致している（ステップ 2）。矛盾する主張は、食い違いのある file:line とともに欠陥として報告します。明示された確認範囲外の主張は未検証であり、検証済みとはみなしません

ワークフロー内（/ia-brainstorm または /ia-plan の後）で実行する場合は、以下も確認します。

• ユーザーの意図への忠実性：ドキュメントに議論内容が反映され、前提が検証されている

ステップ 5：最も重要な改善点を特定する

ステップ 2～4 で見つかった内容の中に、特に重要な問題はありますか？ドキュメントの品質を大幅に高める改善点があれば、それを「必ず対応する項目」とします。目立つように強調してください。

ステップ 6：変更を行う

調査結果を提示したうえで、次の作業を行います。

1. 承認済みの編集を適用する：依頼された範囲内で、細かな文言や書式の修正も含めて変更します。レビューのみの依頼では、これらを提案として報告します。
2. 承認を求める：既存の許可範囲を超える変更（構成の変更、セクションの削除、意味の変更）については承認を求めます。AskUserQuestion（Claude Code。未ロードの場合は ToolSearch で select:AskUserQuestion をロード）または request_user_input（Codex）を使用してください。利用できない場合は、チャットで番号付きの選択肢を提示します。判断が具体的にできるよう、質問する前に以下の形式で調査結果を提示してください。
3. 文書を更新する：承認済みの変更のみ文書に反映します。それ以外の場合は、調査結果を返します。

判断用の調査結果の提示

調査結果を判断する読者は文書を開いておらず、識別子も覚えていません。このルールは承認を求める場合（上記の手順 2）のみに適用されます。自動修正する調査結果は、手順 1 に従い、このルールを適用しません。承認を求める調査結果は、以下の順序で提示します。

1. 変更しない場合の影響：誰にどのような問題が起きるのかを、一文で説明します。読者が調べる必要のある識別子は含めません。
2. 推奨する対応：明確に推奨とわかる形で示します。
3. 変更の意図：一文で説明します。
4. 仕組み：最大 2 文で説明し、意味が不透明なアンカーは最大 2 つまで含めます（下記を参照）。

さらに詳しい情報（ファイルの追跡、複数の呼び出し経路、呼び出し元の比較など）は提示せず、最後に必要であれば一行で詳細を案内します。文ごとにインラインコードは 2 組までとします。差分ブロックは使用せず、追加内容が実際に 5 行以下の場合に限り、生のコードブロックを使用します。

不透明なアンカーは、用語ではなく役割に基づいて分類します。

• ナビゲーションアンカー（文書内で定義されている ID）は、ID をそのまま残し、最初に言及する際に短い説明を付けます。例：R6（重要度の低い呼び出しで同僚のパネルを抑制）。ID のみを記載してはいけません。
• 出所アンカー（チケット ID、PR 番号）は、参照先の出来事が判断に影響する場合に限り、役割の説明を付けます。それ以外は詳細情報に回します。
• 仕組みアンカー（関数名、ファイル名、行番号）は、判断における役割に置き換えます（例：「ターミナル失敗の判定条件」）。厳密な対象範囲が判断の分かれ目となる場合に限り、正確なシンボル名を残します。正確性に関する主張が相反する場合は、相反する file:line を唯一の仕組みアンカーとして残します。

「該当箇所を読んでください」と言わなければ判断できない調査結果は、どれほど正確でも不十分です。

簡素化の指針

簡素化とは、必要のない複雑さを取り除くことであり、ただ短くすることではありません。

簡素化する場合：

• 現在のニーズではなく、将来の仮定的なニーズに対応する内容
• 別の場所ですでに説明されている情報を繰り返すセクション
• 次の手順を進めるのに必要な範囲を超える詳細
• 明確さを高めず、負担だけを増やす抽象化や構成

簡素化しない場合：

• 実装に影響する制約や例外
• 他の選択肢を採用しなかった理由を説明する根拠
• 解決が必要な未解決の質問

ステップ 7：次のアクションを提示する

変更が完了したら、次のどちらかを確認します。

1. もう一度調整する — 追加のレビューを行います
2. レビューを完了する — 文書は完成です

イテレーションのガイダンス

2回のブラッシュアップを終えた後、重大な問題が残っていない場合に限り、完了を提案してください。ユーザーが続行を希望する場合は、合計4回まで実施できます。ある回で重大な変更が不要だと判断できた場合にのみ、収束したと見なしてください。4回に達したら終了し、「レビュー上限に達しました。以降のパスには新たな方向性が必要です」と報告してください。引き継ぎには、未解決の指摘事項と未検証の主張を含めてください。新たな枠組みが提示されない限り、ユーザーが希望しても4回を超えて続行しないでください。

以前の回答ですでに決着した内容は取り下げてください。 2回目以降のパスでは、残っている各指摘事項を提示する前に、このセッションですでに決まった内容と照らし合わせて判断してください。以前の回答で解決済み、または矛盾する内容であれば、指摘事項を再度提示せず、指摘内容と、それを退けた回答を1行で述べてから次に進み、要約では、退けた判断を明記して withdrawn と記録してください。重要な違いとして、ユーザーの判断（スキップ、保留、事実の表明）による取り下げは確定的であり、その後のすべてのパスで指摘事項を抑止します。一方、修正保留中であることによる取り下げは暫定的です。次のパスで同じ指摘事項が再発した場合は、抑止したままにせず再提示してください。指摘事項を提示する時点で必要に応じて判断し、回答のたびに再確認してはいけません。（コードレビューにも同じルールが適用されます。過去の議論との照合については ia-code-review を参照してください。）

選択後は、呼び出し元（ワークフローまたはユーザー）に制御を戻してください。

制約

• ドキュメント全体を書き直さず、対象となるセクションを修正してください。構造に根本的な問題がある場合は、その問題を示し、構成を変更する許可を求めてください。
• 不足しているセクションはレビューで指摘してください。ただし、追加してはいけません。何を含めるかはユーザーが決定します。
• 変更は最小限にしてください。段落を簡潔にする必要がある場合は、簡潔にしてください。対象範囲を広げてはいけません。
• レビューは本文内で行ってください。別のレビュー用ファイルやメタデータのセクションは作成しないでください。

成功基準

• 5つすべての品質基準に照らしてドキュメントを読み、評価している
• 関連するレビュー観点を適用し、チェックしている
• 重要な改善点を、具体的な提案とともに特定している
• 次のアクションとして、ブラッシュアップするか完了するかをユーザーが明確に選べる
• 変更が承認された場合、改訂版のドキュメントを保存している

タスク固有の参考資料

該当する動作を実装またはレビューする前に、関連する参考資料を読んでください。

• 独立したドキュメントに対する、任意のコンテキストなし読者テストについては、reader-test.md を参照してください。