spec-drilldown

name	spec-drilldown
description	TRIGGER when: アプリケーション・新機能・CLI・API・画面などの新規作成依頼を受けたとき、実装や plan 作成に着手する前に発火する。ユーザーへの質問で仕様を drilldown し、どのモデルが実行しても同じ成果物を実装できるレベルの詳細仕様書を作ってから実装に進む。明確な bugfix や仕様が既に十分詳細な依頼では使わない。

Spec Drilldown

Goal

作成依頼を受けた時点の要求は通常曖昧である。いきなり実装を始めず、質問によって仕様の曖昧さを削り、どのモデル・どのセッションが実行しても追加質問なしで同じ成果物に到達できる詳細度の仕様書 を作ってから実装フェーズへ進む。

Skip Conditions

以下の場合はこの skill の質問ループを省略してよい:

• 依頼に Exit Criteria をすべて満たす仕様が既に含まれている
• 明確な bugfix・小さな refactoring など、仕様の自由度がほぼない作業
• ユーザーが「質問せずにまず作って」「使い捨てのプロトタイプでよい」と明示した場合
  • この場合も、置いた仮定を成果物と一緒に必ず列挙する

Workflow

1. 要求の把握: 依頼文・既存コード・関連ドキュメントを読み、既に決まっていることを確認する。自分で調べて分かることをユーザーに質問しない
2. 曖昧点の洗い出し: Question Categories に沿って未決事項を列挙し、実装の分岐に影響する順に優先度を付ける
3. 質問ループ: 優先度の高い未決事項から質問する。構造化された質問ツールがあれば使う（Claude Code では AskUserQuestion、1回につき最大4問）。回答を受けて仕様を更新し、Exit Criteria を満たすまで繰り返す
4. 技術検証: 仕様書に記載する技術方式（サービス選定・API・連携手段）の実現可能性を Technical Investigation に従って検証する
5. 仕様書の作成: Exit Criteria を満たしたら Spec Document を作成し、ユーザーへ提示する
6. 承認と実装への接続: ユーザーの承認を得てから plan / 実装へ進む。plan mode を使う場合は仕様書を plan の入力にする

Technical Investigation

仕様書は「どのモデルが実行しても同じ成果物に到達する」ための文書である。未検証の技術前提を仕様書に書くと、実装フェーズでそれが実現不可能と判明したとき、実装モデルが仕様にない回避策を独自に発明し、仕様と成果物が乖離する。これを防ぐため、drilldown 時点で以下を行う:

• 仕様書に記載する技術方式は記載前に実現可能性を検証する。サービスの選定・API の存在・連携手段は、公式ドキュメント・ローカルの SDK/型定義・検証コマンドのいずれかで「その方式が実際に構成可能である」ことを確認してから書く
• training 知識を前提にしない。特にクラウドサービス・外部 SaaS の API は知識カットオフ以降に変わっている前提で、最新の公式ドキュメント（WebSearch/WebFetch）やインストール済み SDK の型定義で現在の仕様を確認する。制約を見つけた場合は、その制約を持たない後継サービス・新機能がないかまで調査してから仕様に採用する （制約だけ見て回避構成を仕様化すると不要な複雑さが仕様に固定される）
• 検証結果と出典を仕様書（Tech Stack / Assumptions）に記載する。出典（ドキュメント URL・確認した型定義のパス・検証コマンドと結果）のない制約・技術方式を仕様書に書かない
• 方式選定を実装フェーズへ保留する場合（「実装時に判断する」）は、選択肢・判断基準・調査方法を仕様書に明記し、実装モデルの自由裁量にしない

Question Categories

質問は下記カテゴリを網羅的に検討し、実装の分岐に影響するものだけ を聞く:

カテゴリ	決めること
目的・ユーザー	誰が何のために使うか、解決したい課題
入出力	入力の形式と具体例、出力の形式と具体例
データ	データモデル、永続化の要否、スキーマ、既存データとの関係
技術スタック	言語、framework、実行環境、依存してよい外部サービス
インターフェース	画面構成・操作フロー、CLI ならサブコマンド/フラグ体系、API ならエンドポイント設計
エラー・エッジケース	異常入力・失敗時の挙動、バリデーション、リトライ
非機能	性能、データ量の規模、認証/認可、並行実行
スコープ	今回やらないこと、将来対応でよいこと

Question Guidelines

• open-ended な「どうしますか?」ではなく、推奨案を含む選択肢を提示する。推奨は先頭に置き "(Recommended)" を付ける
• 「この回答で実装のどの分岐が決まるか」を説明できない質問はしない
• 既存コードの慣習やライブラリの有無など、調査すれば決まることを質問しない
• 1回の質問セットは最大4問に絞り、回答が次の質問に影響するものは次のループに回す
• 質問ループは通常2〜3往復で収束させる。収束しない場合は、残りを仮定として仕様書に明示する方式へ切り替えてよいかをユーザーに確認する

Exit Criteria

仕様が完成したと言えるのは以下をすべて満たすとき。1つでも欠けるなら質問するか、ユーザーの許可を得た明示的な仮定で埋める:

• 入力と出力が具体例付きで定義されている
• 永続化するデータがあるなら、データモデル/スキーマが確定している
• 技術スタックと実行環境が確定している
• 仕様書に記載した技術方式（サービス・API・連携手段）の実現可能性が出典付きで検証されている（Technical Investigation 参照）
• 主要なエラー・エッジケースの挙動が定義されている
• スコープ外の項目が明記されている
• 検証可能な受け入れ条件（Acceptance Criteria）が列挙されている
• この仕様書だけを渡された別のモデルが、追加質問なしで同等の機能を実装できると言える

Spec Document

• 保存先: 対象リポジトリに仕様書の慣習があればそれに従い、なければ docs/spec/<slug>.md
• 構成:
  • Overview（目的・ユーザー）
  • Inputs & Outputs（具体例付き）
  • Data Model
  • Tech Stack
  • Interface（UI/CLI/API）
  • Error Handling
  • Non-functional Requirements
  • Out of Scope
  • Acceptance Criteria
  • Assumptions（ユーザーの許可を得て仮定で埋めた項目）
• 実装完了までの間に仕様変更が発生したら、会話内だけで処理せず仕様書本体を更新する

Prohibitions

• 仕様書の承認前に実装コードを書き始めることを禁じる
• 未決事項を暗黙に仮定して埋めることを禁じる。仮定する場合は Assumptions として仕様書に明示し承認を得る
• 1回の質問セットで5問以上を投げること、同じ内容を言い換えて再質問することを禁じる
• Exit Criteria を満たさないまま「仕様は十分」と判断することを禁じる

Completion

• 完了条件は「質問した」ことではなく、承認された Spec Document が存在する こと
• 実装フェーズへ進むときは仕様書のパスを報告する
• 実装完了時は Acceptance Criteria との対応（満たしたもの / 満たしていないもの）を報告する