docs-ai-prd

PRD、仕様書、プロジェクトのコンテキスト

ワークフロー

1. 成果物を選びます。
2. 根拠、制約、依存関係を集めます。
3. 対象のツールまたはチームのワークフローに適した、標準のコンテキストを選びます。
4. まず決定事項を書きます。
5. 受け入れ基準、ロールアウトのゲート、ソースに基づく事実を追加します。複数のセッションまたは作業者にまたがる作業の場合は、デリバリーマイルストーン表を追加します。
6. 引き継ぎ前に、関連するチェックリストで検証します。ソースの一覧を作成する場合は、python3 scripts/validate_sources.py --scan-only を実行します。このコマンドはアーカイブとシンボリックリンクを除外し、スキャン対象のルートが無効または空の場合、およびソースファイルを読み取れない場合は終了コード 2 を返します。一覧の作成に成功しても、記載内容や有効な URL が検証されたことにはなりません。

クイックリファレンス

必要なもの	参照先
コア PRD	assets/prd/prd-template.md
AI 機能の PRD	assets/prd/ai-prd-template.md
技術設計	assets/spec/tech-spec-template.md
ストーリーマップまたはバックログの整理	assets/stories/story-mapping-template.md
受け入れ基準	assets/stories/gherkin-example-template.md
デリバリーマイルストーン（複数セッションにまたがる作業）	references/delivery-milestones.md
計画チェックリスト	assets/planning/planning-checklist.md
エージェントへの引き継ぎ	assets/planning/agentic-session-template.md
最小限のエージェントコンテキストファイル	assets/minimal-claudemd.md, assets/minimal-agents.md
ツール間のコンテキストのレイヤー化	assets/cross-tool-context.md
スタック固有のプロジェクトコンテキスト（一から書かず、空欄を埋めてください）	assets/web-app-context.md, assets/api-service-context.md, assets/cli-context.md, assets/library-context.md, assets/react-context.md, assets/nodejs-context.md, assets/python-context.md, assets/go-context.md

専門家の判断：仕様書がコーディングエージェントを失敗させる理由

引き継ぎ前に、エージェントが文書化された要件を満たしながら、作成者の意図しない動作を実装できてしまわないか確認してください。

エージェントの実行を妨げる曖昧さの種類

次の6種類の曖昧さがないか確認します。

1. 照応の曖昧さ — 固定された名詞句、ID、スキーマへの参照がないまま、「ユーザー」「フォーム」「それ」などと記述されています。エージェントはもっともらしい直近の対象を参照先として選びますが、それは作成者が想定したケースとは異なることがあります。
2. 暗黙のデフォルトに関する曖昧さ — 重複したメールアドレス、空のリスト、同時編集などのケースが一切言及されていないため、エージェントがデフォルトの動作を作り出します。そのデフォルトがシステムのほかの部分と照らして検証されることは、ほとんどありません。
3. スコープ境界の曖昧さ — 仕様書に新しい動作は記述されているものの、変更してはならないものが明記されていません。そのため、エージェントが周辺のコードまで過剰にリファクタリングしたり、削除を依頼されていない不要な処理経路を残したりします。
4. 時間・順序に関する曖昧さ — 手順は暗示されているものの、順序が示されていません（「検証して保存する」— 元に戻せない副作用の前と後のどちらで検証するのか？）。
5. 測定方法の曖昧さ — 「高速」「信頼性が高い」「安全」「クリーン」といった表現に、単位、しきい値、パーセンタイル、テスト方法が指定されていません。
6. 優先権の曖昧さ — 仕様書と既存コードの内容が食い違っているのに、どちらを優先するかが示されていません。エージェントは一方を選びますが、次のエージェント（または次のセッション）がもう一方を選ぶ可能性があります。

過剰な仕様指定と仕様不足：調整の判断

• 過剰な仕様指定では、結果だけが重要な場合でも、実装方法（特定のライブラリ、正確な変数名、行単位の疑似コード）まで指定します。代償として、指定された方法がコードベースに合わないとエージェントが手戻りを繰り返したり、意図ではなく記述どおりのものをそのまま実装したりします。また、その食い違いがレビューまで見つからないこともあります。
• 仕様不足では、タイトルと1段落だけを示し、正常系以外のすべてを暗黙のままにします。代償として、エージェントが契約の詳細（エラーの形式、再試行回数、空の状態での動作）を独自に決め、ほかの3つの呼び出し箇所にすでに組み込まれている前提と衝突することがあります。事後に判明すると、事前に判明する場合よりも解決にコストがかかります。

