| name | dev-spec |
| description | 設計ループ。ユーザーストーリー → UI スケッチ → ユースケース → 実現可能性検証 → PoC 検証 → 横断設計 (docs/design/DESIGN.md) → 機能設計 (docs/design/features/) → 設計チェック → issue ドラフトチェック → GitHub issue 生成 (親子構造) までを対話的に実行し、人間が issue を確認して実装ループへ引き渡す。 「設計フェーズを開始」「要件を整理したい」「計画を立てたい」「ユーザーストーリーを書きたい」 「技術的に実現できるか確認したい」「機能設計を書きたい」「issue に落としたい」などで起動。 docs/design/ の状態から途中再開・特定フェーズの部分実行も可能。 `cli` / `webapp` のプロダクトモード指定で CLI ツール開発時は UI スケッチ等を軽量化できる。 issue 作成後、/dev-impl がそれを 1 件ずつ実装する。 |
| argument-hint | [cli|webapp] [タスク説明] |
dev-spec — 設計ループ
概要
設計ループを回して docs/design/ 配下に設計成果物を生成し、GitHub issue に落として実装ループ (/dev-impl) に引き渡す。成果物は 3 種:
- docs/design/DESIGN.md (横断設計 1 枚): 目的・アーキテクチャ・開発検証コマンド・スキーマ・API 一覧・横断規約
- docs/design/features/<機能名>.md (機能設計): 機能単位の入出力・API・実装配置・エッジケース・テスト方針。正本は常に docs 側で、issue は参照するだけ (ローカルで「この機能の設計はどうなっているか」を AI にも人間にも引ける)
- GitHub issue: 親 1 件 (トラッキング) + 子 N 件 (作業単位)。人間が issue 本文 + 参照 docs だけで着手できることが情報設計の基準
フェーズごとに Feedback (検証手段) が異なる:
- 要件・設計の妥当性 → 人間の確認 (AskUserQuestion) + fresh context の検査 subagent (フェーズ 8・9)
- 技術的実現可能性 → PoC の実行結果 (tech-investigation subagent)。「できるはず」という自己申告のまま設計に進むことを禁止する
モデルガード
このスキルは賢いモデル (Fable / Opus) のセッションで実行する前提。起動時にセッションモデルを確認し、Sonnet / Haiku なら「設計ループは高知能モデルでの実行を推奨します。このまま続行しますか?」と警告してから進める (強制はしない)。
プロダクトモード
設計対象がブラウザ操作型か CLI/ターミナル型かを表す横断設定。フェーズ 2 (UI スケッチ) の要否と E2E 検証の中身を左右する。
| モード | 対象 | 判定ヒント |
|---|
webapp | ブラウザで操作するプロダクト (モバイル Web 含む) | 「画面」「サイト」「Web」「SPA」「ダッシュボード」等の語 |
cli | ターミナルから実行するプロダクト (TUI 含む) | 「CLI」「コマンド」「ツール」「TUI」「パイプ」等の語 |
判定と保持: モードは docs/design/DESIGN.md の 1 行目に <!-- product-mode: cli --> (または webapp) の形式でスタンプする (フェーズ 6 が新規生成時に必ず書き込む)。判定コマンド:
sed -nE 's/.*<!-- product-mode: (cli|webapp) -->.*/\1/p' docs/design/DESIGN.md | head -1
dev-impl はこのスタンプで UI の実機検証 (Playwright E2E) の要否を切り替える。
クイックモードとの合成規則: 各フェーズの有効・無効は「クイックモード列を適用 → cli モード列を適用」の順で決める。どちらか一方でも「スキップ」ならスキップする。フェーズ 4・5 の条件は「フェーズ 0.3 の不確実性確認の結果 (あり/なし)」。
フェーズ一覧
フェーズを開始するときに該当手順書を Read し、その手順に従う。
| # | フェーズ | 手順書 | 出力 | クイックモード | cli モード |
|---|
| 1 | ユーザーストーリー | references/user-story.md | docs/design/USER_STORIES.md | スキップ | 実行 |
| 2 | UI スケッチ | references/ui-sketch.md | docs/design/UI_SKETCH.html | スキップ | スキップ |
| 3 | ユースケース記述 | references/usecase-description.md | docs/design/USECASES.md | スキップ | 実行 |
| 4 | 実現可能性検証 | references/feasibility-check.md | docs/design/FEASIBILITY.md (PoC 計画) | 条件付き実行 | 実行 |
| 5 | PoC 検証 | references/poc-verification.md | FEASIBILITY.md 更新 (PoC 結果) | 条件付き実行 | 実行 |
| 6 | 横断設計 | references/design-doc.md | docs/design/DESIGN.md | 実行 | 実行 |
| 7 | 機能設計 | references/feature-doc.md | docs/design/features/<機能名>.md | 実行 | 実行 |
| 8 | 設計チェック | (本ファイル下記) | 指摘の反映 (docs 修正) | 実行 | 実行 |
| 9 | issue ドラフト + ドラフトチェック | references/issue-template.md | ドラフト (scratchpad) + 指摘の反映 | 実行 | 実行 |
| 10 | GitHub issue 生成 | references/issue-template.md | 親 issue 1 件 + 子 issue N 件 | 実行 | 実行 |
フェーズ 10 はモードに関係なく常に実行する (実装ループは issue を入力にとる)。進捗表示の分母は 10。
ゲート条件 (フェーズ 6 の開始条件)
FEASIBILITY.md に blocker=true の未解決 PoC 計画が残っている間は、フェーズ 6 (設計書生成) に進んではならない。判定はプロンプト遵守ではなく次のコマンドで機械的に行う:
rg -n 'POC_STATUS:.*blocker=true.*status=unresolved' docs/design/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 の先頭トークン群のうち、cli / webapp に完全一致するものはプロダクトモードとして消費し、残りをタスク説明とする。タスク説明が無ければ事前の会話から推論し、それも不明なら「どのようなタスクの設計を行いますか?」と質問する。
既存の docs から復元できる項目は質問しない。 docs/design/DESIGN.md があればプロダクトモードはスタンプから復元する。トークン指定も復元もできない場合だけ、タスク説明と会話履歴から推論し、推論結果を推奨ラベル ((推論) + 根拠 1 行) にして AskUserQuestion で確認する (確定済みなら呼ばない)。
0.2 既存ドキュメントの確認と開始点の決定
docs/design/ 配下の既存成果物 (USER_STORIES.md / UI_SKETCH.html / USECASES.md / FEASIBILITY.md / DESIGN.md / features/) と、GitHub 上の親 issue (tracking ラベル) を確認する (先に gh auth status を確認し、未認証なら issue 関連の判定はスキップして「フェーズ 10 までに認証が必要」と伝える)。
旧構成の成果物 (DESIGN_DETAIL_APP.md / DESIGN_DETAIL_INFRA.md / DOMAIN_MODEL.md / TODO.md) を見つけたら、本スキルの対象外であることを伝え、「新構成 (DESIGN.md 1 枚 + features/) で設計し直す / 中止」を確認する。旧成果物は読み取りの参考にはするが更新しない。
途中まで存在する場合は「続きから (推奨) / 最初から / 既存を更新」を AskUserQuestion で確認する。「続きから」の再開フェーズは次の表で決める (存在する成果物のうち最も下流のものを見る):
| 最も下流の既存成果物 | 再開フェーズ |
|---|
| USER_STORIES.md | 2 (UI スケッチ)。cli モードでは 3 |
| UI_SKETCH.html | 3 (ユースケース) |
| USECASES.md | 4 (実現可能性) |
| FEASIBILITY.md (blocker=true が unresolved) | 5 (PoC 検証) |
| FEASIBILITY.md (全件解決済み) | 6 (横断設計) |
| DESIGN.md | 7 (機能設計)。features/ 各ファイルの「対象 UC」と USECASES.md の UC 一覧を突合し、全 UC がカバー済みなら 8 (USECASES.md が無い構成では人間に確認する) |
GitHub に親 issue (tracking) がある | 9 (ドラフトを docs から再生成) → 10。ドラフトはセッション固有の scratchpad にしか無く、10 単独では突き合わせの比較元が無い |
更新モードでは既存ドキュメントを読み取って差分のみ更新し、ファイル先頭に変更履歴コメント (<!-- 変更履歴 [YYYY-MM-DD]: 要約 -->) を追記する (DESIGN.md ではスタンプ行を押し出さず 1 行目に保つ)。概念の追加・削除を含む更新では該当節だけの局所 Edit にせず全文を読み直して書き直し、更新後はフェーズ 8 (設計チェック) を再実行する。
0.3 モード選択
AskUserQuestion({
questions: [{
question: "設計ループの回し方を選んでください",
header: "モード",
options: [
{ label: "フルコース", description: "ユーザーストーリー〜issue 生成まで全フェーズ (1〜10)。新規プロダクト・大きい機能向け" },
{ label: "クイック", description: "タスク説明から設計書 + issue を直接生成 (6〜10)。技術的な不確実性がある場合のみ実現可能性検証 + PoC (4〜5) を先に通す" }
],
multiSelect: false
}]
})
クイック選択時は、まず Claude 自身がタスク説明と会話履歴から不確実性候補 (未経験ライブラリ / 外部 API 連携 / 性能・スケール懸念 / 新しいプラットフォーム機能) を走査して列挙し、その候補を提示した上で「これらを含め、成立するか未検証の技術要素はありますか?」と AskUserQuestion で確認する (人間の記憶だけに頼らない)。あればフェーズ 4 → 5 を実行してから 6 へ、なければ 6 から開始する (この「不確実性なし」の確認が、ゲート条件の「FEASIBILITY.md 無し」通過の根拠になる)。
部分実行
依頼が特定フェーズだけを指す場合 (例: 「ユースケースを詳細化したい」「機能設計だけ書き直したい」「issue を作り直したい」) は、全フェーズを回さず該当フェーズの手順書だけを Read して実行する。ただし対象にフェーズ 6 が含まれる場合は、実行前に必ず「ゲート条件」の判定コマンドを実行する。 docs を修正する部分実行の後は、フェーズ 8 (設計チェック) → 9 (ドラフト再生成 + ドラフトチェック) → 10 の順で issue に反映する (フェーズ 10 の突き合わせが本文差分を検出して貼り直す)。対象がフェーズ 2 (UI スケッチ) で cli モードなら「cli モードでは UI スケッチは対象外です」と案内して終了する。
各フェーズの進め方
- 進捗を表示する。スキップしたフェーズは
⊘ で表示し番号は振り直さない:
📍 設計ループ [n/10]
├─ ✓ user-story（完了）
├─ ⊘ ui-sketch（cli モードのためスキップ）
├─ ▶ usecase-description（実行中）
└─ ○ ...
- 手順書を Read し、手順に従って実行する
- フェーズ完了後、AskUserQuestion で「次へ進む / ここで終了」を確認する
- ユーザーが修正内容を入力した場合は反映して再承認を取る (承認されるまで繰り返す)
- フェーズ 6・7 では、プロダクト判断が要る点をその場で AskUserQuestion で確認しながら書く (独立したインタビューフェーズは無い。聞き方の基準は各手順書の「記入基準」)
フェーズ 8: 設計チェック (fresh context)
docs が完成した時点で、書き手と別コンテキストの subagent に全文を突合させる。書き手自身は「定義したつもり」バイアスで漏れ・矛盾を検出できないため。issue 生成の前に行う — 設計の穴は issue 化してから見つかるほど手戻りが大きい。
general-purpose subagent を model: "opus" 明示で 1 本起動する (機能設計書が 8 本を超える場合は機能ごとに分担させて並列 fan-out し、横断の整合は親がまとめる)。指示文に含める内容:
docs/design/USECASES.md (あれば)・docs/design/DESIGN.md・docs/design/features/*.md を全文 Read し、次を検査して指摘だけを返せ (修正はしない):
- 落とし漏れ: USECASES.md の各 UC・各規則 (BR) が、いずれかの機能設計書でカバーされているか
- 矛盾: 機能設計書どうし、および DESIGN.md との食い違い (スキーマと入出力、API 一覧と各機能の API 節)
- 未定義・参照切れ: 使われている用語・テーブル・エンドポイント・節参照に定義があるか。「後述」「別途定義」のまま宙に浮いた参照が無いか
- エッジケースの妥当性: 明らかに起こるのに決定が書かれていないエッジケース
- 開発・検証コマンドの実在: DESIGN.md「開発・検証コマンド」が現リポジトリで実行可能か (可能なら実行して確かめる)
出力: [severity] 該当箇所 / 問題の一文 / 修正案の一文 (severity: high = 実装が詰まる / medium = 曖昧さが残る / low = 可読性)
結果の分岐 (最大 2 周): high があれば該当 docs を修正して再実行。2 周しても残る high は人間に提示して判断を仰ぐ。high が無ければ (medium/low は反映するか判断してから) フェーズ 9 へ。subagent がエラーの場合は未検査のまま進まず、「再試行 / チェックなしで続行 / 中止」を AskUserQuestion で確認する。
フェーズ 9: issue ドラフト + ドラフトチェック
references/issue-template.md を Read し、テンプレートに従って親 1 件 + 子 N 件のドラフトを scratchpad にファイルとして書き出す (まだ GitHub に作らない)。再実行時 (issue への反映・別セッションからの再開) もドラフトは docs から再生成する — 前セッションの scratchpad は残っていない。作業単位の切り方: 1 issue = 独立して検証可能な 1 単位 (機能 1 つ、または機能を構成する縦切りの 1 段)。依存は最小限にし、並行して着手できる形を優先する。
全ドラフトが揃ったら、general-purpose subagent (model: "opus" 明示、fresh context) を 1 本だけ起動し、親 + 子の全ドラフトを一括で検査させる (issue ごとに個別起動しない — 依存の整合と相互の重複・漏れはセット全体を見ないと検査できない)。検査観点は issue-template.md「ドラフトチェックのチェックリスト」の 5 項目を指示文に転記し、機能設計書と DESIGN.md のパスを渡して照合させる。出力形式はフェーズ 8 と同じ。
分岐も同じ (最大 2 周): high は修正して再実行、2 周で残れば人間に提示、無ければフェーズ 10 へ。
フェーズ 10: GitHub issue 生成
references/issue-template.md の「issue 作成手順」に従う。要点:
-
docs をコミットする: docs/design/ 配下の成果物 (DESIGN.md / features/ ほか。ただし docs/PENDING_REVIEW.html は対象外 — dev-impl が管理する) の変更を Conventional Commit でコミットする (コミット実行の委譲は ~/.claude/rules/core/orchestration.md に従う)。/dev-impl は origin から切ったブランチで docs を読むため、実装開始前にこのコミットの push が必要 — 手順 4 の案内に含める
-
作成前に人間の同意を取る (GitHub への書き込みなので):
AskUserQuestion({
questions: [{
question: "issue を作成してよいですか? (ドラフトチェック済み)",
header: "issue 作成",
options: [
{ label: "作成", description: "<owner/name> に子 issue <n> 件 + 親 issue 1 件を作成し、sub-issue として紐付ける" },
{ label: "ドラフトを見せて", description: "ドラフト全文を表示してから再確認" },
{ label: "中止", description: "ここで終了 (docs とドラフトは残る。issue は作成しない)" }
],
multiSelect: false
}]
})
- 手順書どおり作成する: ラベル用意 → 既存 issue との突き合わせ (冪等) → 親の特定/作成 → 子を依存順に作成 → sub-issue 紐付け → 親本文の確定
- 結果を報告し、次を案内する:
✓ issue を作成しました: 親 #<番号> + 子 <n> 件 (新規 <a> / 更新 <b> / スキップ <c>)
GitHub で issue をざっと確認し、docs のコミットを push してください (/dev-impl は origin の docs を読みます)。問題がなければ実装ループを起動します:
A (推奨): 新しいセッションで起動 — 対象リポジトリで claude を開き /dev-impl を実行
(設計の対話履歴を持ち込まず、クリーンなコンテキストで実装ループが回る)
B: このセッションで続行 — このまま /dev-impl とタイプ
修正したい issue があれば、指摘してください (docs を直してフェーズ 8 → 9 → 10 で issue に反映します)。
実装ループを Skill ツールで自動起動しない — issue を人間が確認して GO を出すことが承認であり、/dev-impl はユーザーが起動する。
完了条件
参照ルール
設計・タスク分解で以下を参照する:
- TDD ルール:
~/.claude/rules/core/tdd.md
- 設計原則:
~/.claude/rules/core/design.md
- テスト方針:
~/.claude/rules/core/testing.md
関連スキル・エージェント
- dev-impl: issue 駆動の逐次実装ループ。フェーズ 10 が issue を作った後、ユーザーが起動する
- tech-investigation (subagent): フェーズ 5 の PoC 検証で並列 fan-out される
- workflow-debate: 設計判断の壁打ちが必要なとき
