仕様駆動開発（SDD）×Claude Code完全ガイド｜requirements.mdから始める実践手順とテンプレ

AIコーディングを実務で回していると、「指示が抽象的で実装がブレた」「期待と違うコードが3回戻ってきた」「チーム内で意図が共有されていない」といった手戻りに必ず突き当たります。手戻りの本質は仕様の曖昧さであり、それをAIに押し付けても解決しません。むしろ高速にコードを生成するAIに曖昧な指示を与えるほど、誤った実装が積み上がるスピードも比例して上がっていきます。

2025年から2026年にかけて急速に広がっている仕様駆動開発（SDD; Spec-Driven Development、スペック駆動開発） は、「コードより先に仕様書を書き、AIは仕様書から実装を生成する」というワークフローです。AWS Kiro、GitHub Spec Kit、cc-sdd、claude-code-spec-workflowといったツールチェーンが整い、Claude Codeとの組み合わせで現場運用に耐える形まで成熟しました。

本記事では、Claude CodeでのSDD実践手順を、業種別のrequirements.md / design.md / tasks.md テンプレ9本、4大ツール比較、業界別適用パターン、失敗5選、チーム導入ロードマップまで含めて、ピラー記事として一冊で完結する形にまとめます。TDDとの関係はClaude Code TDDワークフロー、基本操作はClaude Code完全ガイドも合わせて参照してください。

結論 ── SDDは「仕様を第一級成果物にする」AIコーディングの新標準

仕様駆動開発（SDD）は、コードより先に要件（Requirements）・設計（Design）・タスク（Tasks）を仕様書として人間が承認し、AIが仕様から実装を生成するワークフローです。 Claude Codeでは /add-feature などのSkill、cc-sdd、GitHub Spec Kit、claude-code-spec-workflow といったツールチェーンが揃い、2026年時点で実務運用に耐えるレベルまで成熟しています。

従来、仕様書は「開発中に読まれない紙」として扱われてきました。SDDの最大の発想転換は、仕様書を第一級成果物（first-class artifact）として位置付け、コードを仕様から派生する二次成果物として扱うことです。AIコーディングとの相性が極めて良く、Vibe Coding（とりあえず書く）やPlan Mode（計画は立てるが揮発する）の限界を超える方法論として急速に広がっています。

すぐ始めるには次の3コマンドで足ります。Claude Codeのプロジェクト直下で実行してください。

# 1. cc-sdd をインストール（日本語対応）
npx cc-sdd@latest --lang ja

# 2. 新機能の仕様を初期化
/kiro-spec-init ユーザー検索機能

# 3. 仕様から実装まで自律実行（承認ゲートあり）
/kiro-impl ユーザー検索機能

公開されている定量データとしては、Vibe Codingに比べて開発時間が約40%短縮、バグ件数が機能あたり12個から2個に削減、コードレビュー時間が約60%短縮といった効果が報告されています（出典: Claude Codeで実現する仕様駆動開発(SDD), 2026, Zenn Luup Developers）。実プロジェクト規模で再現性は変動しますが、「仕様を先に書いた分だけ、後工程の手戻りが減る」というメカニズムは普遍的です。

なお本記事は、ピラー記事として「SDDとは何か」から「ツール比較」「業種別テンプレ9本」「業界別適用パターン」「失敗5選」「3-6ヶ月導入ロードマップ」「表記揺れ問題」までを一冊で網羅する構成にしています。先頭から順に読むと体系的に理解でき、すでに知っている読者は目次から興味のあるセクションに飛んで実務リファレンスとして使えるようにしています。

Claude Code で SDD を始める3つの方法（claude code sdd 最短ルート）

Claude Code で SDD を始めるルートは大きく3つあります。どれも requirements.md / design.md / tasks.md の3点セットを生成し、各フェーズに承認ゲートを置く点は共通で、違うのは導入コストと柔軟性だけです。「Claude Code で SDD を試したいが、どれを入れればいいか分からない」という最初の分岐を、次の表で1分で解消できます。

最短で体感したいなら、プロジェクト直下で npx cc-sdd@latest --lang ja を実行し、/kiro-spec-init {機能名} で仕様を初期化、/kiro-impl {機能名} で実装まで通すだけで requirements → design → tasks → implementation の4フェーズを一巡できます。3ルートの詳細な違いは後述の「SDDを支える主要4ツール比較」と「cc-sdd 完全ガイド」で、Claude Code 固有の Skills / Subagents / CLAUDE.md 連携の作り込み方は「Claude Code 固有の SDD 実践」で解説します。まず動かして感触を掴み、必要に応じて自前 Skill へ発展させるのが、Claude Code で SDD を定着させる現実的な順序です。

仕様駆動開発（SDD）とは何か

仕様駆動開発（SDD; Spec-Driven Development）とは、自然言語の仕様書（spec）を唯一の真実（Single Source of Truth）と定め、AIが仕様から実装コードを生成する開発方法論です。日本語では「スペック駆動開発」と呼ばれることもあり、両者は同義です。

従来の開発では、「要件を口頭で確認 → ホワイトボードで設計 → 暗黙知のままコード化」という流れが多く、設計判断の根拠が個人の頭にしか残りませんでした。SDDは、要件・設計・タスク分解の各段階で必ずMarkdownの仕様書を生成し、git管理することで、設計判断を組織知としてレビュー・再利用可能な形に保存します。

SDDが扱う3つの仕様書

AWS Kiro、cc-sdd、GitHub Spec Kit といった主要ツールはすべて、この3点セットを基本に置いています。ファイル名やディレクトリ配置に細部の違いはありますが、コンセプトはほぼ統一されています。

第一級成果物としての仕様書

「第一級成果物」は型システムの「ファーストクラス関数」と同じニュアンスで、仕様書がコードと同等にレビュー・テスト・バージョン管理される存在になることを意味します。具体的には、PRのレビューに先立って仕様書のPRがレビューされ、仕様書だけのコミット履歴がgitに残り、CIで仕様書のフォーマット検証が走り、変更要求はコードではなく仕様書の差分として議論される、といった運用が成立します。

仕様書を第一級にすると、自然と「コードを書く前に仕様で議論する」文化が定着し、無駄な実装の手戻りが減ります。

Single Source of Truth としての効果

仕様書を真実の起点と定めると、認識齟齬・実装漏れ・テスト抜けがすべて「仕様書とコードの差分」として検出可能になります。差分検出のたびに、コードを直すか、仕様書を直すか、いずれかの修正が必ず発生し、放置された曖昧さが残らないという仕組みが効きます。

SDD という言葉の歴史と直近の流れ

「コードより先に仕様を書く」という発想自体は新しいものではなく、形式手法・Behavior Driven Development（BDD）・モデル駆動開発（MDD）など、長く議論されてきた領域です。それが2025年に再注目された背景には、AWSが2025年7月にプレビュー公開、同年11月に一般提供（GA）を開始した独自IDE「Kiro」の存在が大きく影響しています。Kiroが「spec モード」と呼ぶ requirements → design → tasks → implementation の4フェーズワークフローを打ち出したことで、AIコーディング時代のSDDの形が明確に定義され、コミュニティ全体がこのフォーマットに収斂していきました。