詳細度は、習慣やテンプレートの長さではなく、次の3つの変数に合わせて調整します。

影響範囲	可逆性	エージェントの自律性	適切な詳細度
高（決済、認証、削除、PII）	低（ロールバックが困難）	任意	すべてのエッジケースを明示的に仕様化し、さらに「絶対にしてはならないこと」のリストを追加します
中	中	1ステップごとに監督（人間が各ステップをレビュー）	決定事項と未解決の質問を記載し、残りのエッジケースはレビューの反復で解決します
低（プロトタイプ、社内ツール、フラグの背後）	高（低コストで元に戻せる）	任意	結果と正常系を示し、エージェントにエッジケースの提案と指摘を任せます
中または高	任意	無人／自律実行（完了まで人間が介在しない）	すべてのエッジケースを仕様化します。実行途中の逸脱を見つけるレビュー担当者がいないためです

受け入れ条件のテスト可能性：チェックリストを超えた判断

references/acceptance-criteria-patterns.mdでは、形式とよくある間違いを説明しています。チェックリストの先には、判断が必要な点が2つあります。

• 「失敗するテストを具体的に思い描けない」という兆候。 文章としてはよく書けていても、テストが1つも生成されない受け入れ条件は反証できません。動作が誤っていた場合に失敗する具体的なテストを説明できないなら、その受け入れ条件は未完成です。引き継ぎの前に書き直し、不足分をエージェントが推測してくれることに期待して、そのままリリースしないでください。
• 「能力のあるエンジニア2人」という兆候。 仕様の失敗で最もよくある原因は、受け入れ条件の欠落ではありません。同じ受け入れ条件を、実質的に異なる2つの実装が同時に満たしてしまうことです。「能力のあるエンジニア2人が異なるものを作り、どちらもこの受け入れ条件を満たしたと正直に言えるか」と考えてください。答えが「はい」なら、答えが「いいえ」になるまで、具体的な入出力の組、特定のエラーコード、明示的な順序など、区別を明確にする条件を追加します。

決定事項と未確定事項の台帳

未解決のプロダクト上の選択事項を、宣言的な要件に含めないでください。未確定事項ごとに、必要な決定、現在の前提、担当者、期限またはブロッキングマイルストーン、影響を受ける要件、判断を確定するために必要な根拠を記録してください。その前提に依存する受け入れ基準には印を付け、実装者が仮置きの内容を承認済みの動作と誤解しないようにしてください。

リポジトリから分かるのは、システムが現在どのように動作するかであり、ビジネス上の要件ではありません。コードから SLA、価格、コンプライアンスや保持に関する義務、優先順位、対象ユーザーを推測してはいけません。ユーザーまたは権威ある文書によって確定されるまでは、確認が必要な前提として台帳に記載してください。誤った推測がセキュリティ上の露出、データ損失、取り消せない移行、契約や API の破壊的変更、重大なコスト、または破壊的な外部操作につながるおそれがある未確定事項に限り、ユーザーの回答を待ってください。それ以外は前提を記録して作業を進めてください。

実装によって受け入れ基準を満たせないことが分かった場合、その基準を削除したり、黙って回避したりしてはいけません。[revised] と印を付け、制約を明記し、適用範囲または検証方法を調整して、仕様のリビジョンを上げ、変更した基準のみを再提示してください。変更によってブロッキングとなる決定が変わる場合、または安全性や正確性の保証が弱まる場合に限り、明示的な確認を求めてください。

決定が確定したら、要件と受け入れ基準をまとめて更新し、決定の出典を記載して台帳の項目を完了してください。PRD は、すべてのブロッキングとなる未確定事項が解決済みであるか、スコープ外として明示的に延期されているか、または名前付きのデフォルト値とフォールバックを備えた安全な実行時／設定上の選択肢として示されている場合にのみ、実装に着手できる状態です。

