dev-spec

name	dev-spec
description	設計ループ。ユーザーストーリー → UI スケッチ → ユースケース → 実現可能性検証 → PoC 検証 → DDD モデリング → 概要/詳細設計 (DESIGN.md / DESIGN_DETAIL_APP.md / DESIGN_DETAIL_INFRA.md) → 深掘りインタビュー → 検証手順補完 → TODO.md 生成までを対話的に実行し、承認ゲートで実装ループ (/dev-impl) へ引き渡す。 「設計フェーズを開始」「要件を整理したい」「計画を立てたい」「ユーザーストーリーを書きたい」 「技術的に実現できるか確認したい」「TODO.md を作りたい」「DESIGN.md を深掘りしたい」などで起動。 docs/ の状態から途中再開・特定フェーズの部分実行も可能。
argument-hint	[タスク説明]

dev-spec — 設計ループ

概要

設計ループを回して docs/ 配下に設計成果物を生成し、承認ゲートを経て実装ループ (/dev-impl) に引き渡す。最終成果物は次の 4 ファイル:

• docs/DESIGN.md (概要設計): 共通 (目的・スコープ・ゴール・全体構成図・技術選定) + アプリ概要 + インフラ概要の 3 章構成
• docs/DESIGN_DETAIL_APP.md (アプリ詳細設計): セットアップ・API・スキーマ・シーケンス・エラー実装・UX・検証手順 (ローカル / CI 系)
• docs/DESIGN_DETAIL_INFRA.md (インフラ詳細設計): リソース・IaC・CI/CD (GitHub Actions 固定)・監視・シークレット・検証手順 (環境依存系)
• docs/TODO.md: TDD 準拠の実装タスクリスト

フェーズごとに Feedback (検証手段) が異なる:

• 要件・設計の妥当性 → 人間の承認 (AskUserQuestion)
• 技術的実現可能性 → PoC の実行結果 (tech-investigation subagent)。「できるはず」という自己申告のまま設計に進むことを禁止する

モデルガード

このスキルは賢いモデル (Fable / Opus) のセッションで実行する前提。起動時にセッションモデルを確認し、Sonnet / Haiku なら「設計ループは高知能モデルでの実行を推奨します。このまま続行しますか?」と警告してから進める (強制はしない)。

フェーズ一覧

フェーズを開始するときに該当手順書を Read し、その手順に従う。

#	フェーズ	手順書	出力	クイックモード
1	ユーザーストーリー	references/user-story.md	docs/USER_STORIES.md	スキップ
2	UI スケッチ	references/ui-sketch.md	docs/UI_SKETCH.md	スキップ
3	ユースケース記述	references/usecase-description.md	docs/USECASES.md	スキップ
4	実現可能性検証	references/feasibility-check.md	docs/FEASIBILITY.md (PoC 計画)	条件付き実行
5	PoC 検証	references/poc-verification.md	FEASIBILITY.md 更新 (PoC 結果)	条件付き実行
6	DDD モデリング	references/ddd-modeling.md	docs/GLOSSARY.md, docs/DOMAIN_MODEL.md	スキップ
7	概要/詳細設計	references/analyzing-requirements.md	docs/DESIGN.md, docs/DESIGN_DETAIL_APP.md, docs/DESIGN_DETAIL_INFRA.md	実行
8	深掘りインタビュー	references/interview.md	DESIGN / DETAIL 更新	実行
9	検証手順の確認と補完	references/verification-review.md	DESIGN / DETAIL 更新	実行
10	TODO.md 生成	references/todo-generation.md	docs/TODO.md	実行
11	承認ゲート	(本ファイル下記)	—	実行

ゲート条件 (フェーズ 7 の開始条件)

FEASIBILITY.md に blocker=true の未解決 PoC 計画が残っている間は、フェーズ 7 (設計書生成) に進んではならない。判定はプロンプト遵守ではなく次のコマンドで機械的に行う:

rg -n 'POC_STATUS:.*blocker=true.*status=unresolved' docs/FEASIBILITY.md

• 1 件以上ヒット → フェーズ 5 (PoC 検証) へ戻る
• 0 件 → 通過
• FEASIBILITY.md 自体が無い → フェーズ 0.3 で「不確実性なし」を確認済みの場合のみ通過。未確認ならフェーズ 0.3 の不確実性確認に戻る