その後、GitHubが2025年後半に「Spec Kit」をOSSとして公開、日本人開発者の gotalab 氏がKiro互換の「cc-sdd」を公開、コミュニティ開発の「claude-code-spec-workflow」「cc-spex」が登場、と短期間で生態系が広がりました。2026年5月時点では、これらのツールはほぼ同じファイル構造（requirements.md / design.md / tasks.md）を採用しており、ツール間の移行コストは非常に低くなっています。

なぜ今SDDが必要か — AIコーディング3つの限界

AIコーディングの普及によって露呈した3つの限界が、SDDの普及を後押ししています。

限界1: Vibe Coding（とりあえず書く）の手戻り増大

「いい感じに実装して」と自然言語で指示するスタイルは、初期は速いものの、規模が増えると認識齟齬が累積します。AIは指示の行間を勝手に補完するため、人間の意図とAIの解釈のズレが、レビュー時にまとめて顕在化します。

事例報告として、Vibe Codingでは1機能あたり平均12個のバグが残るのに対し、SDDでは2個程度まで圧縮されたケースが紹介されています（出典: Claude Codeで実現する仕様駆動開発(SDD), 2026, Zenn Luup Developers）。これは小規模PoCで観測された値であり、規模拡大時にこの比率がそのまま維持されるとは限りませんが、傾向としては多くの現場で再現されています。

限界2: Plan Mode（計画を立てるが揮発する）の継承不能性

Claude CodeのPlan Modeや、ChatGPTでの「まず計画を立ててから実装」スタイルは、Vibe Codingよりは構造化されますが、計画がAIのセッション内メモリにしか残らないため、翌日の作業や別エンジニアへの引き継ぎで継承できないという問題があります。

SDDは計画をMarkdownファイルとしてリポジトリに保存するため、セッションを跨いだ継承性が確保されます。Claude Codeのコンテキスト圧縮（auto-compact）でも、ファイルから再読み込みすればコンテキストを復元できます。

限界3: AIハルシネーションと認識齟齬の温床

AIは「もっともらしいが間違っている」コードを自信たっぷりに出力します。架空のAPI、存在しないライブラリ、誤ったバージョン引数といったハルシネーションは、コードだけを見るとレビュアーも見抜けないことがあります。

SDDは、design.mdに使用ライブラリ・バージョン・公式ドキュメントURLを明記する運用を強制することで、ハルシネーションを設計段階で抑止します。「Claude Codeに架空のライブラリを使われた」という事故は、design.mdに公式URLを書く運用だけで大半が防げます。

SDDの4フェーズ詳細（Requirements / Design / Tasks / Implementation）

SDDの典型的な進め方は次の4フェーズです。AWS Kiroが「requirements → design → tasks → implementation」という流れを定めて以来、cc-sdd、GitHub Spec Kit、claude-code-spec-workflowもすべて、この4フェーズを基本骨格としています。

Phase 1: Requirements（要件定義）

「何を、誰のために、なぜ作るか」を定義するフェーズです。ユーザーストーリー、受け入れ基準、非機能要件、スコープ外項目、依存する既存機能を、自然言語と構造化フォーマットで記述します。

このフェーズの最大の論点は曖昧さの排除です。「使いやすい検索」「高速」「セキュアに」といった表現は具体化必須で、「平均応答時間500ms以内」「最大同時セッション100」「権限のない一般ユーザーからは検索フォームが非表示」のように、テスト可能な数値・条件に分解する必要があります。

承認ゲート: 要件レビュー → 業務担当と開発リードが承認

Phase 2: Design（設計）

「どう作るか」を定義するフェーズです。API設計、DBスキーマ、フロントエンドコンポーネント構成、使用ライブラリと選定理由、トレードオフ、シーケンス図、ER図を記述します。

設計判断の根拠を明記することが重要で、「3案出して比較したうえで2案を採用」のように、選ばれなかった案も併記すると、後から判断を見直すときの議論のスタート地点が高くなります。

承認ゲート: 設計レビュー → アーキテクト・テックリードが承認

Phase 3: Tasks（タスク分解）

「どの順で作るか」を定義するフェーズです。設計を実装単位に分解し、依存関係、見積もり、対応するテスト、完了条件を明示します。1タスクが1PR、半日以内に完了、レビュー30分以内、というのが現場で機能する粒度の目安です。

このフェーズで甘いと、実装中に「あ、これは別タスクにすべきだった」が連発するため、ここで時間を使うほど後が楽になります。

承認ゲート: タスク粒度レビュー → 開発リードが承認

Phase 4: Implementation（実装）

タスクを順にAIに実装させます。Claude Codeなら /add-feature SkillやSubagent経由で、各タスクをTDDで進めることが可能です。完成したコードをPRに上げ、CI、レビュー、マージというフローに乗せます。

承認ゲート: 各タスクのテスト通過 → コードレビュー → マージ

各フェーズで「人間の承認」を挟むことで、AIが暴走して下流まで誤った仮定で進むのを防ぎます。AWS Kiroではこれを「approval gate」と呼び、cc-sddやGitHub Spec Kitでも同じ思想が採用されています。

requirements.md 完全ガイド（業種別3テンプレ＋EARS・最小版）

requirements.mdは「何を作るか」を確定させる最重要ファイルです。粒度・記法・項目構成は組織やプロジェクトに応じてカスタマイズすべきですが、ここでは業種別の代表例を3パターンに加え、記法を標準化したい組織向けのEARS形式テンプレ、まず1枚で始めるための最小スターターテンプレの計5種を提示します。すべてコピペしてプロジェクトに合わせて修正できる形にしてあります。

テンプレ1: 業務SaaS（権限管理機能の追加）

業務SaaSは機能追加サイクルが速く、既存機能との影響範囲が大きいため、スコープと既存機能への影響を明示することが効きます。

# Requirements: 組織横断権限管理機能

## 目的
複数チームに所属するメンバーが、所属に応じて閲覧範囲が自動で切り替わるようにする。
現在は個別に権限設定が必要で、人事異動のたびに3〜5時間の手作業が発生している。

## ユーザーストーリー
1. As a 管理者
   I want メンバーをチームに割り当てるだけで権限が決まるようにしたい
   So that 異動のたびの個別設定をなくしたい

2. As a メンバー
   I want 自分が所属するチームのデータだけが見えるようにしたい
   So that 他チームの機密情報に意図せずアクセスしないようにしたい

## 受け入れ基準（Given-When-Then形式）
- Given メンバーAがチームXに所属、When メンバーAがダッシュボードを開く、Then チームX関連の案件のみ表示される
- Given 管理者が新メンバーをチームYに割り当てる、When 割り当て後10秒以内、Then 当該メンバーのアクセス可能範囲にチームYのデータが追加される
- Given メンバーが2つのチームに所属、When ダッシュボードを開く、Then 両チームのデータが統合されて表示される
- Given 一般メンバーが他チームのAPIを直接叩く、When リクエスト送信、Then 403を返す

## 非機能要件
- 権限判定の追加レイテンシ: p95 で 30ms 以内
- 同時セッション: 5,000
- 監査ログ: 全アクセスを30日保持

## スコープ外
- 個別ユーザーへの一時付与（次フェーズ）
- 外部組織との共有設定（別案件）

## 依存
- 既存の users / teams テーブル
- 認証ミドルウェア（変更なし）

テンプレ2: モバイルアプリ（プッシュ通知機能）