ツール間のコンテキストルール

プロジェクトのメモリーは階層構造として扱ってください。表には各ツールで通常使用される場所を示しています。実行時に実際に読み込まれるファイルとその優先順位は、agents-memory が確認する事項です。

ツール	主な場所	補助的な場所
Claude Code	すべてのコントリビューターでネイティブ読み込みが検証済みの場合は AGENTS.md、それ以外の場合は AGENTS.md を読み込む CLAUDE.md	スコープ指定の Claude ファイル、エージェント、スキル、フック
GitHub Copilot	.github/copilot-instructions.md	追加の GitHub 指示、AGENTS.md
Cursor	.cursor/rules/ またはルートの AGENTS.md	ルートの CLAUDE.md、スコープ指定のルールファイル
移植可能なベースライン	AGENTS.md	詳細なガイダンスを重複させず、リンクで参照

Claude Code が AGENTS.md をネイティブに読み込むかどうか、また両方のファイルが存在する場合にどちらが優先されるかは、リリースによって変わります。仕様にサポート状況を記載しないでください。AGENTS.md を唯一の情報源として維持してください。agents-memory の確認手順に従い、各コントリビューターのバージョン、プロバイダー、設定で /memory を使って読み込み済みのファイルを確認してください。すべてのコントリビューターでネイティブ読み込みが検証済みで、かつ CLAUDE.md 系のファイルによって無効化されていない場合は、ブリッジは不要です。それ以外の場合は、CLAUDE.md の先頭で @AGENTS.md を読み込む（その下に Claude 専用の内容を記載する）か、CLAUDE.md → AGENTS.md のシンボリックリンクを使用してください。

品質ゲート

PRD と仕様の品質

• 問題の説明と根拠が明確である
• 担当者と成功基準が明記されている
• 受け入れ基準が測定可能である
• 指標に計算式、期間、出典がある
• リスク、ロールアウトのゲート、ロールバック条件が明示されている

AI 機能の品質

• ベースラインとなる代替案が文書化されている
• 構築前に評価目標とデータセット計画が定義されている
• 権限、プロンプトインジェクション、データ流出のリスクが対処されている
• モニタリング、インシデント対応、キルスイッチが明記されている

プロジェクトコンテキストの品質

• ファイルパスとコマンドがリポジトリと一致している
• ガイダンスが適切なツールの場所に割り当てられている
• シークレットや機密データが含まれていない
• 共通の指示とツール固有の指示が矛盾していない

ナビゲーション

リファレンス — コア（最初に読み込む）

• references/agentic-coding-best-practices.md — エージェントを考慮した執筆ルール。仕様書やコンテキストファイルに関する作業では読み込んでください
• references/requirements-checklists.md — PRD、仕様書、コンテキストファイルの品質を確認するゲート用チェックリスト
• references/acceptance-criteria-patterns.md — Gherkin、EARS、表形式、二値チェックのパターン
• references/security-review-checklist.md — AI 機能の権限、インジェクション、データ流出に関するゲート
• references/tool-comparison-matrix.md — Claude Code、Copilot、Cursor、Codex の機能比較
• references/code-graph-spec-patterns.md — コードグラフとマルチリポジトリのコンテキストに関する仕様書のパターン
• references/docs-audit-commands.md — 既存のプロジェクトドキュメントを監査するためのシェルコマンド
• references/operational-guide.md — クイックスタートの入口と一般的なワークフローのレシピ。概要の把握が必要な場合に読み込んでください

参考資料 — 仕様駆動開発とプロンプト作成

• references/spec-driven-dev-landscape.md — GitHub Spec Kit、EARS 記法、Kiro、BMAD-METHOD：パイプラインの構成と検索ステップ。仕様ゲート付きのエージェント型パイプラインで読み込んでください
• references/prompt-engineering-patterns.md — チャットエージェントやコーディングエージェント向けのタスク契約、コンテキストのパッケージ化、出力契約のパターン。仕様書に埋め込むプロンプトを作成する際に、assets/prompting/prompt-playbook.md および assets/prompting/structured-prompt-examples.md と併せて読み込んでください
• references/vibe-coding-patterns.md — プロンプトとエージェントの反復ループ、人間とエージェントの役割分担、衛生管理ルール。迅速なプロトタイピングやバイブコーディングのワークフローで読み込んでください

