Claude Code仕様駆動開発ガイド｜CLAUDE.mdとドキュメント管理の実践

Claude Codeを使ったプロジェクト開発で、こんな経験はありませんか？

「指示したはずなのに、全然違うコードが生成された」
「何度も同じ修正を繰り返している」
「コンテキストが長くなると精度が落ちる」

**これらの問題の多くは、仕様駆動開発のアプローチで解決できます。**CLAUDE.mdとドキュメント管理を適切に設計すれば、Claude Codeは驚くほど正確にコードを生成してくれます。

この記事では、仕様駆動開発の考え方からCLAUDE.mdの具体的な設計パターン、そして実践的なワークフローまでを詳しく解説します。

Claude Code仕様駆動開発のワークフロー図解

仕様駆動開発とは？Claude Codeとの相性が良い理由

仕様駆動開発（Specification-Driven Development）とは、コードを書く前に仕様を明確に定義し、その仕様に基づいて実装・検証を行う開発手法です。

Claude Codeとの相性が良い理由は明確です。

LLMはコンテキストに依存する：明確な仕様 = 良いコンテキスト
再現性が高い：同じ仕様からは同じ品質のコードが生成される
レビューが容易：仕様と実装の差分を確認するだけ
チーム共有が簡単：仕様書がそのままClaude Codeへの指示書になる

従来のTDD（テスト駆動開発）が「テストを先に書く」のに対し、仕様駆動開発は「仕様を先に書く」アプローチです。Claude Codeが仕様を読み取って、テストとコードの両方を生成してくれます。

CLAUDE.mdの設計原則｜200行ルールとモジュール分割

プロジェクト概要・アーキテクチャ・コーディング規約の書き方

CLAUDE.mdは**Claude Codeがプロジェクトを理解するための「設計図」**です。Anthropic公式が推奨するCLAUDE.mdガイドの基本に加え、以下の構成が効果的です。

# CLAUDE.md

## プロジェクト概要
- サービス名、目的、主要機能の概要

## アーキテクチャ
- 技術スタック、ディレクトリ構成、データフロー

## コーディング規約
- 命名規則、エラーハンドリング、テストポリシー

## 重要な制約
- セキュリティ、パフォーマンス、互換性の要件

## よくある間違い
- 過去にClaude Codeが犯したミスとその修正方法

200行ルール：CLAUDE.mdは200行以内に収めることが推奨されています。それ以上になる場合は、モジュール分割を検討しましょう。

グローバルCLAUDE.md vs プロジェクトCLAUDE.md

Claude Codeは複数のCLAUDE.mdを階層的に読み込みます。

~/.claude/CLAUDE.md：グローバル設定。コーディングスタイルや個人的な好み
プロジェクトルートのCLAUDE.md：プロジェクト固有の仕様
サブディレクトリのCLAUDE.md：モジュール固有の仕様

この階層構造を活用することで、共通ルールと個別仕様を効率的に管理できます。

/docs ディレクトリの構成パターン

仕様書・API定義・ADR（Architecture Decision Record）

仕様駆動開発では、/docsディレクトリが「真実の源泉」（Single Source of Truth）になります。

/docs
├── specs/           # 機能仕様書
│   ├── auth.md      # 認証機能の仕様
│   ├── payment.md   # 決済機能の仕様
│   └── search.md    # 検索機能の仕様
├── api/             # API定義
│   ├── openapi.yaml # OpenAPI仕様
│   └── graphql/     # GraphQLスキーマ
├── adr/             # Architecture Decision Records
│   ├── 001-database-choice.md
│   └── 002-auth-strategy.md
└── guides/          # 開発ガイド
    ├── setup.md
    └── deployment.md

Claude Codeが読みやすいMarkdown構造

Claude Codeが仕様書を正確に読み取るためのMarkdown構造には、いくつかのベストプラクティスがあります。