POC_STATUS 行の書式は references/poc-verification.md で定義する (フェーズ 4 が status=unresolved で書き、フェーズ 5 が更新する)。

フェーズ 0: ルーティング

0.1 タスク説明の取得

$ARGUMENTS があればタスク説明として使用。なければ事前の会話から推論し、それも不明なら「どのようなタスクの設計を行いますか?」と質問する。

0.2 既存ドキュメントの確認と開始点の決定

docs/ 配下の既存成果物 (USER_STORIES.md / UI_SKETCH.md / USECASES.md / FEASIBILITY.md / GLOSSARY.md / DOMAIN_MODEL.md / DESIGN.md / DESIGN_DETAIL_APP.md / DESIGN_DETAIL_INFRA.md / TODO.md) を確認する。

旧形式の単一 docs/DESIGN_DETAIL.md を見つけたら、references/todo-generation.md のフォールバック A (APP / INFRA への分割移行) を案内してから続行する。

• DESIGN.md / DESIGN_DETAIL_APP.md / DESIGN_DETAIL_INFRA.md / TODO.md が揃い、TODO.md 先頭に承認スタンプ (<!-- dev-spec:approved ... -->) がある → 「設計は完成しています。実装ループは /dev-impl を起動してください。設計を修正したい場合は更新モードで再実行してください」と案内して終了
• 4 点は揃っているが承認スタンプが無い → 未承認。フェーズ 11 (承認ゲート) から再開する
• 途中まで存在する → 「続きから (推奨) / 最初から / 既存を更新」を AskUserQuestion で確認。「続きから」の再開フェーズは次の表で決める (存在する成果物のうち最も下流のものを見る):

最も下流の既存成果物	再開フェーズ
USER_STORIES.md	2 (UI スケッチ)
UI_SKETCH.md	3 (ユースケース)
USECASES.md	4 (実現可能性)
FEASIBILITY.md (blocker=true が unresolved)	5 (PoC 検証)
FEASIBILITY.md (全件解決済み)	6 (DDD)。クイックモードなら 7
GLOSSARY.md / DOMAIN_MODEL.md	7 (設計書生成)
DESIGN.md + DESIGN_DETAIL_APP.md + DESIGN_DETAIL_INFRA.md	8 (深掘り)。深掘り済みが明らかなら 9
TODO.md (承認スタンプ無し)	11 (承認ゲート)

• 何もない → モード選択へ

更新モードでは既存ドキュメントを読み取って差分のみ更新し、ファイル先頭に変更履歴コメント (<!-- 変更履歴 [YYYY-MM-DD]: 要約 -->) を追記する。

0.3 モード選択

AskUserQuestion({
  questions: [{
    question: "設計ループの回し方を選んでください",
    header: "モード",
    options: [
      { label: "フルコース", description: "ユーザーストーリー〜DDD まで全フェーズ (1〜11)。新規プロダクト・大きい機能向け" },
      { label: "クイック", description: "タスク説明から設計書 + TODO を直接生成 (7〜11)。技術的な不確実性がある場合のみ実現可能性検証 + PoC (4〜5) を先に通す" }
    ],
    multiSelect: false
  }]
})

クイック選択時は、まず Claude 自身がタスク説明と会話履歴から不確実性候補 (未経験ライブラリ / 外部 API 連携 / 性能・スケール懸念 / 新しいプラットフォーム機能) を走査して列挙し、その候補を提示した上で「これらを含め、成立するか未検証の技術要素はありますか?」と AskUserQuestion で確認する (人間の記憶だけに頼らない)。あればフェーズ 4 → 5 を実行してから 7 へ、なければ 7 から開始する (この「不確実性なし」の確認が、ゲート条件の「FEASIBILITY.md 無し」通過の根拠になる)。

部分実行

依頼が特定フェーズだけを指す場合 (例: 「ユースケースを詳細化したい」「DESIGN.md を深掘りしたい」「TODO だけ作り直したい」) は、全フェーズを回さず該当フェーズの手順書だけを Read して実行する。ただし対象にフェーズ 7 が含まれる場合は、実行前に必ず「ゲート条件」の判定コマンドを実行する (ゲートはどの経路から入っても効かせる)。

