spec-driven-workflow

仕様駆動ワークフロー

仕様は、何を構築するか、そして完了をどう判断するかを共有する唯一の情報源です。

サイズのクイックガイド

サイズ	ワークフロー
ごく小規模	正式なワークフローは省略し、チャットで対応します
小規模	仕様を作成 → 実装
中規模	仕様を作成 → 分析 → 計画 → 実装 → レビュー
大規模	まず調査し、その後に完全なワークフローを進めます

サイズが判断しにくい場合は、references/problem-size-guide.md を読んでください。

ゲート付き手順

現在の成果物が十分な品質になるまでは、次のフェーズに進まないでください（中規模以上ではユーザーによるレビュー、小規模では自己チェックを行います）。

SIZE → SPECIFY → ANALYZE (medium+) → PLAN (medium+) → CLEAR → IMPLEMENT → REVIEW
                    ↑______________ living spec + plan sync ______________|

1. サイズ — 問題のサイズに合わせて深さを調整します（上の表を参照）。
2. 仕様化 — まず前提を明らかにし、その後、テスト可能な要件（REQ-XXX を推奨）を記述します。デフォルトは 要件優先 です。references/spec-writing-guide.md を読んでください。
   • バグ修正（自明でない／リスクの高い不具合）：現状／期待される状態／変更しない点 を使用します。references/bugfix-workflow.md を読んでください。
   • 設計優先（厳格な NFR、既存アーキテクチャ、スコープ決定前の実現可能性検証）：先に TECH／アプローチを作成し、その後 REQ を導きます。references/spec-writing-guide.md を参照してください。
3. 分析（中規模以上）— 計画の前に、要件間の競合、曖昧さ、抜け漏れを確認します。references/analyze-requirements.md を読んでください。
4. 計画（中規模以上）— 作業を具体的で検証可能なタスクに分割します。複数ファイルにわたる変更では、事前に文書化された計画を作成することを推奨します。
   • アーキテクチャパケット（大規模、およびアーキテクチャ／統合が曖昧な中規模）：複数フェーズの実装前に、システムコンテキストとコンテナビュー（または「N/A — アーキテクチャ検証済み」）を必須とし、不可逆な選択については solution-architecture ／ /design-architecture を通じて ADR へのリンクを記載します。references/problem-size-guide.md を参照してください。
   • トレーサーバレット（大規模、およびアーキテクチャ／統合が曖昧な中規模）：複数フェーズの実装前に、小さな垂直スライスと検証を 1 つ含めるか、「N/A — アーキテクチャ検証済み」という明示的な根拠を記載します。references/problem-size-guide.md を参照してください。
   • QA が次の REQ スライスと並行して進められるよう、ビルドタスクと検証／レビュータスクを分けることを推奨します（小規模では任意）。
5. 整理（中規模以上）— 調査結果を継続的に更新する仕様／計画に反映し、実装は身軽に開始します。調査の記録全体を作業コンテキストとして引き継がないでください。範囲を限定した調査（サブエージェントまたは専用チャットの利用）は問題ありませんが、永続化すべき知見はすでに成果物に記載されている必要があります。複数セッションにわたる作業では、references/session-handoff.md を読んでください（コーディング前の開始チェックリスト：継続的に更新する仕様＋計画＋進捗）。
6. 実装 — 仕様／計画に従い、明示的な根拠がある非動作要件を除き、各要件をテストに対応付けます。中規模以上では、セッション終了時（または作業が未完了の場合）に session-handoff.md に従って引き継ぎ／進捗セクションを記述します。AFK プロダクトではありません。
7. レビュー — 評価の工程を分けます（生成者 ≠ 評価者）。仕様への適合性、リグレッション防止策、セキュリティ上重要な経路、テスト、およびユーザー向け画面の変更に伴うドキュメント／README の差異を、反証を試みる姿勢で確認します（/update-readme ／ readme-authoring に引き継ぎます。依頼がない限り、レビュー中に全体の同期は行わないでください）。実装セッション中の自己評価を完了とみなさないでください。references/review-evaluator.md を読んでください。
8. 既存コードベース — 大規模な変更の前に、extract-spec で既存の動作を文書化します。references/brownfield-workflow.md を読んでください。

仕様を書く前に

前提をすぐに明らかにします。 仮定していることを列挙し、下書きの前に修正を促してください。

ASSUMPTIONS:
1. …
2. …
→ Correct me now or I'll proceed with these.

曖昧な目標を成功基準として再構成し（測定可能／テスト可能な形にして）、確認します。

REQUIREMENT: "Make the dashboard faster"
SUCCESS CRITERIA:
- LCP < 2.5s on 4G
- Initial data load < 500ms
→ Are these the right targets?

