spec

/spec — ガイド付き仕様設計

セッションコンテキスト

今日の日付（仕様書のヘッダーに使用してください。推測しないでください）： !date +%F

既存の仕様書： !ls specs/ 2>/dev/null || echo "The specs/ folder does not exist yet"

---

このスキルは、仕様駆動の手法に沿って有用な仕様書を作成するのに役立ちます。**ここではコードを書きません。**ユーザーが何を作りたいのかを明確にし、定義が不十分な場合は質問し、specs/ に保存できる状態になるまで、セクションごとに仕様書を作成するのがあなたの役目です。

基本方針

仕様書は飾りのドキュメントではありません。後続の実行を導く契約です。仕様が曖昧だと、コードの実装がその場しのぎになります。そのため、このフローは定義フェーズでは意図的に時間をかけ、執筆フェーズでは素早く進めます。

このスキルと同じディレクトリにある template.md を読み、仕様書の全体構成を確認してください。各ステップでこれを活用してください。

コマンドフロー

• 4 つのフェーズを順番に進めてください。フェーズ 2 は決して省略しないでください。質問こそがこのフローの要です。ユーザーが先を急ぎたい場合は、仕様の不備によるコストは後のコード実装時に発生すると伝えてください。（フェーズ 2 が本当に完了した後であれば、フェーズ 3 には簡易ルートがあります。詳細は後述します。）
• 返信は最初のプロンプトと同じ言語で行ってください。たとえば、最初のプロンプトがスペイン語ならスペイン語で、英語なら英語で返信してください。

フェーズ 1 — コンテキストの把握

機能について質問する前に、まずプロジェクトのコンテキストを把握してください。

1. プロジェクトメモリファイルが存在する場合は読み込んでください。CLAUDE.md、AGENTS.md、GEMINI.md、README.md の順に確認し、最初に見つかったファイルで止めてください。これにより、このスキルを実行しているエージェント（Claude Code、Codex、Gemini CLI など）に合わせて適応できます。
2. 上記のセッションコンテキストにある specs/ の一覧を確認し、既存の仕様書と番号の付け方を把握してください。
3. 以前の仕様書がある場合は、直近の 2 つ以上を読んで、プロジェクトの慣例を把握してください。これには、仕様書が書かれている言語や、状態とセクション見出しに使われている正確な表現も含まれます。新しい仕様書は既存のものに合わせる必要があります。

$ARGUMENTS 引数が空の場合は、作りたいものについて、最初の説明を1 文でユーザーに尋ねてください。説明が 1 文に収まらない場合は、それが機能の規模が大きすぎる最初の兆候です。続行する前に、機能を分割することを提案してください。

フェーズ 2 — 質問で明確にする

このコマンドで最も重要なフェーズです。ここでの役割は、曖昧な点を見つけて質問することであり、決めつけることではありません。

質問は一度に3～5個ずつ、ブロックに分けて行います（質問を1つずつ続けてはいけません。相手を疲れさせてしまいます）。各ブロックの後は、回答を待ってから次に進みます。

常に検討する質問のカテゴリ：

• スコープ： 対象に含まれるものと含まれないものは何ですか？機能のどの部分を別の仕様に委ねますか？
• データ： どのような新しい構造を導入しますか？どのように命名しますか？どこに配置しますか？
• 統合： この機能は以前の仕様に依存しますか？既存のものを変更しますか、それとも追加のみですか？
• 永続化： セッション間で保存するものはありますか？どこに保存しますか？バージョン管理はどうしますか？
• UX と状態： 正常に動作しているときはどのように見えますか？失敗したときはどうなりますか？中間状態はありますか？
• リスク： 何が原因で壊れる可能性がありますか？機能が低下した場合はどうなりますか？
• 確定済みの決定事項： ユーザーがすでに決定しており、再検討したくないことはありますか？

質問の表現方法：

• 自由回答形式ではなく、具体的な質問をしてください。❌「永続化について、どのようにお考えですか？」→ ✅「永続化には localStorage、IndexedDB、ディスク上の JSON ファイルのどれを使いますか？」
• 選択肢を示す場合は、2～4個提示し、どれを推奨するかとその理由を明記してください。
• エージェントがネイティブの複数選択式質問ツール（Claude Code の AskUserQuestion など）を利用できる場合は、選択肢を文章で示す代わりに、質問ブロックでそのツールを使ってください。ユーザーは入力する代わりに選択できます。推奨案を最初に置き、推奨であることを明記してください。そのようなツールがない場合は、番号付きの Markdown リストを使ってください。
• 回答によって話が際限なく広がりそうな場合（たとえば「マルチプレイヤー機能も追加したい」など）は、それには独立した仕様が必要であることを伝え、この仕様のスコープから除外するかどうかを尋ねてください。