各フェーズの進め方

1. 進捗を表示する:

📍 設計ループ [n/11]
   ├─ ✓ user-story（完了）
   ├─ ▶ ui-sketch（実行中）
   └─ ○ ...

2. 手順書を Read し、手順に従って実行する
3. フェーズ完了後、AskUserQuestion で「次へ進む / ここで終了」を確認する
4. ユーザーが修正内容を入力した場合は反映して再承認を取る (承認されるまで繰り返す)

フェーズ 11: 承認ゲート (設計 → 実装の遷移)

設計ループと実装ループの境界。人間の明示承認がないと越えられない Stop であり、Claude が自律的に実装ループを開始することは禁止。Skill ツール経由の起動では dev-impl のモデル指定 (model: sonnet) が適用されないため、実装ループの起動は必ずユーザーが行う。

11.1 サマリー表示

✓ 設計ループ完了

生成されたファイル:
- docs/DESIGN.md              (概要設計)
- docs/DESIGN_DETAIL_APP.md   (アプリ詳細設計)
- docs/DESIGN_DETAIL_INFRA.md (インフラ詳細設計)
- docs/TODO.md                (タスクリスト、全 n フェーズ)
- docs/FEASIBILITY.md         (PoC 結果: verified x 件 / fallback 採用 y 件)

FEASIBILITY.md を作成していない場合 (クイックモードで不確実性なし) は、その行を省略する。

11.2 最終承認

AskUserQuestion({
  questions: [{
    question: "設計成果物を確認してください。実装ループへ進んでよいですか?",
    header: "設計承認",
    options: [
      { label: "承認", description: "実装ループの起動方法を案内して終了" },
      { label: "修正", description: "修正内容を指示して該当フェーズへ戻る" },
      { label: "中止", description: "ここで終了 (成果物は残る)" }
    ],
    multiSelect: false
  }]
})

「修正」の戻り先は指摘内容で決める: ゴール・検証手順 → フェーズ 9、設計内容 → フェーズ 7〜8、タスク分割 → フェーズ 10。戻った後は当該フェーズ以降を再実行し、再度この承認ゲートに来る。

11.3 実装ループへの引き継ぎ案内

承認されたら次の 2 つを行ってこのスキルを終了する (dev-impl を Skill ツールで起動しない):

1. 承認スタンプの書き込み: docs/TODO.md の先頭 (1 行目) に <!-- dev-spec:approved YYYY-MM-DD --> を挿入する (既存スタンプがあれば日付を更新)。dev-impl は起動時 (Step 1 構造ゲート) にこのスタンプを機械チェックし、無ければ実装に入らない
2. 以下を表示する:

✓ 設計が承認されました。実装ループは以下のいずれかで開始してください:

A (推奨): 新しいセッションで起動
   claude を新しく開いて /dev-impl を実行。
   設計の対話履歴を持ち込まず、クリーンなコンテキストで実装ループが回る。
   dev-impl は model: sonnet 指定なので、起動ターンから Sonnet で実行される。

B: このセッションで続行
   このまま /dev-impl とタイプ。このターンだけ Sonnet に切り替わる。
   (エスカレーション回答後の再開も /dev-impl の再実行で行う)

完了条件

• 対象フェーズがすべて実行された (またはユーザー判断でスキップ)
• blocker=true の PoC 計画がすべて解決済み (verified または fallback 採用)
• 全フェーズ実行時: DESIGN.md / DESIGN_DETAIL_APP.md / DESIGN_DETAIL_INFRA.md / TODO.md が生成され、承認ゲートを通過した
• 承認時: TODO.md 先頭に承認スタンプが書き込まれた

参照ルール

設計・タスク分解で以下を参照する:

• TDD ルール: rules/core/tdd.md
• 設計原則: rules/core/design.md
• コミットルール: rules/core/commit.md

関連スキル・エージェント

• dev-impl: 実装ループ (旧 workflow-autopilot)。承認ゲート通過後にユーザーが起動する
• tech-investigation (subagent): フェーズ 5 の PoC 検証で並列 fan-out される
• workflow-debate: 設計判断の壁打ちが必要なとき