H2で機能単位に分割：1つのH2セクション = 1つの機能
入出力を明示：「入力：○○、出力：○○、エラー時：○○」
具体例を含める：JSON形式のリクエスト/レスポンス例
制約を明記：バリデーションルール、レート制限など

ワークスペース管理ガイドも参考に、プロジェクト全体の構成を最適化しましょう。

仕様→計画→実装→検証の4フェーズワークフロー

Plan Modeで仕様レビュー

Claude CodeのPlan Modeは、仕様駆動開発の「計画」フェーズに最適です。

Plan Modeでの仕様レビューの手順：

仕様書を/docs/specs/に作成
Claude Codeに「この仕様をレビューして」と依頼
矛盾点・不足点の指摘を受ける
仕様を修正して再レビュー
仕様が固まったら実装フェーズへ

Plan Modeでは実際のコード変更は行われないため、安全に仕様の品質を高められます。

実装指示の出し方（スコープ限定のプロンプト設計）

仕様が固まったら、実装指示を出します。ここでのポイントはスコープの限定です。

Anthropic公式ドキュメントでも、Claude Codeに対する指示は「1つのタスクに1つの指示」が推奨されています（出典：Anthropic Claude Code Documentation）。

良い指示の例：

/docs/specs/auth.md の「ログイン機能」セクションに基づいて、
src/auth/login.ts を実装してください。
テストも src/auth/__tests__/login.test.ts に作成してください。

悪い指示の例：

認証機能を全部作って。

コンテキスト管理｜60%ルールとファイル退避戦略

Claude Codeの精度を維持するために、コンテキストウィンドウの60%以上を使わないようにしましょう。

不要なファイルを参照に含めない
大きなファイルは要約を作成して参照させる
完了したタスクのコンテキストはクリアする
/compactコマンドでコンテキストを圧縮

コンテキストが増えすぎると、Claude Codeの「注意力」が分散し、仕様の重要な部分を見落とす可能性が高まります。

カスタムコマンドで仕様確認を自動化する

Claude Codeのカスタムスキルを使えば、仕様確認のプロセスを自動化できます。

.claude/commands/ディレクトリにコマンドを定義：

# spec-check.md
以下の手順で仕様との整合性を確認してください：
1. /docs/specs/ から該当する仕様書を読む
2. 実装されたコードと仕様を比較
3. 差分があれば報告
4. テストカバレッジを確認

/spec-check auth のように呼び出すことで、手動確認の手間を大幅に削減できます。

チーム開発での運用ベストプラクティス

仕様駆動開発をチームで運用する際のポイントをまとめます。

仕様のバージョン管理：Gitで仕様書も管理。PRレビューの対象に含める
CLAUDE.mdのオーナーシップ：テックリードが管理し、チームでレビュー
仕様テンプレート：チーム共通のテンプレートを用意して品質を統一
仕様レビュー会：週1回、30分の仕様レビューを実施
ADRの活用：技術的な判断の記録を残し、後からの「なぜ？」に答えられるように

プロンプトエンジニアリングガイドの知見を仕様書の書き方に応用すると、さらに効果的です。

まとめ｜仕様駆動で「手戻りゼロ」を目指す

仕様駆動開発は、Claude Codeの力を最大限に引き出すための開発手法です。

CLAUDE.mdを200行以内で設計し、プロジェクトの設計図とする
/docsディレクトリを真実の源泉として管理する
Plan Modeで仕様をレビューしてから実装に進む
スコープを限定した指示で精度を高める
コンテキスト管理で60%ルールを守る

「仕様を書く時間がもったいない」と感じるかもしれませんが、手戻りの時間と比較すれば圧倒的に効率的です。仕様に1時間投資すれば、実装で10時間を節約できる——これが仕様駆動開発の本質です。

Claude Codeの活用法をさらに深く学びたい方は、Claude Code完全攻略シリーズをご覧ください。最新のテクニックを随時更新しています。