モバイルアプリはOS依存・端末バリエーションが大きいため、対象OS・端末状態・オフライン挙動を明示します。

# Requirements: イベント通知プッシュ機能

## 目的
ユーザーがフォロー中のイベントに変更が発生した際、即時にプッシュ通知する。
現状はメールのみで、開封率が8%にとどまっている。

## ユーザーストーリー
1. As a ユーザー
   I want フォロー中イベントの開始30分前に通知を受けたい
   So that 開始に間に合うようにスケジュール調整できる

2. As a ユーザー
   I want 通知の種類ごとにオン/オフを切り替えたい
   So that 過剰な通知を防ぎたい

## 受け入れ基準
- Given ユーザーがイベントAをフォロー、When 開始30分前、Then プッシュ通知が届く
- Given ユーザーが通知設定で「開始前通知」をオフ、When 開始30分前、Then 通知が届かない
- Given ユーザーがオフライン、When 通知が届くタイミング、Then オンライン復帰後3分以内に届く
- Given OSの通知権限が拒否されている、When アプリ起動、Then 初回起動時に1度だけ権限再要求のダイアログを表示

## 対象環境
- iOS 16 以降、Android 12 以降
- 機内モード・低電力モードでも復帰時に届くこと

## 非機能要件
- 通知到達率: 95%以上（48時間以内）
- 配信ジョブ: 1分あたり50,000通

## スコープ外
- リッチ通知（画像付き）
- アプリ内通知のUI改善

テンプレ3: 業務システム（在庫管理機能の刷新）

業務システムは既存業務フローの転記が要で、画面遷移と例外パターンを丁寧に書き出します。

# Requirements: 在庫引当ロジックの刷新

## 目的
受注後に複数倉庫から最適な倉庫を自動で選択し、引当・出荷指示を生成する。
現状は担当者が手動でExcelから引き当てており、1件あたり平均8分、誤引当率3%。

## ユーザーストーリー
1. As a 受注担当
   I want 受注確定時に倉庫が自動選択されるようにしたい
   So that 引当作業を手動でやらなくて済む

2. As a 倉庫担当
   I want 出荷指示書がプリンタに自動で出るようにしたい
   So that 朝の作業開始時にすぐ出荷準備に入れる

## 受け入れ基準
- Given 商品Aの在庫が倉庫W1・W2にある、When 顧客が東京の届け先で受注、Then 距離が近いW2が優先される
- Given 倉庫W1のロットが先入先出条件にマッチ、When 引当判定、Then ロット古いほうから引当
- Given 在庫不足、When 受注確定、Then 「在庫不足」ステータスで保留、担当者にアラート
- Given 受注がキャンセル、When キャンセル確定、Then 引当を自動で解放

## 業務フロー
1. 受注登録 → 引当判定 → 倉庫選択 → 出荷指示書発行 → 倉庫で梱包 → 出荷
2. 例外: 在庫不足 → 保留 → 補充入庫 → 引当再実行

## 非機能要件
- 引当判定: p95 で 500ms 以内
- 並行受注 1,000件/分でデッドロックなし
- ロット管理: 賞味期限・製造日を保持し、優先度ルール変更が設定画面から可能

## 依存
- 既存倉庫マスタ、商品マスタ、ロット管理
- ERP連携（既存IF、変更なし）

テンプレ4: EARS形式（記法を標準化したい組織向け）

EARS（Easy Approach to Requirements Syntax）は、曖昧さを減らす5つの基本構文で要件を書く記法で、AWS Kiroが標準採用しています。Given-When-Thenが「受け入れテスト」の記法なのに対し、EARSは「要件そのもの」の記法です。両者を併用すると、要件レベルと受け入れテストレベルの双方を構造化できます。Claude Codeに「EARS形式でrequirements.mdを書いて」と指示すると、この構文に沿った要件を生成できます。

# Requirements: ユーザー検索機能（EARS形式）

## Ubiquitous（常時成立する要件）
- The system shall すべての検索リクエストを監査ログに記録する。

## Event-driven（WHEN: イベント駆動）
- WHEN ユーザーが検索ボタンを押す, the system shall 500ms以内に結果を返す。

## State-driven（WHILE: 状態駆動）
- WHILE ユーザーが未ログイン状態である, the system shall 検索フォームを非表示にする。

## Optional（WHERE: 機能オプション）
- WHERE 高度検索オプションが有効な場合, the system shall 正規表現検索を許可する。

## Unwanted behavior（IF...THEN: 異常系）
- IF 検索クエリが空である, THEN the system shall 直近の検索履歴を表示する。

5構文（Ubiquitous / Event-driven / State-driven / Optional / Unwanted behavior）に分類するだけで、要件の抜け漏れ（とくに異常系の取りこぼし）と曖昧さが大幅に減ります。要件全体をEARSで構造化し、各要件に対応する受け入れ基準だけをGiven-When-Thenで書く、という二段構えが実務では読みやすい構成です。

最小スターターテンプレ（まず1枚で始める）

「いきなり業種別テンプレは重い」という場合の、最小構成のrequirements.mdです。これだけでもVibe Coding（とりあえず書く）に比べて認識齟齬が激減します。まずこの1枚で1機能を通し、慣れてきたら業種別テンプレやEARS形式に拡張していくのがスムーズです。

# Requirements: {機能名}

## 目的（なぜ作るか）
{1〜2文で。現状の課題と、解決後の状態を書く}

## ユーザーストーリー
- As a {誰が}, I want {何を}, So that {なぜ}

## 受け入れ基準（Given-When-Then）
- Given {前提}, When {操作}, Then {期待結果}

## 非機能要件（必ず数値で）
- {例: p95 レスポンスタイム 500ms 以内}

## スコープ外
- {今回やらないことを明示。膨張を防ぐ}

## 依存
- {影響する既存機能・テーブル・外部IF}

requirements.mdレビューの観点

• 受け入れ基準は1基準=1テストに対応する粒度になっているか
• 非機能要件は数値で書かれているか（「速い」「安全に」はNG）
• スコープ外項目が明示されているか
• 依存する既存機能・データが列挙されているか
• 業務担当が読んで理解できる粒度か

Claude Codeに requirements.md を生成させたあとは、必ず業務担当を含めたレビューを1度通します。AI生成のままマージすると、業務理解と乖離した「もっともらしい仕様書」がそのまま設計に流れていきます。

design.md 完全ガイド（業種別3テンプレ＋Mermaid図）

design.mdは「どう作るか」を確定させるファイルです。API・DB・UI・使用ライブラリ・トレードオフを記述します。業種別の3テンプレに加え、設計意図を可視化するMermaid図の書き方も後半で示します。

テンプレ1: 業務SaaS（権限管理）

# Design: 組織横断権限管理機能

## アーキテクチャ概要
権限判定は API ゲートウェイ層に集約し、リクエストごとに JWT に埋め込まれた team_ids
と対象リソースの所属 team_id を突合する。

## API 設計
- GET /api/teams/{team_id}/items — チーム所属者のみ取得可
- POST /api/teams/{team_id}/items — チーム所属者のみ作成可
- 共通レスポンス: 403 (権限不足) / 404 (リソース未存在)

