spec

/spec — 徹底した仕様策定ワークフロー

概要

アイデアを、開発者と Claude の双方が明示的に合意する、文書化されバージョン管理された仕様に変換します。計画やコードの作成に着手する前に行います。契約の内容は以下のとおりです。

• 決して推測しません。 アイデアに不足している情報はすべて質問にします。Claude が「たぶん」「おそらく」「一般的なやり方で」と考えた場合、その考えは決定ではなく、確認すべき質問です。
• 徹底的に、ただし体系的に進めます。 質問は、9 つの観点にわたって、焦点を絞ったラウンド（1 回につき 3～5 問）で行います。一度に圧倒するほどの質問を投げたり、早々に切り上げるための丁寧な質問を 1 回だけ行ったりはしません。
• 合意を明示します。 仕様には、Draft → In Review → Approved というステータスのライフサイクルがあります。Draft の状態から実装を開始することはありません。承認には、開発者が最終文書を読み、読んだことを伝える必要があります。
• 仕様はチャットではなくファイルです。 出力は docs/specs/<NNN>-<slug>.md に保存され、セッション終了後も残ります。計画、テスト、コミットからこのファイルを参照します。

使用するタイミング

• 1 文ですべてを説明できない規模の機能
• 新しい製品やモジュールのアイデア（「チームのワークスペースを追加したい」など）
• /plan の実行前に、複雑な機能について仕様を作成するとき。計画は承認済みの仕様を参照します
• 実装中に要件が曖昧だと感じたとき：作業を止めて /spec を実行し、計画を立て直します
• トリガーとなる語句：「spec」「requirements」「PRD」「define the feature」「acceptance criteria」

省略する場合： バグ修正、リファクタリング、対象のエンティティが明らかな単一エンドポイントの CRUD。

手順

ステップ 1：アイデアを把握して言い換える

元のアイデアを、Claude が理解した内容として、自分の言葉で 1 段落に言い換えます。最後に「これがアイデアですか？ どこを誤解していますか？」と尋ねます。開発者が言い換えを確認するまで、質問を始めてはいけません。誤ったアイデアについて質問しても、全員の時間を無駄にします。

ステップ 2：質問ラウンド

9 つの観点を順番に確認します。各ラウンドでは、未回答の質問のうち、後の質問の前提となる最も重要なものを 3～5 問選びます。ハーネスが選択肢を提示できる場合は、トレードオフと推奨案を添えて提示します。ただし、選択するのは開発者です。推奨案が黙って適用されることはありません。

#	観点	明確にする内容
1	問題とユーザー	現在困っているのは誰か、どのように回避しているか、成功とはどのような状態か
2	スコープ	今回の対象範囲、明確に対象外とするもの、MVP の境界
3	ドメインとデータ	エンティティ、関係、ライフサイクル（作成→アーカイブ→削除？）、保持期間
4	API コントラクト	リソース、エンドポイント、リクエスト／レスポンスの形式、ページネーション、バージョニング
5	認可	誰が何をできるか、ロール／クレームのモデル、テナントの境界
6	エッジケースと障害モード	同時実行、重複、冪等性、一部失敗、制限
7	非機能要件	想定されるボリューム、レイテンシの予算、成長の想定
8	インテグレーション	外部サービス、公開イベント、Webhook、副作用
9	受け入れ基準	スコープ内の各動作について、テスト可能な Given/When/Then

徹底的に質問するためのルール：

• 回答はすべて、直ちに仕様のドラフトに記録します。回答は会話ではなく、要件です。
• 矛盾があればその場で確認します。「ラウンド 1 では X と言っていましたが、今回の回答は X ではないことを示しています。どちらを優先しますか？」
• 「わかりません」は有効な回答です。その場合は保留中の決定事項に移し、開発者が今選ぶ明示的なフォールバックを設定します（「決定するまでは論理削除を既定にする」など）。黙って保留することは禁止です。
• 追加のラウンドで新しい質問が 1 つも出なくなったら、その観点は完了です。
• 9 つすべての観点が完了したら、質問フェーズは終了です。会話が長く感じても、途中で切り上げないでください。早く切り上げると、前提が紛れ込む原因になります。