参考資料 — コードベースのコンテキスト抽出

• references/architecture-extraction.md — 既存のコードベースからエントリーポイント、レイヤー、データフローを抽出するための手順ごとのコマンド。既存情報のない状態で技術仕様書を作成する際に読み込み、その後 assets/architecture-context.md に記入してください
• references/convention-mining.md — コードベースから命名規則、ファイル規則、インポート規則を検出するスクリプト。規約セクションを作成する際に読み込み、その後 assets/conventions-context.md に記入してください
• references/tribal-knowledge-recovery.md — ドキュメント化されていない決定を復元するための、git 履歴やコメントのマイニング手法。レガシーコードベースへのオンボーディング時に読み込み、その後 assets/tribal-knowledge-context.md に記入してください

ステークホルダーとチームのプロセス（product-management が管理）

• product-management の references/prd-review-facilitation.md — レビュー形式の選択、アジェンダテンプレート、フィードバックの分類、反復ワークフロー。PRD レビューを実施する際に読み込んでください

• product-management の references/prd-stakeholder-alignment.md — RACI マッピング、非同期／同期レビューのパターン、対立の解決、意思決定ログのテンプレート。複数のステークホルダーの承認を管理する際に読み込んでください

• product-management の references/pm-collaboration-guide.md — 人間の PM チーム向けのインタビュー報告の構成と PRD の引き継ぎ。ステークホルダーへのインタビューから PRD を作成するタスクで読み込んでください

• product-management の references/traditional-prd-writing.md — 人間のチーム向けの PRD の各セクションに関するガイダンス（Cagan／Wiegers 系）。対象読者がコーディングエージェントではなく PM チームの場合に読み込んでください

• data/sources.json

追加アセット

• assets/metrics/agentic-coding-metrics-template.md — 仕様書やパイロットでコーディングアシスタントの影響を測定する必要がある場合に読み込みます
• assets/key-files-context.md — CLAUDE.md または AGENTS.md にエージェントが把握すべきファイルを記載する場合に読み込みます
• assets/dependencies-context.md — CLAUDE.md または AGENTS.md に外部サービスとインテグレーションを記載する場合に読み込みます

出力形式：仕様成果物の HTML と Markdown

エージェントが読み取るコンテキストファイル（CLAUDE.md、AGENTS.md、.cursor/rules/）には Markdown を使用します。人が一度だけ読む長い成果物（約 100 行を超える PRD、選択肢を比較する探索仕様、インタラクティブな仕様書）には HTML の使用を検討し、受け入れ基準は表またはコードブロックとして抽出できるようにしてください。また、インタラクティブな仕様書の末尾には、エクスポート用の操作部（「JSON／プロンプト／diff としてコピー」）を設けてください。判断表、トレードオフ、レシピについては、references/html-vs-markdown-output.md を参照してください。

境界：docs-ai-prd と docs-codebase

• docs-ai-prd は、要件、仕様、受け入れ基準、コンテキストファイルの戦略を担当します
• docs-codebase は、README、ランブック、API リファレンス、変更履歴、標準となるドキュメントの品質を担当します

エージェントに必要なコンテキストや仕様書の構成を検討している場合は、ここで作業します。リポジトリのドキュメントを書き換える場合は、docs-codebase を使用してください。

関連スキル

• ../docs-codebase/SKILL.md
• ../dev-context-engineering/SKILL.md
• ../dev-workflow-planning/SKILL.md
• ../qa-docs-coverage/SKILL.md
• ../product-management/SKILL.md
• ../software-architecture-design/SKILL.md

学びのループ

過去の判断や落とし穴が関連する場合は、存在すれば learnings.consolidated.md を参照してください。必要な履歴を確認する場合、または利用可能な代替ファイルとしてのみ learnings.md を使用します。それ以外の場合は、どちらも参照しないでください。

適用後、覚えておく価値のあるパターン、防止すべきミス、意外だった分野の知見に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付付きの箇条書きを 1 つ learnings.md に追記してください。SKILL.md 自体は変更しないでください。