## DB スキーマ
team_members テーブル（新規）
  - user_id: uuid, NOT NULL
  - team_id: uuid, NOT NULL
  - role: text ('admin' | 'member' | 'viewer'), NOT NULL
  - PRIMARY KEY (user_id, team_id)
  - INDEX idx_team_members_user_id ON (user_id)

items テーブル（既存に team_id 追加）
  - ALTER TABLE items ADD COLUMN team_id uuid;
  - INDEX idx_items_team_id ON (team_id)

## 権限ミドルウェア
- 既存 auth ミドルウェアの後段に permission ミドルウェアを挿入
- JWT.team_ids と request.params.team_id を比較
- 一致しなければ 403

## ライブラリ選定
- 採用: zod（既存利用、リクエスト検証）
- 採用: drizzle-orm（既存利用、team_members 操作）
- 候補だが不採用: casbin（汎用権限ライブラリだが、過剰）

## トレードオフ
案A: JWT に team_ids 埋め込み（採用）
  → メリット: DB アクセスなし、高速
  → デメリット: 異動時に JWT 失効処理が必要
案B: 毎回 DB を叩く
  → デメリット: レイテンシ +20ms

## マイグレーション戦略
1. team_members テーブル作成
2. 既存 items に team_id カラム追加（NULL 許容）
3. 既存データに team_id を一括 backfill
4. team_id を NOT NULL 化
5. 権限ミドルウェア有効化

テンプレ2: モバイルアプリ（プッシュ通知）

# Design: プッシュ通知配信基盤

## アーキテクチャ概要
イベントの開始時刻と通知タイミングを Schedule テーブルに登録し、
分単位の cron がチェック → FCM/APNs にバッチ送信する構成。

## 配信パイプライン
イベント変更 → Schedule に通知ジョブを登録 → cron (毎分) → FCM/APNs → デバイス

## API 設計
- POST /api/notifications/subscriptions — 通知種別の購読設定
- DELETE /api/notifications/subscriptions/{id} — 購読解除
- POST /api/devices/tokens — デバイストークン登録（OS判別付き）

## データモデル
notification_schedules
  - event_id, user_id, notify_at (timestamp), type
  - INDEX (notify_at)
device_tokens
  - user_id, platform ('ios' | 'android'), token, updated_at

## 通知ペイロード
{
  "title": "[イベント名] が30分後に開始",
  "body": "現在地から徒歩10分。詳細を見る",
  "data": { "event_id": "...", "deep_link": "/events/..." }
}

## 配信失敗時の挙動
- 一時エラー: 5分後にリトライ最大3回
- 恒久エラー（端末トークン無効）: device_tokens から削除

## ライブラリ選定
- 採用: firebase-admin（FCM 公式）
- 採用: node-apn（APNs、シンプルで実績あり）
- 候補だが不採用: OneSignal（外部依存を最小化したい）

## トレードオフ
案A: cron で分単位ポーリング（採用）
  → メリット: 構成シンプル、デバッグ容易
  → デメリット: 最大1分のズレ
案B: BullMQ で遅延ジョブ
  → デメリット: 運用負荷

テンプレ3: 業務システム（在庫引当）

# Design: 在庫引当アルゴリズム

## アーキテクチャ概要
受注登録 → 引当ジョブをキューに投入 → 倉庫選択ロジック → 引当ロック → 出荷指示生成。

## 引当アルゴリズム
1. 商品の在庫を持つ倉庫を抽出
2. 配送先住所から距離スコアを計算（Haversine 公式）
3. ロット優先度（先入先出 / 賞味期限優先）でロットを並べる
4. 必要数量を満たすまでロット単位で引当
5. 引当ロックを取得（PostgreSQL のアドバイザリロック）

## DB スキーマ
allocations
  - id, order_id, sku, lot_id, warehouse_id, qty, status, allocated_at
  - INDEX (order_id), INDEX (lot_id, warehouse_id)

reservation_locks
  - lot_id, warehouse_id, locked_until
  - PRIMARY KEY (lot_id, warehouse_id)

## 競合制御
- PostgreSQL のアドバイザリロック (pg_advisory_xact_lock) で SKU 単位排他
- ロック失敗時は最大3回リトライ、それでも失敗なら「保留」ステータス

## ライブラリ選定
- 採用: drizzle-orm + node-postgres
- 採用: BullMQ（引当ジョブのキュー管理）
- 候補だが不採用: Apache Kafka（オーバースペック）

## トレードオフ
案A: 同期 API + アドバイザリロック（採用）
  → メリット: シンプル、デバッグ容易
  → デメリット: ピーク時のスループット上限
案B: 非同期キュー + イベントソーシング
  → デメリット: 受注完了の即時性が損なわれる

design.md に Mermaid 図を埋め込む

design.mdは文章だけより、Mermaid図を併記すると設計意図が一目で伝わります。GitHubもcc-sddもGFM（GitHub Flavored Markdown）のMermaidをレンダリングできるため、シーケンス図・ER図・状態遷移図をそのままspecに貼れます。とくにAPIの呼び出し順序と権限判定の分岐は、文章で書くより図のほうがレビュー時の認識齟齬が減ります。

権限判定フローのシーケンス図の例:

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant P as Permission MW
  participant D as DB
  C->>G: GET /teams/{id}/items (JWT)
  G->>P: JWT.team_ids と request.team_id を突合
  alt 権限あり
    P->>D: items 取得
    D-->>C: 200 OK
  else 権限なし
    P-->>C: 403 Forbidden
  end

権限まわりのER図の例:

erDiagram
  users ||--o{ team_members : has
  teams ||--o{ team_members : has
  teams ||--o{ items : owns

図は「正」ではなく「補助」と位置付けるのがコツです。図と本文が矛盾したら本文を正とし、図は次の編集で追従させる、という運用ルールをdesign.mdの冒頭に1行書いておくと、図の陳腐化による混乱を防げます。Claude Codeに「この設計のシーケンス図をMermaidで書いて」と頼めば、本文から図を自動生成できるため、図のメンテナンスコストも抑えられます。

design.md レビューの観点

• 採用ライブラリの公式URLが記載されているか
• 不採用案とトレードオフが書かれているか
• マイグレーション手順が破壊的変更を最小化しているか
• 競合制御・例外処理が言及されているか
• フロントエンドとAPIのインターフェースが一致しているか

design.mdに使用ライブラリの公式URLを必ず記載する運用を徹底すると、AIによる架空ライブラリのハルシネーションを設計段階で潰せます。

tasks.md 完全ガイド（業種別3テンプレ）

tasks.mdは「どの順で実装するか」を確定させるファイルです。1タスク=1PRの粒度に分解し、依存関係を明示します。

テンプレ1: 業務SaaS（権限管理）

# Tasks: 組織横断権限管理機能

## 実装順序
1. [ ] DB マイグレーション: team_members テーブル作成 + items.team_id 追加
   - 依存: なし
   - テスト: マイグレーションの up/down が成功すること
   - 完了条件: 既存テストが全て通過

2. [ ] team_members CRUD API 実装
   - 依存: 1
   - テスト: 単体テスト（CRUD 各パターン）+ 統合テスト
   - 完了条件: カバレッジ 80% 以上

3. [ ] 権限ミドルウェア実装
   - 依存: 2
   - テスト: JWT に team_ids がない場合 403、ある場合 200
   - 完了条件: e2e テストで権限分離が確認できる

4. [ ] 既存 items API に team_id バインド追加
   - 依存: 3
   - テスト: 別チームのデータが見えないことを確認
   - 完了条件: 既存テスト + 新規テスト全通過

5. [ ] 管理画面: チーム所属管理 UI
   - 依存: 2
   - テスト: Playwright e2e（割り当て・解除）
   - 完了条件: アクセシビリティ自動チェック通過

6. [ ] 既存データの team_id 一括 backfill スクリプト
   - 依存: 1
   - テスト: dry-run で件数確認 → 本番適用
   - 完了条件: 全 items に team_id が設定される

7. [ ] 監査ログ拡張: 権限拒否イベントを記録
   - 依存: 3
   - テスト: 403 ログが audit_logs に残ること
   - 完了条件: ログ閲覧画面で確認可能

テンプレ2: モバイルアプリ（プッシュ通知）

# Tasks: イベント通知プッシュ機能

1. [ ] device_tokens テーブル作成 + トークン登録 API
2. [ ] notification_schedules テーブル作成 + イベント変更時の登録ロジック
3. [ ] cron ワーカー: 1分ごとに到来通知をスキャン
4. [ ] FCM 配信実装（Android）
5. [ ] APNs 配信実装（iOS）
6. [ ] 通知設定 UI（種別ごとオン/オフ）
7. [ ] 配信失敗ハンドラ（リトライ + 無効トークン削除）
8. [ ] e2e: フォロー → 30分前 → 通知到達のリグレッションテスト
9. [ ] ダッシュボード: 配信成功率の可視化

テンプレ3: 業務システム（在庫引当）

# Tasks: 在庫引当ロジック刷新

1. [ ] allocations / reservation_locks テーブル作成
2. [ ] 距離スコア計算ライブラリの導入（Haversine 公式）
3. [ ] 引当アルゴリズムのコア実装（純粋関数）
4. [ ] 引当アルゴリズムの単体テスト（境界値、競合、欠品）
5. [ ] 引当ジョブ（BullMQ）の組み込み
6. [ ] PostgreSQL アドバイザリロックの統合
7. [ ] 受注 API への引当キック組み込み
8. [ ] 既存 ERP との連携 IF（変更なし、回帰テストのみ）
9. [ ] 受注キャンセル時の引当解放
10. [ ] 監視ダッシュボード（引当失敗率、平均遅延）
11. [ ] 旧手動引当画面の段階的廃止計画

tasks.md レビューの観点

• 1タスクが半日以内、1PRに収まる粒度か
• 依存関係が一方向のグラフになっているか（循環がないか）
• テスト・完了条件が明示されているか
• 「テストを書く」が独立タスクではなく、各タスクに内包されているか
• ロールバック手順が必要なタスクは記載されているか

SDD vs TDD vs DDD vs プロトタイプ駆動 — 4軸比較マトリクス

SDDの位置付けを正しく理解するには、隣接する手法と並べて比較するのが早道です。下表は6観点での4手法比較です。

これらは排他ではなく組み合わせて使うのが現実的です。たとえば「SDDで仕様を固めてからTDDで実装する」「DDDで業務を整理した上でSDDで仕様化する」「PoCはプロトタイプ駆動で素早く回し、本番化する瞬間にSDDへ昇格する」といった併用が現場で機能します。

いつ何を選ぶか — 意思決定の目安

• 業務担当との認識齟齬が頻発 → SDDから着手
• 安全性・正確性が要のロジック（金融計算・課金など）→ TDDを軸に
• 業務概念が複雑で整理が必要（保険・物流など）→ DDDで土台を作る
• 仮説検証・体験設計が主目的 → プロトタイプ駆動
• 上記が複合 → SDDをハブにTDD・DDDを呼び込む

SDDを支える主要4ツール比較（cc-sdd / Spec Kit / Kiro / claude-code-spec-workflow）

2026年時点で実務利用される主要4ツールを9観点で比較します。最新バージョンは2026年5月時点の情報で、変動が激しい領域のため必ず公式リポジトリのリリースノートも確認してください。

cc-sdd

cc-sdd は日本人開発者 gotalab 氏が開発する OSS で、AWS Kiro 互換の SDD ワークフローを Claude Code を含む 8 つの AI コーディングエージェントで使えるようにする国産ツールです。npx cc-sdd@latest --lang ja の1コマンドで導入でき、日本語完全対応・MIT ライセンス・週次の活発な更新が魅力です。

公式リポジトリ: github.com/gotalab/cc-sdd

GitHub Spec Kit

GitHub が公式提供する OSS で、/speckit.specify、/speckit.plan、/speckit.tasks、/speckit.implement の4スラッシュコマンドで4フェーズを進めます。GitHub Copilot・Claude Code・Cursor・Gemini CLI・Windsurf 等のクロスエージェント運用が可能で、ベンダーロックインを避けたい組織に向きます。

公式リポジトリ: github.com/github/spec-kit、ドキュメント: Spec Kit Documentation

AWS Kiro

AWS が 2025年11月に一般提供を開始した独自 IDE で、SDD を IDE 体験として最初から統合した「Agentic IDE」です。requirements → design → tasks → implementation の流れを GUI で進行でき、Property-Based Testing・MCP Governance・Model Governance といったエンタープライズ機能が揃います。Kiro 自身がオリジナルの SDD 文化を確立し、cc-sdd など他ツールにフォーマットを輸出した経緯があります。

公式: kiro.dev

claude-code-spec-workflow

Pimzino 氏が公開するコミュニティ製ワークフローで、Claude Code 専用に「新規機能」「バグ修正」の2系統で SDD を運用できる構成です。シンプルさを求める Claude Code 単独運用に向きます。

公式: github.com/Pimzino/claude-code-spec-workflow

選び方の目安

Claude Code 中心で日本語ドキュメントを重視するなら cc-sdd、複数エージェント横断で同じフォーマットを使いたいなら Spec Kit、IDE 一体で開発体験を最適化したいなら Kiro、Claude Code 単体でシンプルに始めたいなら claude-code-spec-workflow が向きます。実際は cc-sdd か Spec Kit を入口にし、必要に応じて Kiro IDE へ広げる構成が多く見られます。

cc-sdd 完全ガイド — Claude Code でSDDを始める最短ルート

cc-sdd は Claude Code から SDD を始めるうえで最もハードルが低いツールです。導入から運用まで一通り解説します。

インストール

プロジェクト直下で次のコマンドを実行します。

# 日本語対応版（推奨）
npx cc-sdd@latest --lang ja

# Claude Code 以外の AI エージェント向けプリセット
npx cc-sdd@latest --codex-skills --lang ja
npx cc-sdd@latest --cursor-skills --lang ja

実行すると、プロジェクトに次のディレクトリ構造が生成されます。

.kiro/
  specs/
    {feature-name}/
      requirements.md
      design.md
      tasks.md
      spec.json          # 進捗ステータス管理
.claude/
  commands/              # Claude Code 用スラッシュコマンド
  agents/                # サブエージェント定義

主要コマンド

cc-sdd v3 系では次のような17のSkillが提供されています。

推奨フロー

1. /kiro-discovery で「新機能 / バグ修正 / リファクタ」を分類
2. /kiro-spec-init {feature-name} でファイルを作成
3. /kiro-spec-requirements で要件を AI と対話で作成 → 業務担当レビュー → 承認
4. /kiro-spec-design で設計を生成 → アーキテクトレビュー → 承認
5. /kiro-spec-tasks でタスク分解 → 開発リードレビュー → 承認
6. /kiro-impl で実装フェーズへ。各タスクが TDD で実行され、PR まで自動進行

AWS Kiro との互換性

cc-sdd は Kiro のディレクトリ構造（.kiro/specs/...）とファイル命名（requirements.md / design.md / tasks.md）に忠実に従っているため、Kiro IDE と cc-sdd を併用しても spec を相互に読み書きできます。「Kiro IDE で仕様を書き、Claude Code で実装する」「Claude Code で書いた spec を Kiro IDE で可視化する」といった往復が可能です。

注意点

• Stable 対応は Claude Code と Codex、その他は Beta 扱いで挙動が変わる可能性あり
• 大規模リポジトリでは spec ディレクトリが膨らむので、.kiro/specs/ のディレクトリポリシーを早めに決めること
• /kiro-impl の autonomous モードはコストが嵩むため、初回は小機能で試算してから本格運用へ

Claude Code 固有の SDD 実践（Skills / Subagents / CLAUDE.md 連携）

Claude Code は SDD をプラグイン的に統合できる柔軟性が強みです。/add-feature などの Skill、Subagent、CLAUDE.md を組み合わせて、組織独自の SDD ワークフローを作れます。

Skill を使った SDD コマンド化

/add-feature を SDD 用に拡張すれば、対話的に requirements → design → tasks → implementation を進められます。Skill の定義例（抜粋）です。

---
name: add-feature
description: SDD で新規機能を実装する。requirements → design → tasks → impl の4フェーズを承認ゲート付きで進める。
---

# add-feature Skill

ユーザーが新規機能の実装を依頼したら、以下のフェーズを順に実行する。

1. requirements.md を `.steering/specs/{feature}/requirements.md` に生成
2. ユーザーに「requirements を承認しますか？」と確認
3. 承認後、design.md を生成し再承認
4. 承認後、tasks.md を生成し再承認
5. 承認後、各タスクを TDD で実装

各フェーズで承認が得られなければ前フェーズに戻る。

Skill の作り方はClaude Code Skillsガイドに詳しく説明しています。

Subagent への phase 委譲

requirements・design・tasks を別々の Subagent に委譲すると、コンテキストを分離して品質を保てます。

- requirements-agent: 業務理解とユーザーストーリー作成に特化
- design-agent: アーキテクチャ・ライブラリ選定に特化
- tasks-agent: 依存関係解析と粒度分解に特化
- impl-agent: TDD でコードを書く

各 Subagent は最小限のコンテキストだけ受け取るため、長いセッションでのコンテキスト汚染を防げます。Subagent 設計の考え方はClaude Codeサブエージェントガイドを参照してください。

CLAUDE.md に書く SDD ルール

プロジェクトの CLAUDE.md に SDD ルールを書いておくと、Claude Code がプロジェクト全体で SDD を前提に動作します。最低限書いておきたい項目は次の通りです。

## SDD ルール

- 新機能の依頼は必ず `/add-feature` から開始する
- `.steering/specs/{feature}/` 配下に requirements.md / design.md / tasks.md を生成する
- 各フェーズで人間の承認を得るまで次フェーズに進まない
- design.md には使用ライブラリの公式 URL を必ず記載する
- tasks.md の1タスクは1PR、半日以内、レビュー30分以内の粒度
- 仕様変更はコード変更より先に spec を更新し、spec の PR をマージしてからコード PR を出す

CLAUDE.md の書き方はCLAUDE.md 書き方ガイドに詳しく解説しています。

実例: 新規機能を SDD で通し開発（ユーザー検索機能）

ここまでの内容を踏まえて、1機能を SDD で通しで作るデモを示します。例題は管理画面のユーザー検索機能です。

Step 1: Requirements を作る

Claude Code で /add-feature ユーザー検索機能 を起動します。対話で次の点を詰めます。

• 検索キーは「名前」「メールアドレス」
• 名前は部分一致、メールは完全一致
• 結果は最大50件、ページネーション付き
• 権限のない一般ユーザーには検索フォームが見えない
• p95 レスポンスタイム 500ms 以内、検索インデックスを利用

これを requirements.md に落とし、業務担当レビューを通します。受け入れ基準は最低5つ、Given-When-Then 形式で書きます。

Step 2: Design を作る

Claude Code に「3案出してトレードオフ表で比較してください」と依頼します。Like 検索・全文検索・pg_trgm の3案が出てきたら、運用負荷とインデックスサイズで比較し採用案を確定します。design.md に確定版を書き、使用ライブラリの公式 URL を必ず記載します。

Step 3: Tasks を作る

Design からタスクを分解します。「マイグレーション」「API 実装」「権限ガード」「フロントエンド SearchForm」「ResultList」「ページネーション」「e2e テスト」の7タスクが目安です。各タスクが1PRで半日以内に終わる粒度になるよう微調整します。

Step 4: Implementation

tasks.md の順に Claude Code に実装させます。TDD と併用するなら、各タスクで「テストを書く（Red）→ 実装（Green）→ リファクタ」のサイクルを回します。完成したコードを PR に上げ、CI とコードレビューを経てマージします。

通しでかかる時間は機能規模にもよりますが、典型的な小機能なら半日〜1日、中規模機能で1〜3日、規模が大きいほど requirements/design に時間をかけるほど後工程の手戻りが減る傾向があります。

通し開発で気を付けたい3つのポイント

実例を通すうえで現場で躓きやすいポイントを3つ挙げます。

1. requirements を業務担当抜きで完成させてしまう: AIと開発者だけで requirements を仕上げ、業務担当に最終承認だけ求めると、業務理解が不足したまま実装が進みます。最低1回は業務担当を含む対面レビューを挟むこと。
2. design.md で技術選定の根拠を省略する: 採用ライブラリだけ書いて理由を書かないと、後から見直すときに判断のスタート地点が低くなります。「3案出して比較」を必ず実施し、不採用案も併記すること。
3. tasks.md の見積もりを楽観的に書く: 「テストは並行で書ける」「ライブラリ調査は不要」と楽観的に書くと、Implementation 段階で破綻します。各タスクに「想定外の調査時間」のバッファを15〜25%乗せておくこと。

これらは些細に見えますが、SDDの効果を半減させる致命傷になりやすい部分です。チェックリスト化してレビュー時に毎回確認することを推奨します。

TDD と SDD の併用パターン

SDD と TDD は補完関係です。4軸比較マトリクスで提示した通り、SDDは「何を作るか」を上流で固め、TDDは「どう動くべきか」を実装と同時に検証します。両者を併用すると、仕様レベルの認識齟齬と実装レベルのバグの双方を抑止できます。

併用する典型フローは次の通りです。

/add-feature
  → Requirements（受け入れ基準を Given-When-Then で書く）
  → Design（テスト戦略も合わせて記述）
  → Tasks（各タスクにテストタスクを内包）
  → Implementation（TDD: Red → Green → Refactor）

受け入れ基準を Given-When-Then で書くと、そのまま e2e テストや受け入れテストに変換できるため、SDD と TDD のつなぎがスムーズになります。詳細な TDD 運用はClaude Code TDDワークフローを参照してください。

業界別SDD適用パターン（業務SaaS / 製造業 / 金融 / SIer）

SDDの効果は業界特性に応じて出方が変わります。代表的な4業界での適用パターンを示します。

業務SaaS / Vertical SaaS

機能追加サイクルが2〜4週間と速く、リリースごとの影響範囲が広いことが特徴です。tasks.md の粒度を細かく保ち、依存関係と影響範囲を明示することで、複数チームの並行開発を可能にします。requirements.md には「既存の○○機能との影響範囲」を必須項目として入れ、影響箇所の回帰テストをタスクに必ず含めます。新機能の半数は既存機能の改修を伴うため、新規開発と保守の境界が曖昧になりがちですが、SDDで明示することで境界線を仕様書に閉じ込められます。

製造業（基幹系・MES・WMS）

長期保守が前提で、業務フローが既存資産として固定化されている領域です。requirements.md には現行業務フローを正確に転記し、変更点だけをマーキングする運用が向きます。design.md には画面遷移図とER図を必須化し、tasks.md にはデータ移行・並行稼働期間・切り戻し手順を含めます。SIer 連携が多い領域なので、外部連携 IF の章を design.md に独立させ、IF 仕様書のバージョンを spec から参照可能にしておくと、ベンダー間の認識齟齬が大幅に減ります。

金融（規制・監査対応）

要件が法令・社内規程に紐づき、変更履歴が監査対象になる領域です。requirements.md / design.md / tasks.md を git に保存することで、自然と監査証跡が確保されます。requirements.md に対応する法令条文や社内規程の番号を引用し、design.md には RPO / RTO / SLA を非機能要件として明記、tasks.md には「監査ログ追加」「監査画面確認」を独立タスクとして配置します。AI 生成の仕様書をそのまま提出してはならず、必ず人間の規程担当によるレビューを挟む運用が必要です。

SIer / 受託開発

顧客との合意形成が要の領域です。requirements.md を顧客と一緒に作るドキュメントと位置付け、変更要求は requirements.md の PR として処理します。design.md は受託側の責任範囲を明示し、tasks.md には顧客承認待ち期間を明示的に含めます。検収フェーズで「これは仕様にないので追加見積もり」という議論が起きたとき、requirements.md の該当バージョンを参照できるため、紛争予防の意味でも SDD は強力です。プロジェクト終了時にも、仕様書一式がそのまま納品物となり、保守フェーズへの引き継ぎが容易になります。

業界横断の共通ノウハウ

4業界に共通するノウハウとして、3点を補足します。1点目は「仕様書の言語を業務担当に合わせる」ことです。エンジニア向けの抽象表現を避け、業務用語をそのまま使って書きます。2点目は「変更履歴を仕様書のコミットメッセージに残す」ことです。feat:, change:, fix: などの prefix を仕様書 PR でも徹底すると、変更履歴がそのまま監査資料・引き継ぎ資料になります。3点目は「テンプレを業界別に分岐させる」ことです。すべての業界で同じテンプレを使うとフィットしない項目が出てくるため、業界別のサブテンプレを .steering/templates/{industry}/ のように用意するのが現実的です。

失敗パターン5選 × 回避策

SDDを導入してすぐに頓挫する典型パターンと、その回避策を5つ整理します。実際に koromo がプロジェクト支援で観測したパターンと、各種ブログで報告されているパターンを統合しています。

失敗1: 仕様膨張（spec creep）

「あれも書こう、これも書こう」と requirements に項目を追加し続け、結局誰も読まないドキュメントになるパターンです。回避策は MoSCoW（Must / Should / Could / Won't）分類で項目を強制的に分け、Must だけを今回のスコープに残すことです。Should 以下は「次フェーズ候補リスト」として別ファイル（backlog.md など）に逃がします。仕様膨張は「全部書けば安心」というプロダクトオーナーの心理から発生するため、「書かないものを決める」プロセスをチームの儀式として組み込むことが効きます。

失敗2: 過剰設計（over-engineering）

将来の不確実な拡張に備えて design.md にプラグイン機構や抽象クラスを盛り込みすぎ、初回実装が大幅に遅れるパターンです。回避策は design.md に「3案出して比較した上で2案を不採用」というセクションを必須化することと、Claude Code に「YAGNI（必要になるまで実装しない）の原則で書いてください」と明示することです。3年後の拡張を見据えた設計より、3週間後に変更しやすい設計の方が実務では強いことが多い、と覚えておきます。

失敗3: フォーマット崩壊（spec drift）

機能ごとに requirements.md の章立てがバラバラになり、横断検索や CI 検証が不可能になるパターンです。回避策はテンプレを .steering/templates/ 配下に固定し、/add-feature などの Skill から強制的にテンプレを呼び出すことです。CI で markdownlint と独自スキーマ検証を回せば、フォーマット逸脱はマージ前に検出できます。テンプレを更新したら、過去の spec を一度にマイグレートする必要はなく、新規からテンプレを適用していけば十分です。

失敗4: AIハルシネーション（架空API / 架空ライブラリ）

design.md にAIが架空のライブラリ名・架空のAPIエンドポイントを書き込み、そのまま実装まで進んで初めて気付くパターンです。回避策は design.md に使用ライブラリの公式URLを必ず記載するルールを徹底することです。AI に「このライブラリの公式リポジトリ URL を教えて」と聞き、URL を実際に開いて存在を確認してから設計に組み込みます。さらに、Claude Code に Web 検索ツールを与えてバージョンと API シグネチャを確認させると、ハルシネーションを大幅に減らせます。

失敗5: ステークホルダー巻き込み不足

requirements.md を開発者だけで書き、業務担当のレビューを通さずに実装に進むパターンです。完成後に「これは欲しかったものと違う」と差し戻され、SDD を導入しても結局手戻りが発生します。回避策は requirements レビューに最低2名（実装者＋業務担当）を必須化することと、業務担当が読める日本語で requirements を書くことです。専門用語が混ざるなら、巻末に用語集セクションを追加し、業務担当の音読チェックを通すと現場知との乖離が見えてきます。

失敗パターンに共通する根本原因

5つの失敗を並べると、共通する根本原因は「仕様書を書くこと自体が目的化し、何のためのSDDかを見失う」ことだと分かります。SDDの目的はあくまで「認識齟齬を減らし、手戻りを削減し、AIコーディングの精度を上げる」ことであり、テンプレに項目を埋めることでも、長い仕様書を書くことでもありません。導入時には「3ヶ月後に手戻りが減ったか」を計測し、減っていなければ運用を見直す、というKPI連動の運用を最初から設計しておくことを推奨します。

チーム導入ロードマップ（3-6ヶ月モデル）

SDDをチーム・組織に定着させるには段階的な導入が現実的です。1人のPoCから組織標準化までを3〜6ヶ月で進めるロードマップを示します。

Month 1: 個人PoC（1人 × 1機能）

最も SDD に共感したエンジニア1人が、自分の担当機能で SDD を試します。/add-feature または cc-sdd を導入し、requirements / design / tasks の各ファイルを作って通しで1機能を完成させます。この段階の KPI は「SDDで実装した機能と従来手法で実装した機能の手戻り回数の比較」です。1機能だけだとサンプルが小さいですが、感覚的な手応えは十分得られます。

落とし穴: 1人で完結する範囲だと SDD の最大効用（チームでの認識共有）が出ないため、レビューだけでもチームメンバーを巻き込んでください。

Month 2: チーム実験（3〜5人 × 2〜3機能）

PoCの手応えを共有した後、3〜5人のチームで2〜3機能を SDD で進めます。requirements レビュー会、design レビュー会、tasks 粒度確認会を週次で開催し、フォーマットの揺れや承認ゲートのリズムをチームで擦り合わせます。テンプレを .steering/templates/ に固定し、CI で markdownlint を回し始めます。KPIは「PRレビュー時の手戻りコメント数」「業務担当からの差し戻し件数」です。

落とし穴: フォーマット議論が紛糾すると本来の目的を見失います。「完璧なテンプレ」を目指さず、3ヶ月後に見直す前提で割り切ります。

Month 3-4: テンプレ整備・スキル化

チーム実験で得た知見をテンプレに反映し、/add-feature の Skill 定義に組み込みます。Subagent への phase 委譲、CLAUDE.md への SDD ルール記述、CI での spec 検証も整備します。並行して、SDD で書かれた spec を集めた .steering/specs/ ディレクトリのナビゲーションを整備し、過去の spec を参照しやすくします。KPIは「新規参画者の仕様キャッチアップ時間」「機能あたりの spec 作成時間（短縮されていれば学習が進んだ証）」です。

落とし穴: テンプレを過剰に厳格化すると、現場が「テンプレ通りに書くこと」を目的化してしまいます。テンプレは骨格だけにとどめ、章立て・項目数の柔軟性を残します。

Month 5-6: 組織標準化

複数チームに SDD を展開し、CI/CD・コードレビュー文化と統合します。spec の git 履歴を活用したリリースノート自動生成、spec から自動生成されるテスト雛形、spec ベースのドキュメントサイトといった応用も始まります。KPIは「組織全体での手戻り削減率」「新機能のリリースリードタイム」「障害発生時の原因がスペック不足だった割合」などです。

落とし穴: 強制力を強めすぎると「形だけのSDD」になります。チームの裁量を残しつつ、最低限の共通ルールだけを強制する温度感が肝です。

SDD導入の意思決定フレーム — 適用すべき / すべきでないプロジェクト

すべてのプロジェクトで SDD が有効とは限りません。導入判断の目安を整理します。

判断フローとしては次のようなパスが使えます。

1. プロジェクト期間が1ヶ月以上かつチーム規模が2人以上 → SDD適用候補
2. 規制・監査ありなら必須レベルで導入
3. 業務複雑性が高い、または AI コーディング比率が高ければ効果大
4. 短期 PoC（数日）はプロトタイプ駆動を優先
5. 1人で1日で終わる作業に SDD は過剰

PoC として「とりあえず1機能だけSDDで作ってみる」と判断を保留することも有効です。1回試して効果が見えなければ、その案件では撤退する自由を持っておきます。

コスト試算の簡易例

定性的な判断だけでなく、コスト試算でも判断できます。たとえば中規模機能を1つ作るのに、SDDで仕様作成に2日、実装に3日、合計5日かかると見込みます。SDDなしの場合、実装は2日で終わるかもしれませんが、認識齟齬・差し戻し・追加修正で平均2日かかるとすると合計4日。一見SDDのほうが時間がかかります。ところが保守フェーズに入ると、SDDありは仕様書を読めば0.5日で改修できるのに対し、SDDなしはコードを読み解く0.5日 + 仕様を再構成する1日 + 改修1日で合計2.5日になります。2回保守があれば SDD ありの累積コストが上回り、3回目以降は明確に SDD が安くなる、という構造です。保守頻度の高い領域ほどSDDの ROI が大きい、と覚えておくと判断しやすくなります。

ファイル名の単数複数問題 — requirement.md と requirements.md の表記揺れ

実務で意外と困るのが、ファイル名の単数複数問題です。requirement.md（単数）と requirements.md（複数）のどちらが正解か、というのはコミュニティ内でも揺れています。

事実上の標準は 複数形 requirements.md です。AWS Kiro と cc-sdd と GitHub Spec Kit がすべて複数形を採用しており、ツールチェーンを跨いでも互換性を保てます。新規にプロジェクトを始めるなら複数形を採用し、既存に requirement.md（単数）の慣習がある場合は次の見直しタイミングで移行する、というのが現場で機能する判断です。

なお、Google検索では requirements.md のほうがクエリ数・記事数ともに圧倒的に多く、SEO観点でも複数形が有利です。社内ドキュメントの統一だけでなく、検索性・引用しやすさの面でも複数形を推奨します。

Markdown 派生形式の差異にも注意

ファイル名の単数複数だけでなく、Markdown の派生形式にも差異があります。GitHub Flavored Markdown（GFM）、Commonmark、MDX、Notion 独自記法など、書き手によって表組みやリストのレンダリング結果が変わることがあります。AWS Kiro と cc-sdd と GitHub Spec Kit は基本的に GFM で書く前提なので、表組みは | 区切り、チェックリストは - [ ]、コードブロックは三重バックティック、という共通ルールでまとめると、ツール間で互換性を保てます。MDXのコンポーネントを使いたい場合は、コンポーネント呼び出しを .md ファイル末尾に集約するか、別ファイル notes.mdx に切り出すと、ツールのパーサが壊れないようにできます。

よくある質問

まとめと次のステップ

仕様駆動開発（SDD）は、「AIが速く書けるようになった今こそ、人間は仕様を正しく書くことに集中する」という分業の提案です。Claude Code に cc-sdd や /add-feature などのツールチェーンを組み合わせれば、requirements → design → tasks → implementation の4フェーズを数時間〜数日のサイクルで回せます。

導入の現実的な順序は次の通りです。

1. まず1機能を SDD で通しで回す（本記事の「実例」を参考に半日でPoC）
2. 業種別テンプレを .steering/templates/ に固定する
3. チームレビュー会のリズムを作り、フォーマットの揺れを擦り合わせる
4. CI / Skill / Subagent / CLAUDE.md と統合し、組織標準にする

SDDは万能ではなく、短期PoCや1人完結タスクには過剰です。「適用すべきプロジェクト」と「適用すべきでないプロジェクト」を見極める意思決定フレームを持っておくことが、形だけのSDDに陥らないコツです。導入後は3ヶ月単位で手戻り削減率や仕様レビュー時間といった指標を計測し、効果が見えない場合はテンプレや承認ゲートを見直す運用も合わせて設計しておくと、SDDが「形だけのプロセス」に劣化することを防げます。

次のステップとして、テスト駆動の併用はClaude Code TDDワークフロー、Skillsの作り方はClaude Code Skillsガイド、サブエージェント設計はClaude Codeサブエージェントガイド、CLAUDE.md の書き方はCLAUDE.md書き方ガイド、大規模リファクタはClaude Codeリファクタリングガイド、AIエージェント比較はAIコーディングエージェント比較を参照してください。

関連記事

• Claude Code完全ガイド
• Claude Code TDDワークフロー
• Claude Code Skillsガイド
• Claude Codeサブエージェントガイド
• CLAUDE.md書き方ガイド
• Claude Codeスラッシュコマンド集
• Claude Codeリファクタリングガイド
• AIコーディングエージェント比較 2026