この記事の要点
仕様書駆動開発とは、実装の前に「何を作るか」を文章で固定し、その文章を唯一の指示源として実装・検証まで進めるやり方です。Claude Code でこれをやるとき、実務上の難所は仕様書の文章力ではありません。書いた仕様書が、必要なタイミングでモデルの文脈に入っているかどうかです。
Claude Code は仕様書という専用の機能を持っていません。代わりに、文章を文脈へ持ち込む経路が4つあります。CLAUDE.md、.claude/rules/ のルール、スキル、そして @ によるファイル参照です。この4つは読まれる条件がそれぞれ違います（Anthropic「How Claude remembers your project」）。仕様書を1か所に全部書くと、必ずどこかで読まれません。
この記事は、その振り分けから実装後の検証までを7手順にしたものです。
- 仕様を「恒久ルール・領域ルール・案件仕様」の3層に割る
- 案件仕様のひな形を、受け入れ条件が検証コマンドになる形で作る
- 恒久ルールを
CLAUDE.mdに、領域ルールをpaths付きルールに置く - plan mode で仕様書を実装計画に変換し、計画を人が直す
- 受け入れ条件で止める仕組みを
/goalか Stop フックで用意する - 仕様と実装のズレを
/code-reviewと検証サブエージェントで拾う - 非対話実行で CI に載せ、仕様書の更新を運用に戻す
対象読者は、Claude Code を日常的に使っていて、個人の使い方からチームの開発プロセスへ持ち上げたい開発者・テックリードです。コマンド・設定キー・バージョン条件は、すべて公式ドキュメントで実在を確認した値だけを書いています。業務への当てはめは末尾に「想定モデル事例」として分けて置きました。
1. 仕様を3層に割る。1つのファイルに全部書かない
最初にやることは、仕様書の分割です。分け方は内容ではなく、読まれるタイミングで決めます。
4つの経路は読まれる条件が違う
| 経路 | 読まれるタイミング | 向いている内容 |
|---|---|---|
CLAUDE.md |
毎セッションの開始時 | ビルド・テストコマンド、命名規約、常に守る規則 |
.claude/rules/（paths 付き） |
対象パターンのファイルを読んだとき | 特定ディレクトリ・特定拡張子だけの規約 |
| スキル | 名前で呼ばれたとき | 複数手順の作業手順書 |
@ でのファイル参照 |
その場で明示的に渡したとき | 案件ごとの仕様書 |
CLAUDE.md は毎回読まれるので確実ですが、その分だけ毎回の文脈を消費します。公式ドキュメントは「毎セッション保持してほしい事実」に限るよう書いており、多段手順や一部のコードにしか関係しない内容はスキルか paths 付きルールへ移すよう案内しています（Anthropic「How Claude remembers your project」）。
3層への割り当て
この条件差から、仕様は次の3層に割るのが素直です。
- 恒久ルール：プロジェクトが続く限り変わらない規約。
CLAUDE.mdに置く - 領域ルール：特定ディレクトリでだけ効く規約。
.claude/rules/にpaths付きで置く - 案件仕様：今回の変更で何を作るか。
docs/specs/などに置き、@で明示的に渡す
案件仕様を CLAUDE.md に書き足していくと、終わった案件の仕様が毎セッション読み込まれ続けます。逆に恒久ルールを案件仕様の中にだけ書くと、次の案件では守られません。層を跨いだ記述が、仕様書駆動が崩れる最初のきっかけになります。
2. 案件仕様のひな形を作る。受け入れ条件は検証コマンドで書く
案件仕様のひな形には、最低限この5節を置きます。
# 仕様: <変更の名前>
## 目的
（なぜこの変更が要るか。1〜3行）
## 対象範囲
- 変更してよいファイル / ディレクトリ
- 触ってはいけないファイル
## 受け入れ条件
- [ ] `npm test -- auth` が通る
- [ ] セッション期限切れ後のログインで 401 ではなく再認証へ遷移する
- [ ] 既存の API レスポンス形式を変えない
## 非対象
（今回はやらないこと。明示しないと勝手に広がる箇所）
## 参照
- src/auth/session.ts
- docs/adr/0007-session-strategy.md
受け入れ条件を「走るもの」にする
この5節のうち、実装の質を決めるのは受け入れ条件です。公式のベストプラクティスは、Claude に自己申告させず、テスト出力・実行したコマンドとその戻り・スクリーンショットといった証跡を出させるよう書いています（Anthropic「Best practices for Claude Code」）。
そのため受け入れ条件は「正しく動くこと」ではなく、そのまま実行できるコマンドか、誰が見ても真偽が割れない観測可能な状態で書きます。手順5で使う停止条件が、この行をそのまま使う形になります。
非対象の節を省かない
実務で効くのは「非対象」です。仕様書に書いていない部分をモデルが良かれと思って触ると、差分レビューの負荷が跳ね上がります。対象範囲で許可し、非対象で禁止する、の二重で書いておくと、手順4の計画段階でズレが表面化します。
3. 恒久ルールと領域ルールを置く
CLAUDE.md の置き場所は4つある
CLAUDE.md は複数の場所に置け、読み込み順が決まっています。組織全体の管理ポリシー、ユーザー個人、プロジェクト、ローカル個人の順で、後のものほど具体的な位置に入ります（Anthropic「How Claude remembers your project」）。
| 範囲 | 置き場所 | 用途 |
|---|---|---|
| 管理ポリシー | macOS は /Library/Application Support/ClaudeCode/CLAUDE.md、Linux と WSL は /etc/claude-code/CLAUDE.md |
組織共通の規約 |
| ユーザー | ~/.claude/CLAUDE.md |
全プロジェクト共通の個人設定 |
| プロジェクト | ./CLAUDE.md または ./.claude/CLAUDE.md |
チームで共有する規約 |
| ローカル | ./CLAUDE.local.md |
個人用。.gitignore に入れる |
仕様書駆動でチームに効かせたいのはプロジェクト層です。./CLAUDE.md か ./.claude/CLAUDE.md に置き、ソース管理に入れます。作業ディレクトリより上の階層にある CLAUDE.md と CLAUDE.local.md は起動時に読まれ、サブディレクトリのものは、そのディレクトリのファイルを読んだときに読み込まれます。
領域ルールは paths 付きで書く
ディレクトリごとに違う規約は .claude/rules/ に置き、YAML フロントマターの paths でスコープを絞ります。
---
paths:
- "src/api/**/*.ts"
---
# API 開発ルール
- すべての API エンドポイントは入力バリデーションを含める
- 標準のエラーレスポンス形式を使う
- OpenAPI ドキュメントコメントを付ける
paths が無いルールは無条件に読み込まれ、すべてのファイルに適用されます。paths 付きのルールは毎回のツール使用ではなく、パターンに一致するファイルを Claude が読んだときに発火します（Anthropic「How Claude remembers your project」）。
パターンは **/*.ts（任意のディレクトリの TypeScript ファイル）、src/**/*（src/ 配下すべて）、*.md（プロジェクト直下の Markdown）のように書きます。ブレース展開も使えますが、1つのルールの paths 全体で展開後1,000パターンと4 MiB の予算を共有し、超えるパターンは展開されないまま使われます。
なお paths の値にブレースグループを多数並べると、v2.1.217 より前のバージョンでは起動時に CLI が固まるか落ちていました。シンボリックリンク経由のファイルでの一致は v2.1.198 以降で動きます。設計・運用の細部はCLAUDE.md設計・運用ガイドの側にまとめています。
4. plan mode で仕様書を実装計画に変換する
仕様書ができたら、いきなり実装させません。plan mode に入れて、仕様書から実装計画を作らせます。
入り方は3つ
plan mode には3つの入り方があります。Shift+Tab をステータスバーに ⏸ plan mode on が出るまで押す、/plan をプロンプトから実行する、セッションを claude --permission-mode plan で開始する、のいずれかです。plan mode の間、Claude はファイルを読んで質問に答えますが、ディスクには一切書きません（Anthropic「Best practices for Claude Code」）。
/plan には説明を渡せます。/plan fix the auth bug のように書くと、plan mode に入ると同時にその作業から始まります（Anthropic「Commands」）。
公式が推奨する4フェーズ
公式のベストプラクティスは、探索・計画・実装・コミットの4フェーズを推奨しています。
- 探索：plan mode で対象コードを読ませる
- 計画：実装計画を作らせる。
Ctrl+Gで計画をテキストエディタに開いて直接編集できる - 実装：計画を承認するか
Shift+Tabで plan mode を抜け、計画と突き合わせながら実装させる - コミット：説明的なメッセージでコミットさせ、PR を作らせる
仕様書駆動でいちばん効くのは2の Ctrl+G です。計画は人が直す前提の中間成果物で、ここで仕様書との差を潰しておくと、実装後の手戻りがそのぶん減ります。
plan モードのサブエージェントは CLAUDE.md を読まない
ここに注意点があります。組み込みサブエージェントのうち Explore と Plan は、CLAUDE.md と親セッションの git status を読み飛ばします。調査を速く安く保つための仕様で、これ以外の組み込み・カスタムのサブエージェントは、定義で omitClaudeMd を設定しない限り両方を読み込みます（Anthropic「Create custom subagents」）。
つまり CLAUDE.md に書いた恒久ルールは、plan mode 中の調査フェーズでは効いていない可能性があります。案件仕様を @docs/specs/xxx.md の形でプロンプトに明示的に渡す運用が、ここで効きます。
計画のコストが割に合わない場合
公式は plan mode のオーバーヘッドも明記しています。誤字修正、ログ行の追加、変数名の変更のようにスコープが明確で差分が小さい作業は、計画を挟まず直接依頼するよう案内しています。判断の目安は「差分を1文で説明できるなら計画は省く」です。
計画が効くのは、アプローチが定まっていないとき、複数ファイルにまたがる変更のとき、対象コードに不慣れなときです。plan mode そのものの使い分けはClaude Code Plan Mode実践ガイドの側で扱っています。
5. 受け入れ条件で止める仕組みを用意する
仕様書駆動が形だけになる典型は、実装が終わったあと受け入れ条件を誰も確認しない状態です。ここを人手に頼らない形にします。
3段階の止め方
公式のベストプラクティスは、確認の強度を3段階で整理しています（Anthropic「Best practices for Claude Code」）。
- 1プロンプト内：チェックの実行と反復を同じメッセージで依頼する。今日すぐ使える
- セッション全体：
/goalに条件を設定する。毎ターン後に別の評価器が再チェックし、条件が解決するまで作業が続く - 決定的なゲート：
Stopフックがチェックをスクリプトとして実行し、通るまでターンの終了をブロックする
/goal は「条件が満たされるか、別の理由でゴールが解除されるまで作業を続ける」コマンドです。引数なしで実行すると現在または直近で達成したゴールを表示し、clear / stop / off / reset / none / cancel のいずれかで解除できます（Anthropic「Commands」）。
Stop フックの実体と、無限ループの上限
Stop フックは、メインエージェントが応答を終えたときに走ります。ユーザーの割り込みで止まった場合は走らず、API エラーのときは StopFailure が代わりに発火します。/goal はセッション単位のプロンプトベース Stop フックの組み込みショートカットという位置づけで、フック設定を書かずに条件を置きたいときに使うものです（Anthropic「Hooks reference」）。
自前でスクリプトを書く場合、終了コード2でブロックします。仕様書の受け入れ条件をそのままシェルに落とす形です。
#!/bin/bash
INPUT=$(cat)
if ! npm test 2>&1; then
echo "Tests not passing. Fix failing tests before completing." >&2
exit 2
fi
exit 0
無限に止め続ける事故は仕組みで防がれています。Claude Code は8回連続でブロックされるとフックを上書きしてターンを終了します。また Stop フックの入力には stop_hook_active が渡り、Stop フックの結果として既に継続中である場合に true になります。解決しない条件でブロックし続けないよう、この値を見るかトランスクリプトを処理してください。
整形や静的チェックは PostToolUse に寄せる
受け入れ条件のうち、編集のたびに走ってほしいものは Stop ではなく PostToolUse に置きます。settings.json にこの形で書きます。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
設定したフックは /hooks で確認できます。イベント一覧と設定済みの件数が出て、選ぶとイベント・マッチャー・種類・定義元ファイル・コマンドまで表示されます（Anthropic「Automate actions with hooks」）。フック全般の組み方はClaude Code Hooks実践ガイドの側で扱っています。
6. 仕様と実装のズレをレビューで拾う
停止条件を通っても、仕様書に書いた意図と実装が合っているとは限りません。テストが通る誤実装は普通に起きます。
/code-review は組み込みスキル
/code-review は組み込みスキルで、現在の差分か、渡した PR 番号・ブランチ・パスをレビューします。正しさのバグと整理の余地を見ます。--fix で指摘を適用、--comment で GitHub の PR か GitLab のマージリクエストに投稿、ultra で深いクラウドレビューを走らせます。エイリアスは /review です（Anthropic「Commands」）。
GitLab のマージリクエストへの投稿は Claude Code v2.1.257 以降が必要です。ultra を github.com の PR に対して使うとき、--post で投稿を先に選択した状態で起動ダイアログを開けますが、これは v2.1.227 以降です。
なお、プロジェクトに code-review という名前のスキルを置くと組み込みを置き換えますが、エイリアスの /review は置き換わらず、自作スキルを呼びません（Anthropic「Extend Claude with skills」）。仕様書の受け入れ条件に沿ったレビュー観点を自前で持たせる場合、チームには /code-review を使わせる、と決めておく必要があります。
書いた本人に採点させない
公式は「第二の意見」という形も挙げています。検証サブエージェントか、自分の所見を自分で検証する動的ワークフローを使うと、新しいモデルが結果を反証しにいくので、作業した当人が採点する構図を避けられます（Anthropic「Best practices for Claude Code」）。
サブエージェントは自分の文脈ウィンドウ、独自のシステムプロンプト、限定されたツール権限、独立した権限設定を持ちます。仕様書駆動では「仕様書と差分だけを渡し、逸脱を列挙させる」役を作ると噛み合います。サブエージェントの説明文は全部が文脈を食うため短く保ち、詳細は各サブエージェントのシステムプロンプト側に移します。組み込み以外のサブエージェントの説明文の合計が15,000トークンを超えると、起動時に合計トークン数つきの警告が出ます（Anthropic「Create custom subagents」）。
サブエージェントの分け方はClaude Codeサブエージェント並列開発入門の側で扱っています。
7. 非対話実行でCIに載せ、仕様書を運用に戻す
最後に、ここまでの仕組みを人が見ていない時間にも効かせます。
パイプで渡す
Claude Code は非対話でも動きます。標準入力と標準出力が Unix ツールと同じように使えるので、CI、pre-commit フック、バッチ処理に組み込めます（Anthropic「Common workflows」）。
git log --oneline -20 | claude -p "summarize these recent commits"
仕様書駆動でこれを使うなら、差分と仕様書を渡して逸脱を出させる形になります。
git diff origin/main...HEAD | \
claude -p "この差分を docs/specs/session-refresh.md の受け入れ条件と突き合わせ、満たしていない条件だけを列挙してください"
仕様書を「書き足す場所」として使い続ける
仕様書駆動を1回のプロジェクトで終わらせないために、公式が CLAUDE.md について挙げている追記のきっかけがそのまま使えます（Anthropic「How Claude remembers your project」）。
- Claude が同じ間違いを2回した
- コードレビューで、Claude が知っているべきだったことが指摘された
- 前のセッションでも打ったのと同じ修正・補足をチャットに打った
- 新しいチームメンバーが同じ文脈を必要とする
この4つが起きたら、その場の会話で直さず、どの層に書くかを決めてファイルへ戻します。恒久ルールなら CLAUDE.md、特定ディレクトリの話なら paths 付きルール、今回の案件の話なら案件仕様です。この戻し作業をしない限り、仕様書は初回だけ立派なドキュメントになって古びます。
設定が効いていないときの確認手順
書いたのに効いていない、という状態は仕様書駆動でいちばん時間を溶かします。公式には設定のデバッグ手順があり、/context、/doctor、/hooks、/mcp で実際に何が読み込まれたかを見る形になっています（Anthropic「Debug your configuration」）。settings.json の書き方そのものはClaude Code settings.json設定完全ガイドの側にまとめています。
想定モデル事例：SaaS開発チームが仕様書駆動へ切り替える（想定）
ここからは公式ドキュメントの仕様ではなく、上の制約から素直に導ける想定モデル事例です。実在の企業・実測値ではありません。実際の配分は各チームで決めてください。
前提（想定）
- Web SaaS のバックエンド、TypeScript、テストは
npm test - 開発者5名。Claude Code は個人裁量で使われており、プロンプトの粒度が人によってばらばら
- 症状：実装は速いが、レビューで「そこは今回変えなくてよかった」という指摘が繰り返し出る
置いたもの（想定）
| 層 | 置き場所 | 内容 |
|---|---|---|
| 恒久ルール | ./CLAUDE.md |
ビルド・テストコマンド、エラーレスポンス形式、触ってはいけない生成物ディレクトリ |
| 領域ルール | .claude/rules/api.md（paths: src/api/**/*.ts） |
入力バリデーション必須、OpenAPI コメント必須 |
| 案件仕様 | docs/specs/<チケット番号>.md |
目的・対象範囲・受け入れ条件・非対象・参照 |
回し方（想定）
- チケットを切った人が
docs/specs/にひな形を埋める。受け入れ条件はnpm test -- <対象>の形まで落とす - 実装者は
/planで入り、@docs/specs/<番号>.mdを渡して計画を作らせる Ctrl+Gで計画を開き、非対象に触れている手順を消す- plan mode を抜けて実装させ、
/goalに受け入れ条件を置いて止める /code-reviewを差分に当て、別途、仕様書と差分だけを渡す検証サブエージェントで逸脱を列挙させる- レビューで出た指摘のうち、毎回出るものを
CLAUDE.mdかpaths付きルールへ戻す
この形にすると、レビュー指摘の主語が「この書き方は好みじゃない」から「仕様書のこの行を満たしていない」に寄ります。仕様書駆動の実利はコード生成の速さではなく、議論の対象が文章に固定されることの側にあります。
よくある質問
Claude Codeに「仕様書機能」はありますか
専用機能はありません。CLAUDE.md、.claude/rules/、スキル、@ でのファイル参照という4つの経路を組み合わせて仕様書を渡します。どれも読み込まれる条件が違うため、1か所にまとめず層で分けます。
仕様書はCLAUDE.mdに書いてはいけませんか
恒久的な規約なら書きます。案件ごとの仕様を書き足していくと、終わった案件の内容も毎セッション読み込まれます。公式は、多段手順や一部のコードにしか関係しない内容はスキルか paths 付きルールへ移すよう案内しています。
plan modeにはどうやって入りますか
3つあります。Shift+Tab をステータスバーに ⏸ plan mode on が出るまで押す、/plan を実行する、claude --permission-mode plan でセッションを開始する、です。/plan fix the auth bug のように説明を渡すと、その作業から始まります。
作られた計画を人が直せますか
plan mode で Ctrl+G を押すと、計画がテキストエディタで開き、Claude が進む前に直接編集できます。
受け入れ条件を満たすまで作業を続けさせるには
/goal に条件を設定します。毎ターン後に別の評価器が再チェックし、条件が解決するまで作業が続きます。スクリプトで決定的に止めたい場合は Stop フックを使い、終了コード2でブロックします。
Stopフックで無限ループになりませんか
Claude Code は8回連続でブロックされるとフックを上書きしてターンを終了します。あわせて、Stop フックの入力に渡る stop_hook_active を見て、解決しない条件でブロックし続けないようにします。
plan modeは毎回使ったほうがいいですか
公式はオーバーヘッドも明記しています。誤字修正やログ行の追加のようにスコープが明確で差分が小さい作業は、計画を挟まず直接依頼するよう案内しています。目安は「差分を1文で説明できるなら計画は省く」です。
CLAUDE.mdに書いたルールが調査中に効いていない気がします
組み込みサブエージェントの Explore と Plan は、CLAUDE.md と親セッションの git status を読み飛ばします。これ以外の組み込み・カスタムのサブエージェントは、定義で omitClaudeMd を設定しない限り両方を読み込みます。
自作の code-review スキルを置けば /review も置き換わりますか
置き換わりません。プロジェクトの code-review スキルは /code-review を置き換えますが、組み込みのエイリアスである /review は自作スキルを呼びません。
運営元 Uravation よりこの事例を自社の業務で試す場合のテーマ選定・評価・本番移行の確認項目を、無料のチェックリストにまとめています。 Claude Code業務自動化PoCチェックリストを受け取る（無料）
参考・出典
- Anthropic「How Claude remembers your project」（Claude Code ドキュメント）
- Anthropic「Best practices for Claude Code」（Claude Code ドキュメント）
- anthropics/claude-code CHANGELOG（v2.1.257 の /code-review GitLab 対応など版ごとの変更点）（GitHub）
- Anthropic「Common workflows」（Claude Code ドキュメント）
- Anthropic「Hooks reference」（Claude Code ドキュメント）
- Anthropic「Automate actions with hooks」（Claude Code ドキュメント）
- Anthropic「Create custom subagents」（Claude Code ドキュメント）
- Anthropic「Commands」（Claude Code ドキュメント）
- Anthropic「Extend Claude with skills」（Claude Code ドキュメント）
- Anthropic「Debug your configuration」（Claude Code ドキュメント）