質問をやめるタイミング：

次の3つの質問に、何も仮定せずに答えられるようになったら、質問をやめてください。

1. どのファイルが作成または変更されますか？
2. 最初の実行可能なステップと最後のステップは何ですか？
3. 機能の完成をどのように検証しますか？

いずれかにまだ答えられない場合は、質問を続けてください。

フェーズ 3 — 仕様を書く

フェーズ 2 が完了したら、どのように書くかを決めます。

必要な情報がすべて揃っている場合 — つまり、フェーズ 2 の3つの質問（変更するファイル、最初と最後の実行手順、完了を確認する方法）に何も仮定せずに答えられる場合は、セクションごとに進めないでください。仕様をすべて書き上げ、ファイルを保存するフェーズ 4 に直接進みます。セクションごとの確認を求めたり、承認用の下書きを先に見せたりしないでください。ユーザーはフェーズ 2 ですでにすべてに回答しており、再度尋ねるのは余計な手間です。ユーザーは保存されたファイルを確認し、必要に応じて変更を依頼します。

情報がまだ不足している場合に限り（ユーザーがフェーズ 2 を途中で切り上げた、回答が曖昧だった、または何かを創作しないと書けないセクションがある場合）、セクションを1つずつ作成し、それぞれを提示して確認を待ってから次に進みます。

どちらの場合も、内容は同じ順序で並べます。

1. ヘッダー（ステータス、依存関係、日付、目的を表す1文）。目的を表す1文は重要です。1文に収まらない場合は、フェーズ 2 に戻ります。
2. スコープ（対象となるものと、対象外のもの）。対象外のものは明示する必要があります。
3. データモデル（実際の名前を使った具体的な構造）。機能で新しいデータを導入しない場合は、このセクションを省略し、その旨を明記します。
4. 実装計画（システムが各ステップ後も機能する、番号付きの手順）。
5. 受け入れ基準（意欲的な目標ではなく、真偽を確認できるチェックリスト）。
6. 決定事項と不採用事項（簡潔な理由を添えます）。
7. 特定されたリスク（該当する場合のみ。関連するリスクがない場合は省略します）。

各セクションの後（セクションごとに進める場合のみ）：

• Markdown 形式で提示します。
• 「このセクションはこのままでよいですか？それとも調整しますか？」と尋ねます。
• ユーザーが変更を依頼した場合は、反映して再度提示します。
• ユーザーが確認してから、次のセクションに進みます。

避けるべきよくある間違い：

• 検証できない受け入れ基準を作成する（「うまく動作すること」など）。
• スコープに含まれない内容を実装計画に入れる。
• ユーザーが確認していないファイル名や構造を想定する。
• 決定事項のセクションを省略する — このセクションは長期的に最も価値があります。

フェーズ 4 — 仕様書を保存する

内容の準備ができたら（必要な情報がすべてそろった場合、またはすべてのセクションが確認された場合）：

1. セッションのコンテキストにある specs/ の一覧から、次の連番を決定します。既存の番号のうち最大のものに 1 を加え、2 桁になるようゼロ埋めします。最後のファイルが 02-powerups.md なら、今回は 03- になります。specs/ が空、または存在しない場合は、01- から始めます。

2. 目的から短いケバブケースのスラッグを生成します（例：levels-and-highscores）。$ARGUMENTS がスラッグである場合については、以下の Arguments を参照してください。

3. **Date:** フィールドには、上記のセッションコンテキストにある日付を使用します。そこから読み取っていない日付を絶対に記入しないでください。

4. すべてのセクションを含めて、ファイルを specs/NN-slug.md に直接書き込みます。書き込みの許可を求めたり、ファイル名が適切かどうか尋ねたりしないでください。最終確認でパスを伝えます。確認を求めるのは、対象ファイルがすでに存在する場合のみです。