テストの境界をスケッチします（中規模以上）。 新たに境界を作るよりも、役立つ既存の境界（API、モジュール、ポート）を優先し、仕様に固定する前にユーザーに確認します。詳細は references/spec-writing-guide.md を参照してください。

曖昧な要件を黙って補完しないでください。それこそが SDD で防ぐべき失敗パターンです。

仕様と計画の同期を維持する

決定事項やスコープに変更があった場合は仕様を更新し、変更を実装する前に仕様を更新することを優先してください。PR から、対応する仕様のセクションまたは REQ-XXX にリンクしてください。

重要な REQ／設計の編集後： /plan-impl を再実行するか、Cursor Plan YAML の todos を更新して、タスクが最新の仕様に合うようにしてください。古い計画に基づいて実装してはいけません。

成果物の保存先

仕様や計画を作成する前に、出力先を確認してください（.cursor/ と決めつけないでください）。

1. ユーザーが指定したパス（--out、@file、具体的なパス）
2. 既存のプロジェクト規約（docs/specs|plans または .cursor/docs/specs / .cursor/plans）
3. クライアントのデフォルト — Cursor / または Cursor の設定の場合は .cursor/...、それ以外の場合は docs/specs と docs/plans

仕様や計画の作成または保存先の確認時は、references/artifact-homes.md を読んでください。
保存先が Cursor の場合は、references/cursor-adapter.md を読んでください（Plan YAML の todos が必須です）。

スラッシュコマンドは任意の薄いラッパーです。詳細は references/commands-reference.md を参照してください。

段階的な情報開示

必要な場合にのみ、参照資料を読み込んでください。

参照資料	読むタイミング
references/artifact-homes.md	仕様や計画を作成／探すとき、またはパスが不明なとき
references/cursor-adapter.md	Cursor の / コマンド、または .cursor/plans / .cursor/docs の保存先を使うとき
references/session-handoff.md	中規模以上の複数セッション作業の開始時／終了時。進捗と次の REQ を確認するとき
references/review-evaluator.md	/review またはレビュー段階。生成と評価は別物です
references/problem-size-guide.md	規模が不明、または見解が分かれるとき
references/spec-writing-guide.md	仕様の作成またはレビュー時。Design-First と Requirements-First の選択時
references/analyze-requirements.md	中規模以上の作業で /plan-impl の前、または重要な REQ の編集後
references/bugfix-workflow.md	回帰防止策が必要な、単純でないバグ修正時
references/greenfield-workflow.md	維持すべき既存の挙動がない新機能の追加時
references/brownfield-workflow.md	既存コードの変更または文書化時
references/commands-reference.md	スラッシュコマンドの使い方やオプションを確認するとき
references/getting-started.md	ユーザーから ADSK のインストール／セットアップ方法を尋ねられたとき
references/spec-driven-overview.md	ユーザーから SDD を採用する理由を尋ねられたとき（通常の作業では不要）
references/best-practices.md	ユーザーからヒントや外部リンクを求められたとき
references/extending.md	ルール／コマンド／スキルの追加や、上流パックとの組み合わせ時

品質ゲート

• 要件が曖昧な場合は、草案の作成前に前提を明示します。
• 要件は具体的で、テスト可能なものにします。
• 中規模以上の仕様では、計画の前に要件間の分析を行うか、「N/A — 小規模な REQ セットのため、すでにレビュー済み」と明記します。
• 挙動が単純でない場合、中規模以上の仕様では、優先するテスト境界（既存の最も有用な境界）を明記します。
• バグ修正の仕様を作成する場合は、変更しない挙動を記録し、その境界をテストでカバーします。
• 重要な仕様の更新後は、実装前に計画／todos を同期し直します。
• 大規模または曖昧な中規模の計画では、統合境界が不明確な場合、solution-architecture によるアーキテクチャパケットのゲートを設けます（または「N/A — アーキテクチャは実証済み」と明記します）。
• 実装した要件には自動テストを用意します（真に非動作的な変更の場合は、簡潔な理由を記載します）。
• 失敗時は完了としない検証： 完了を宣言する前に、project-cmds（または文書化されたプロジェクト検証手順）を実行します。検証手順が設定されていない場合は、完了を宣言せず、/quick-start の実行、または project-cmds／移植可能な同等の手段の設定を案内してください。「問題なさそう」というだけで検証を済ませてはいけません。
• 複数セッションの引き継ぎ（中規模以上）： セッション開始時に、最新の仕様、計画、進捗を読みます。終了時には、session-handoff.md に従って引き継ぎ情報（次の REQ／T#、git の想定）を更新します。AFK/Ralph 製品ではありません。
• 生成と評価は別物（中規模以上）： 実装時の自己評価だけで完了と判断せず、review-evaluator.md に従い、反証を重視する別個の /review を実施してください（バグ修正では変更しない挙動の境界が必須です）。