tomevault-io APD Phase 1: Spec — 仕様書の生成
APDフレームワークにおけるSpecフェーズの担当エージェントとして、Design文書からSpec（詳細仕様書）を生成する。
Phase 1は「人間の時間」であり、AIがドラフトを生成し、人間がサマリーと確認依頼箇所だけレビューする。
事前準備
以下のファイルを読み込む:
- CLAUDE.md — プロジェクト設定（デフォルトSpecフォーマット、エスカレーションポリシー等）を確認
docs/apd/design/product-design.md— Design文書を読み込むdocs/apd/specs/*.md— 既存Specがあれば読み込むdocs/apd/decisions/*.md— 既存Decision Recordsがあれば読み込む- アクティブサイクル —
docs/apd/cycles/の最新ファイルを読み込み、トリガー種別を確認
モード判定
ユーザーの指示またはサイクル定義のトリガー種別から、実行モードを判定する:
- full — 初回フルSpec生成（
new_productトリガー時） - add — 機能追加Spec（
feature_additionトリガー時） - bugfix — バグ修正Amendment（
bug_fixトリガー時）
不明な場合はユーザーに確認する。
モード: full（初回フルSpec生成）
スコーピング
Design文書の What セクションに記載された全機能を確認し、ユーザーと対話して今回のサイクルのスコープを決定する:
- 全機能を一覧化し、今回のスコープ と スコープ外（後続サイクルで実装） に分類する提案を行う
- ユーザーの判断を仰ぎ、スコープを確定する
- スコープ外に分類された機能は
docs/apd/todo.mdにToDoとして記録する（起源:Phase 1 Spec生成中（スコーピング）、経緯: スコープ外とした理由） - 確定したスコープ内の機能についてのみSpecを生成する
生成ルール
- スコープ内の機能について Spec を作成する
- What Not に含まれるものは絶対に Spec に入れない
- 各Specは以下を含む:
spec_id: コンテキスト略称 + 連番（例: OM-001）- ユーザーストーリー（誰が・何を・なぜ）
- 受け入れ条件（Given/When/Then形式）
- UI記述またはモック指示（該当する場合）
- コンテキスト境界の定義（inputs / outputs / dependencies）
- テスト戦略（AC Coverageテーブル: 各ACに対するテスト種別と内容）
- 成果物プレビュー記述（生成すべきプレビュー種別と方向性。該当する場合）
- コンテキスト間のデータフローを特定し、
docs/apd/specs/_cross-context-scenarios.mdとしてまとめる - 判断が必要だった箇所は Decision Record のドラフトを作成する
出力
- Specファイル群 —
docs/apd/specs/ディレクトリにMarkdown形式（YAML frontmatter付き）で書き出す - Exit Criteriaチェックリスト（下記参照）
- 確認依頼リスト（下記参照）
- Decision Recordドラフト — 判断が発生した場合、
docs/apd/decisions/D-{NNN}.mdに書き出す
モード: add（機能追加Spec）
追加ルール
- 既存Specとの整合性を確認し、矛盾があれば報告する
- 新規Specは新ファイルとして作成する（既存ファイルは上書きしない — Immutable原則）
- 既存Specの修正が必要な場合は Amendment として作成する（
docs/apd/specs/{context}.v{N}.A-{NNN}.md） - コンテキスト間データフローに影響がある場合、
_cross-context-scenarios.mdのAmendmentも作成する
出力
fullモードの出力に加え:
- 既存Specへの影響分析
- Amendment が必要な既存Specのリスト
モード: bugfix（バグ修正Amendment）
トリアージ
まず原因を判定する:
- Spec起因（仕様漏れ・曖昧さ）→ Spec Amendment を作成
- Execute起因（実装がSpecと合っていない）→ 「Execute起因です。実装修正のみで対応可能です。
/apd:buildで修正してください」と報告
Spec起因の場合の出力
- Amendment —
docs/apd/specs/{context}.v{N}.A-{NNN}.md - 影響を受ける他のSpecの分析
- Decision Recordドラフト（仕様判断が必要な場合）
技術選定（Decision Records）
Spec生成と並行して、主要な技術選定についてDecision Recordを作成し、ユーザーの判断を仰ぐ。 技術選定はPhase 2（Build）の前提条件となるため、Phase 1で確定させる。
判断が必要な技術選定の特定
以下の領域について、CLAUDE.mdで既に確定していない項目を洗い出す:
- プログラミング言語 / ランタイム
- フレームワーク / ライブラリ
- ビルドツール / バンドラー
- データベース / ストレージ
- インフラストラクチャ / デプロイ
- その他プロジェクト固有の重要な技術選択
Decision Record の生成
未確定の技術選定ごとに docs/apd/decisions/D-{NNN}.md を作成する:
phase: specを設定する- 各Optionには以下のトレードオフを明記する:
- メリット / デメリット
- 学習コスト / エコシステムの成熟度
- プロジェクト要件との適合性
- 将来の拡張性への影響
- AI Recommendationを付記してよいが、決定権は人間にある
ユーザーへの提示と承認
Decision Recordドラフトを全て提示し、各項目について decision と reason の記入を求める。
重要: 全てのDecision Recordにユーザーの判断が記入されるまで、Human Checkpoint 1を完了できない。
CLAUDE.mdで確定済みの場合
CLAUDE.mdで技術スタックが明示的に指定されている場合、Decision Recordの生成をスキップしてよい。 ただし「他に検討すべき技術選択はありますか？」とユーザーに確認する。
共通出力: Exit Criteriaチェックリスト
以下の充足状況を表形式でサマリーする:
| Exit Criteria | 状態 | 備考 |
|---|---|---|
| 全機能にSpecが存在する | ✅/⚠️/❌ | |
| 各Specにユーザーストーリーがある | ✅/⚠️/❌ | |
| 各Specに受け入れ条件がある | ✅/⚠️/❌ | |
| 各SpecにUI記述がある（該当時） | ✅/⚠️/❌ | |
| コンテキスト境界が定義されている | ✅/⚠️/❌ | |
| コンテキスト間データフローが特定されている | ✅/⚠️/❌ | |
| 各Specにテスト戦略（AC Coverage）がある | ✅/⚠️/❌ | |
| 各Specに成果物プレビュー記述がある（該当時） | ✅/⚠️/❌ | |
| Decision Recordが作成されている（判断発生時） | ✅/⚠️/❌ | |
| 技術選定Decision Recordsに全てユーザー判断が記録されている | ✅/⚠️/❌ |
共通出力: 確認依頼リスト
推論で埋めた箇所、自信がない箇所を明示する:
## 確認が必要な箇所
1. [spec_id] [箇所]: [推論内容] ← 確認してください
2. ...
Human Checkpoint 1
Specが完成したら、以下のチェックリストを提示する:
- Exit Criteriaチェックリストが全て ✅ になっているか
- 確認依頼リストの各項目について判断を返したか
- Decision Recordの各判断について decision と reason を記入したか
- 技術選定Decision Recordsの全項目にユーザー判断が記録されているか
- What Not に含まれるものがSpecに紛れ込んでいないか
承認されたら「/apd:build を実行してPhase 2に進んでください（ここから先、人間は基本介入しません）」と案内する。
修正が必要な場合はフィードバックを受けてドラフトを更新する。
Converted and distributed by TomeVault — claim your Tome and manage your conversions.