お問い合わせ

Claude Codeの出力品質は、CLAUDE.mdの設計で大きく変わります。 同じプロンプトでも、CLAUDE.mdの有無と書き方によって、コードの一貫性・命名規則の遵守・テストの網羅性に明確な差が出ます。

この記事では、CLAUDE.mdの構造設計からデザインパターン、よくある失敗まで、実際のOSSリポジトリの事例とベンチマークデータをもとに解説します。

CLAUDE.mdとは何か

CLAUDE.mdは、Claude Codeがプロジェクトで作業する際に自動的に読み込む指示書です。 プロジェクトのルート、サブディレクトリ、またはホームディレクトリに配置します。 役割は「人間の新メンバーに渡すオンボーディングドキュメント」に近いものです。

プロジェクトルート/
├── CLAUDE.md              # プロジェクト全体のルール
├── src/
│   ├── CLAUDE.md          # srcディレクトリ固有のルール
│   └── components/
│       └── CLAUDE.md      # コンポーネント固有のルール
└── tests/
    └── CLAUDE.md          # テスト固有のルール

Claude Codeは作業対象のディレクトリに応じて、該当するCLAUDE.mdを階層的に読み込みます。 ルートがプロジェクト全体のルール、サブディレクトリが局所的なルールを定義する構造です。

推奨行数：Anthropicは200行以下を推奨

CLAUDE.mdの行数は、品質に直接影響します。 Chroma（2025）のベンチマークでは、18のフロンティアモデルを対象に入力トークン数と回答精度の関係を測定しました。 精度は入力量が少ないときの95%から、入力量が増えるにつれて60%まで低下しました。

つまり、CLAUDE.mdに情報を詰め込みすぎると、かえって指示の遵守率が下がります。 「何を書くか」より「何を書かないか」の判断が重要です。

行数用途備考
〜50行個人の小規模プロジェクト最低限のルールのみ
100〜200行標準的なプロジェクトAnthropic推奨範囲
200〜400行大規模・複雑なプロジェクトサブディレクトリ分割を検討
400行超非推奨精度低下のリスク

CLAUDE.mdの基本構造

効果的なCLAUDE.mdは、以下の5セクションで構成されます。

セクション1：プロジェクト概要（5〜10行）。 プロジェクトが何であるか、技術スタック、対象ユーザーを簡潔に記述します。

セクション2：コーディング規約（20〜40行）。 命名規則、ファイル構成、インポート順序、型定義の方針を記述します。

セクション3：アーキテクチャの方針（20〜40行）。 ディレクトリ構造、データフロー、状態管理の方針を記述します。

セクション4：禁止事項（10〜20行）。 やってはいけないことを明確に列挙します。AIは「やるべきこと」より「やってはいけないこと」の方を正確に守る傾向があります。

セクション5：テスト方針（10〜20行）。 テストの書き方、カバレッジの基準、テストファイルの配置を記述します。

以下に、セクション2と4の記述例を示します。

## コーディング規約

- TypeScript strict mode必須。anyは使わない
- コンポーネント: PascalCase（例: BlogCard.astro）
- ユーティリティ: camelCase（例: formatDate.ts）
- CSS: Tailwind CSSのユーティリティクラスのみ。カスタムCSSは原則禁止
- インポート順序: 外部ライブラリ → 内部モジュール → 型定義

## 禁止事項

- console.logをコミットしない
- anyの使用禁止
- インラインスタイル禁止
- 1ファイル300行超は分割する
- 外部APIキーをコードにハードコードしない

実際のOSSリポジトリに学ぶ設計パターン

anthropics/claude-code（公式テンプレート）。 Anthropic自身のリポジトリが、CLAUDE.mdの公式リファレンスです。プロジェクトの概要、ビルドコマンド、コーディング規約、テスト方針が簡潔にまとまっています。

sst/opencode（TypeScriptモノレポ）。 パッケージ間の依存関係、共有型定義のルール、ビルド順序の制約が明記されている好例です。

supabase/supabase（ポリグロットプラットフォーム）。 複数言語（TypeScript、Go、Elixir）を横断するプロジェクトで、言語ごとの規約をサブディレクトリのCLAUDE.mdで分離する設計が参考になります。

これらの事例は、josix氏が運営するawesome-claude-md（josix.github.io/awesome-claude-md/）で閲覧できます。 2025年時点で108件の実際のCLAUDE.mdが収集・分類されています。

コンテキストエンジニアリングという考え方

Sourcegraphのブログでは、「コンテキストエンジニアリング」を独立した技術領域として提唱しています。 AIに渡す文脈の設計が、出力品質を決定する最大の要因であるという主張です。 CLAUDE.mdは、このコンテキストエンジニアリングの具体的な実装手段です。