5. デフォルトでは状態を Draft（または、このリポジトリの既存の仕様書で使われている同等の語）にします。自動的に Approved にしないでください。ユーザーが再読した後に変更します。

6. ヘッダーに依存関係（**Depends on:** SPEC 01）が記載されている場合は、参照されている各仕様書が実際に specs/ に存在することを確認します。存在しないものがあれば、その旨を伝え、参照切れのまま記述しないでください。

7. 設定ファイルが存在しない場合は、初期設定を作成します。 specs/.spec-config.yml を確認します。存在しない場合は、以下のデフォルト内容で作成します。すでに存在する場合は、そのままにしてください。ユーザーの設定を上書きしてはいけません。

   # spec workflow configuration
   #
   # AutoCreateBranch — controls whether /spec-impl creates the git branch automatically.
   #   true  (default) → /spec-impl creates and switches to spec-NN-slug without asking
   #   false           → /spec-impl asks for [y/N] confirmation before creating the branch
   AutoCreateBranch: true
   

8. ユーザーに以下を伝えます：

   • 作成したファイルのパス。
   • 仕様書は Draft 状態であることを再確認するよう促します。再読したら Approved に変更してください。
   • specs/.spec-config.yml を新しく作成した場合は、ファイルが存在すること、および AutoCreateBranch のデフォルトが true であることを伝えます（ブランチ作成を自分で制御するには false に設定します）。
   • 次のステップ：レビューして承認したら、実装のために /spec-impl NN-slug を実行します。
   • ここで終了します。 この確認の後に、仕様書の実装、コードの記述、その他の作業を提案しないでください。

厳守事項

• このコマンドの実行中にコードを書いてはいけません。 最後に仕様書の .md ファイルのみを書きます。
• 保存後に仕様書の実装を提案してはいけません。 ファイルを書き込んだ時点で作業は完了です。ユーザーは準備ができたら /spec-impl を実行します。
• ユーザーが確認していない判断を決めつけてはいけません。 情報が不足している場合は質問します。質問はフェーズ 2 で行います。
• フェーズ 2 ですでに回答された内容をフェーズ 3 で再質問してはいけません。 情報がそろっている場合は、仕様書全体を作成して保存します。セクションごとの確認は、情報が不足している場合の代替手段であり、デフォルトではありません。
• ユーザーがフェーズ 2 を省略して作業を早めたい場合は、「今の質問が、後の何時間もの手戻りを防ぎます。それでも省略しますか？」と伝えます。ユーザーが希望を貫く場合は、その意向を尊重しますが、仕様書の決定事項のセクションに「詳細な確認を行わずに簡易定義」と記録します。
• 機能の規模が大きすぎる場合（1 文で説明しきれない、システムの 3 領域を超えて関係する、または 4 つ以上の領域で判断が必要な場合）は、続行する前に 2 つ以上の仕様書に分割することを提案します。

質問するときのトーン

率直かつ具体的に質問してください。質問することを謝らないでください。「差し支えなければ……」や「もしかすると……していただけますか？」のような表現は使わないでください。ユーザーは質問してほしいからこそ、このスキルを呼び出しています。質問が複数ある場合は、具体的な質問を1行に1つずつ記載し、回答しやすいように番号を付けてください。

適切な質問ブロックの例：

データモデルを作成する前に、3点確認させてください。

1. 永続化。 localStorage、IndexedDB、ディスク上の JSON ファイルのどれにしますか？ 推奨：データが5MB未満で、クエリが不要なら localStorage です。
2. スキーマのバージョン管理。 フォーマットが変わったときはどうしますか？ 選択肢：（a）キーにバージョンのプレフィックスを付ける、（b）無視して再構築する、（c）読み込み時に移行する。
3. プライバシー。 データは機密情報ですか？ 機密情報の場合、暗号化されていますか？ ログアウト時に削除されますか？

引数

$ARGUMENTS は機能の説明であり、ファイル名ではありません。Phase 1 の出発点として扱い、Phase 4 で目的からスラッグを導き出してください。

例外は1つだけです。$ARGUMENTS がスペースを含まない単一の kebab-case トークン（例：/spec levels-and-highscores）の場合、説明かスラッグか判断がつかないため、スラッグとして使うと同時に、説明の種としても使ってください。確認を求める必要はありません。

引数なしで /spec が呼び出された場合は、1文での説明を尋ねてください。