新機能の仕様策定から実装計画まで一気通貫で進めるワークフロー。ヒアリング→コード探索→計画生成→Codexレビューの全自動パイプライン。implementation-plan.mdとtasks.mdを生成し、実装準備を完了させる。Codexレビュー付き版。
機能実装前に仕様を明確化し、実装計画とタスクリストを生成するスキル。 ヒアリングはオーケストレーターが行い、探索と計画生成は別々のサブエージェントに委譲する。
このスキルが起動されたら、ユーザーへの質問・コード探索・実装の前に、必ず最初に Step 1(specフォルダ + PLANNINGファイル作成)を実行すること。 Step 1 が完了するまで、他の一切のアクションを取ってはならない。
このスキルで生成するimplementation-plan.mdには必ずシステム図(状態マシン図 + データフロー図)を含めること。 ASCII罫線図を優先し、mermaidは補助的に使用する。 システム図がないimplementation-plan.mdは不完全であり、生成完了とみなさない。
計画フェーズ中にAutoCompactが発生すると、コンテキストが要約され意図しない実装が始まる可能性がある。 これを防ぐため、PLANNINGファイルを使用して計画中であることを明示する。
.specs/{nnn}-{feature-name}/PLANNING ファイルが存在する間は計画フェーズ1. specsフォルダ作成 + PLANNINGファイル配置
↓
2. AskUserQuestion形式でヒアリング → hearing-notes.md 書き出し
↓
3. codebase-explorer サブエージェント → exploration-report.md
↓
3.5. (条件付き) 探索後ヒアリング → hearing-notes.md 追記
↓
4. spec-planner サブエージェント → implementation-plan.md + tasks.md
↓
5. Codexレビュー → 修正ループ(自動)
↓
6. ユーザーに提示
↓
7. 実装開始許可後、PLANNINGファイル削除
ヒアリング開始前に、specディレクトリとPLANNINGファイルを作成する。以下の3ブロックを順に実行する。
.specs/ と .specs/archive/ の両方をスキャンし、最大番号+1 をゼロ埋め3桁で $next_num にセットする。
next_num=$(ls -1d .specs/[0-9][0-9][0-9]-* .specs/archive/[0-9][0-9][0-9]-* 2>/dev/null | sed 's|.*/\([0-9]\{3\}\)-.*|\1|' | sort -rn | head -1)
next_num=$(printf "%03d" $(( 10#${next_num:-0} + 1 )))
{feature-name} は実際の機能名(kebab-case)に置き換えてコマンドを発行する。
mkdir -p .specs/${next_num}-{feature-name}
echo "${CLAUDE_SESSION_ID}" > .specs/${next_num}-{feature-name}/PLANNING
mkdir -p .specs/.guard && touch .specs/.guard/${CLAUDE_SESSION_ID}
作成されるディレクトリは例: .specs/003-user-auth。
重要: PLANNINGファイルが存在する間は計画フェーズであり、コードの実装は禁止。
ガード: .specs/.guard/${CLAUDE_SESSION_ID} が存在する間、このセッションでは .specs/ 以外への書き込みがhookによりブロックされる。
ユーザーの要求を受けたら、AskUserQuestion で質問し、結果を .specs/{nnn}-{feature-name}/hearing-notes.md に書き出す。
一度に1-4個の質問をまとめて聞く。
Batch 1: スコープ確認 探索範囲を絞り込み、関係ないコードの読み込みを避けるために確認する。
Batch 2: 技術的詳細 実装計画の精度を高め、既存コードとの整合性を確保するために確認する。
Batch 3: 品質要件 テスト計画とエッジケースの洗い出しに必要な情報を確認する。
質問形式の詳細は references/question-patterns.md を参照。
ヒアリング完了後、テンプレートに沿って結果をファイルに書き出す。
テンプレート: assets/templates/hearing-notes.md
出力先: .specs/{nnn}-{feature-name}/hearing-notes.md
hearing-notes.md を書き出したら、codebase-explorer サブエージェントを起動する。
サブエージェント起動前に、hearing-notes.md の内容から以下を抽出する:
Task tool:
description: "codebase-explorer: {feature-name}"
subagent_type: general-purpose
run_in_background: true
prompt: |
あなたはcodebase-explorerエージェントです。
.specs/{nnn}-{feature-name}/hearing-notes.md を読み込み、
その目的・スコープに基づいてコードベースを探索してください。
## 探索ヒント(オーケストレーターが抽出)
**キーワード**: {hearing-notesから抽出したキーワード5-10個をカンマ区切りで列挙}
**推定対象パス**: {推定したディレクトリ/ファイルパターンを列挙}
**探索の重点**: {新規→類似実装発見 / 既存修正→依存逆引き / リファクタリング→全使用箇所 等}
## 参照スキル
spec-driven-dev-codex:exploration-perspectives
## テンプレート
spec-driven-dev-codex:exploration-report
## 出力先
.specs/{nnn}-{feature-name}/exploration-report.md
{...} はオーケストレーターが hearing-notes.md の内容に基づいて埋める。
TaskOutput:
task_id: "{codebase-explorerのtask_id}"
block: true
timeout: 300000
TaskOutput 受信後、exploration-report.md を読み込み、セクション 8「探索メトリクス」を確認する:
基準チェック:
空セクション検出:
補完探索の実行(品質基準未達の場合のみ、最大 1 回):
Task tool:
description: "codebase-explorer (補完): {feature-name}"
subagent_type: general-purpose
run_in_background: true
prompt: |
あなたはcodebase-explorerエージェントです。
前回の探索レポートが品質基準に達していないため、補完探索を行います。
## 前回のレポート
.specs/{nnn}-{feature-name}/exploration-report.md
## 不足している項目
{具体的な不足項目を列挙}
## 指示
前回のレポートに不足している情報を追加してください。
特に以下に重点を置いてください:
- 不足しているコードスニペットの追加(ファイルを Read して具体的なコードを記載)
- 不足しているセクションの探索と記入
- 探索メトリクスの更新
## 参照スキル
spec-driven-dev-codex:exploration-perspectives
## 出力先
.specs/{nnn}-{feature-name}/exploration-report.md(上書き更新)
TaskOutput:
task_id: "{補完codebase-explorerのtask_id}"
block: true
timeout: 300000
探索の5カテゴリ: アーキテクチャ概要 / 関連コード分析 / 技術的制約・リスク / 変更影響範囲 / テストインフラストラクチャ
詳細は references/exploration-perspectives.md を参照。
exploration-report.md を読み込み、ユーザー判断が必要な論点を抽出する。論点が無ければスキップして Step 4 へ進む。
以下のセクションをスキャンし、ユーザー確認が必要な論点を最大 5 件抽出する:
抽出した論点を exploration-report.md の Section 7「ユーザー判断が必要な論点」に書き戻す(監査証跡)。
論点を重要度順に並べ、上位 4 件 (AskUserQuestion 上限) を 1 ターンで一括聴取する。
AskUserQuestion の回答結果を hearing-notes.md 末尾の ## 探索後ユーザー判断 セクションに追記する:
exploration-report.md が完成したら、spec-planner サブエージェントを起動する。
Task tool:
description: "spec-planner: {feature-name}"
subagent_type: general-purpose
run_in_background: true
prompt: |
あなたはspec-plannerエージェントです。
以下のファイルを読み込み、implementation-plan.md と tasks.md を生成してください。
## 入力
- .specs/{nnn}-{feature-name}/hearing-notes.md
- .specs/{nnn}-{feature-name}/exploration-report.md
## テンプレート
- spec-driven-dev-codex:implementation-plan
- spec-driven-dev-codex:tasks
## 出力先
- .specs/{nnn}-{feature-name}/implementation-plan.md
- .specs/{nnn}-{feature-name}/tasks.md
## 重要
- システム図(状態マシン図 + データフロー図)は必須。省略禁止。ASCII罫線図を優先。
- exploration-report.md の制約・リスクを implementation-plan.md に反映すること。
- implementation-plan.md に "## Definition of Done" セクションを必ず含めること。機能固有の受入条件を具体的に記載すること。
- テスト戦略分析を必ず実施すること。references/test-design-patterns.md に基づき、機能タイプを分類してテストパターンを決定すること。
- テスト要件がある場合、t-wada TDD ベースで tasks.md を構成すること(Red-Green-Refactor サイクル、TODOリスト駆動)。テンプレートの TDD 構成例を参照。
- 変更案セクションの [NEW] には実装骨格(型定義・関数シグネチャ・import文)、[MODIFY] には before/after 形式のコードスニペットを必ず含めること。
TaskOutput:
task_id: "{spec-plannerのtask_id}"
block: true
timeout: 300000
生成した implementation-plan.md を Codex でレビューする。 レビュー結果はファイルに保存し、コンテキストの消費を抑える。
mkdir -p .specs/{nnn}-{feature-name}/plan-review
レビュー結果は .specs/{nnn}-{feature-name}/plan-review/review-{NNN}.md に保存する。
{NNN} は3桁の連番(001, 002, 003...)。
レビュー実行前に、Writeツールで .specs/{nnn}-{feature-name}/plan-review/prompt-{NNN}.txt にレビュー指示文を書き出す。
{NNN} は review-{NNN}.md と同じ連番。再レビュー時はインクリメントする。
prompt-{NNN}.txt の内容:
以下の実装計画をレビューしてください。
【重要】ファイルの作成・編集は一切行わないでください。レビュー結果は標準出力のみで回答してください。
レビュー対象: .specs/{nnn}-{feature-name}/implementation-plan.md
レビュー観点:
1. 仕様の曖昧さ・抜け漏れはないか
2. 実装可能性に問題はないか
3. エッジケースは考慮されているか
4. ファイル構成は妥当か
5. 全体アーキテクチャとの整合性はあるか
問題がなければ「問題なし」と回答してください。
問題があれば具体的な指摘と改善案を提示してください。
プロンプトファイルを cat で読み込んで codex exec に渡し、結果を .specs/ 配下に出力する。
codex exec --cd "$PWD" --dangerously-bypass-approvals-and-sandbox "$(cat .specs/{nnn}-{feature-name}/plan-review/prompt-{NNN}.txt)" > .specs/{nnn}-{feature-name}/plan-review/review-{NNN}.md
レビュー観点の詳細は references/review-criteria.md を参照。
生成したファイルをユーザーに提示:
.specs/{nnn}-{feature-name}/ を明示.specs/{nnn}-{feature-name}/hearing-notes.md.specs/{nnn}-{feature-name}/exploration-report.md.specs/{nnn}-{feature-name}/implementation-plan.md.specs/{nnn}-{feature-name}/tasks.mdユーザーが修正を要求した場合は Step 5 のループに戻る。
計画が完了したら、ユーザーに以下を案内する:
ユーザーへの案内:
実装を開始するには、以下のコマンドを実行してください:
rm .specs/.guard/${CLAUDE_SESSION_ID} .specs/{nnn}-{feature-name}/PLANNING
注意: ガードファイルはhookにより自動削除がブロックされる。必ずユーザーが手動で削除すること。 注意: ガード解除前に実装コードを書いてはならない。
.specs/
└── {nnn}-{feature-name}/
├── PLANNING # 計画中は存在、実装開始時に削除
├── hearing-notes.md # ヒアリング結果(オーケストレーター生成)
├── exploration-report.md # 探索レポート(codebase-explorer 生成)
├── implementation-plan.md # 実装計画(spec-planner 生成)
├── tasks.md # タスクリスト(spec-planner 生成)
└── plan-review/ # Codexレビュー結果
├── review-001.md
├── review-002.md
└── ...
{nnn} は .specs/ 内の既存フォルダ数に基づく3桁の連番(001, 002, 003...)
{feature-name} はケバブケースで命名(例: 001-user-authentication, 002-block-button)