CLAUDE.mdの設計に当てはめると、3つの原則になります。

原則1：関連性。 現在のタスクに必要な情報だけを含めます。ディレクトリごとに分割します。

原則2：簡潔性。 Chromaベンチマークが示すように、入力が増えるほど精度は下がります。1つのルールは1行で書きます。

原則3：構造化。 見出し、箇条書き、コードブロックで構造化します。自然言語の長文より構造化されたフォーマットの方がAIの遵守率が高くなります。

AGENTS.md標準：クロスツール互換への動き

OpenAIはCodex向けにAGENTS.md仕様を策定し、2025年12月にLinux FoundationのAgentic AI Foundationに寄贈しました。 2025年8月時点で20,000以上のリポジトリがAGENTS.mdを採用しています。

AGENTS.mdの目的は、CLAUDE.md、.cursorrules、copilot-instructions.mdなど、ツールごとに分散したAI指示書を統一することです。 現時点では、共通のルールをAGENTS.mdに、Claude Code固有の指示をCLAUDE.mdに書く併用構成が推奨されます。

プロジェクトルート/
├── AGENTS.md          # ツール共通のルール
├── CLAUDE.md          # Claude Code固有の追加ルール
├── .cursorrules       # Cursor固有の追加ルール（必要に応じて）
└── ...

よくある失敗パターン

失敗1：情報の詰め込みすぎ。 CLAUDE.mdに500行以上書いて、指示の遵守率が下がるケースです。200行以下に収め、不要になったルールは定期的に削除します。

失敗2：曖昧な表現。 「きれいなコードを書く」のような曖昧な指示は解釈の幅が広すぎます。「関数は50行以内」「エラーはResult型で返す」のように具体的な基準を示します。

# 悪い例
- コードは読みやすく書く
- 適切にテストを書く

# 良い例
- 関数は50行以内。超える場合は分割する
- publicな関数には必ずJSDocコメントを付ける
- ユーティリティ関数のテストカバレッジは80%以上

失敗3：矛盾するルール。 異なるセクションで矛盾するルールを書くと、AIの出力が不安定になります。変更時は既存ルールとの整合性を確認します。

失敗4：更新の放置。 プロジェクトの進化に伴い内容が実態と乖離するケースです。スプリントの振り返りやPRレビューの際に更新を確認する習慣を作ります。

チームでのCLAUDE.md運用

チーム開発では、CLAUDE.mdをバージョン管理に含め、PRレビューの対象にします。 運用のポイントは3つです。

  1. 個人の好みとチームの規約を分離します。~/.claude/CLAUDE.mdに個人の設定を書き、プロジェクトのCLAUDE.mdにはチーム共通のルールだけを書きます。
  2. CLAUDE.mdの変更にはレビューを必須にします。CIで行数チェックを入れるのも有効です。
  3. 新しいルールを追加する前に、既存のルールで対応できないかを検討します。ルールの数は増やすより減らす方が効果的です。

実践的なCLAUDE.mdの例

以下は、Astro + TypeScriptのコンテンツサイトにおけるCLAUDE.mdの全体例です。

# プロジェクトルール — テックメディア

Astro + TypeScript + Tailwind CSSで構築された技術メディア。
対象読者はエンジニアとマーケティング担当者。

## 技術スタック

- Astro 5.x（SSG）/ TypeScript strict / Tailwind CSS v4
- コンテンツ: Astro Content Collections / デプロイ: Vercel

## コーディング規約

- anyは使わない。コンポーネント: PascalCase.astro、ユーティリティ: camelCase.ts
- 1ファイル250行以内。インポート順: 外部 → 内部 → 型 → スタイル

## コンテンツルール

- フロントマターは定義済みスキーマに従う。見出しは##から開始
- 1段落3行以内。「感嘆符」禁止

## 禁止事項

- console.logのコミット禁止。インラインスタイル禁止
- 画像にwidth/heightを必ず指定。外部APIキーのハードコード禁止

## テスト

- Vitest使用。ユーティリティ関数は必須。テストファイルは .test.ts

まとめ

CLAUDE.mdは、Claude Codeの出力品質を安定させるための最も重要な設計ドキュメントです。 Chromaベンチマークが示すように、簡潔さが精度に直結するため、200行以下を目標に設計します。

効果的なCLAUDE.mdの要件は3つです。 具体的であること（曖昧な表現を避ける）、簡潔であること（不要なルールを削る）、構造化されていること（見出しと箇条書きで整理する）。

awesome-claude-mdの108件の事例や、anthropics/claude-code、sst/opencode、supabase/supabaseなどの実際のリポジトリを参考に、自分のプロジェクトに最適なCLAUDE.mdを設計してください。

参考文献