ステップ 3：仕様ファイルのドラフトを作成する

docs/specs/ にある既存ファイルを確認して、次の番号を決めます（ディレクトリが存在しない場合は作成します）。docs/specs/<NNN>-<slug>.md に次の内容を書き込みます。

# Spec NNN: <Title>

**Status:** Draft
**Date:** <today>

## Problem            
## Scope              
## Domain Model       
## API Contract       
## Authorization      
## Edge Cases & Failure Modes
## Non-Functional Requirements
## Integrations
## Acceptance Criteria  
## Deferred Decisions   
## Open Questions       

ステップ 4：レビューループ

ステータスを レビュー中 に設定します。仕様全体を提示し、「最初から最後まで読んでください。間違っている点、不足している点、または過剰に設計されている点はありますか？」と尋ねます。修正を反映して再度提示します。開発者にこれ以上変更がなくなるまで繰り返します。新たな回答から新しい質問が生じることもあります。これはプロセスが機能している証拠であり、収束に失敗したということではありません。

ステップ 5：合意ゲート

承認は意図的な行為です。沈黙や、何気ない「よさそうです」という言葉から承認を推測してはいけません。明示的に「この仕様を承認しますか？承認後は仕様に沿ってコードを作成します。変更はまず仕様に反映します」と尋ねます。承認されたら、**Status:** Approved (<date>) に設定します。

• 未解決の質問は空でなければなりません。 残っているものがあれば、個別に明示して解決するか、保留にするまで仕様を承認できません。
• 実装中に誤った前提が判明した場合は、作業を止め、ステータスをレビュー中に戻し、開発者と仕様を修正してから再開します。コードが承認済みの仕様から、気づかれないまま逸脱することはありません。

ステップ 6：引き継ぎ

• /plan は承認済みの仕様を読み、受け入れ基準を実装手順に対応付けます
• /tdd は受け入れ基準を最初の失敗テストに変換します（AC-n → テスト名）
• 機能に関するコミットでは仕様を参照します：feat: team workspaces (spec 004)

例

User: /spec users should be able to invite teammates

Claude: Here's what I understood: an existing user can invite another person
  to join their... workspace? account? That's already my first gap.
  Is this the idea? What did I get wrong?

User: yes, invite to their organization

Claude: Round 1 — Scope & Users:
  1. Can invitees be people without an existing account, or only registered users?
  2. Who can invite — any member, or only admins/owners?
  3. Is there a limit on pending invites (per org, per plan)?
  4. Out of scope check: bulk invites and SSO-provisioned members — both OUT for now?

User: 1: both. 2: admins only. 3: no limit. 4: correct, both out.

Claude: Round 2 — Edge cases (your "both" in Q1 raises these):
  1. Inviting an email that already has a pending invite — error, or resend?
  2. Invite expiry — 7 days, 30 days, never?
  3. Invitee already belongs to another org — multi-org membership or rejection?
  ...

[…rounds continue until all nine dimensions are exhausted…]

Claude: Spec written to docs/specs/004-team-invitations.md (In Review).
  Read it end-to-end. What is wrong, missing, or over-engineered?

User: looks right. approved.

Claude: Status: Approved (2026-06-12). Next: /plan to map AC-1..AC-9
  to implementation steps.

関連項目

• /plan — 承認済みの仕様を使用します。仕様が必要な機能を、仕様なしで計画することはありません
• /tdd — 受け入れ基準が最初の失敗テストになります
• /scaffold — 計画で必要とされるスライスを生成します
• architecture-advisor — 機能によってアーキテクチャ上の判断が必要になる場合は、ステップ 2 で読み込みます