100行のCLAUDE.mdより35行が効く理由 — 公式仕様で解く設定の最適化

CLAUDE.mdは長いほど効くわけではありません。むしろ長いほどClaude Codeは従いにくくなります。

100行書いたCLAUDE.mdと、35行に削って残りを.claude/rules/に分離したCLAUDE.md。同じ指示を出しても、後者の方がClaudeの出力品質が明らかに高いのです。

この記事では、なぜそうなるのかを公式仕様に基づいて解説し、「どの行を残し、どの行を移し、どの行を消すか」を1行単位で設計する方法論を紹介します。

CLAUDE.mdの注入メカニズム — なぜ「埋もれる」のか

User Messageとして注入される事実

公式ドキュメントにはこう書かれています。

CLAUDE.md adds the contents as a user message following Claude Code's default system prompt.
— Claude Code Memory Documentation

CLAUDE.mdはSystem Promptの一部ではなく、default system promptの後ろにUser Messageとして追加されます。起動時にはCLAUDE.mdの他にも、auto memory、MCP tool names、skillsの一覧など複数のstartup contextが読み込まれます。

この「User Messageである」という事実が、効果減衰の根本原因です。

4つの減衰メカニズム

CLAUDE.mdの効果が薄れるのは、単純な「古くなるから」ではありません。4つのメカニズムが複合的に作用しています。

1. 位置バイアス（Recency Bias）
LLMは全トークンを均等に扱いません。直近の発話に重みが寄ります。50ターン後のCLAUDE.mdは、最新のユーザー指示に対して相対的に弱い存在になります。

2. Attention希釈
コンテキスト内のトークン数が増えるほど、各トークンに割り当てられるAttentionは分散します。CLAUDE.mdの30行に注がれていた注意が、数千トークンの会話履歴に薄められます。

3. 命令の競合（Instruction Drift）
会話の中で「今回はテストは省略して」「この部分だけ例外で」といった一時的な指示が蓄積すると、CLAUDE.mdの元の方針と競合します。LLMは直近の指示を優先するため、元のルールが実質的に上書きされます。

4. 要約・圧縮の影響
Claude Codeは長い会話を内部的に圧縮（compact）します。この過程でCLAUDE.mdの内容は要約され、細かいニュアンスが失われる可能性があります。

ターン数と効果の関係

実運用での観測に基づく目安です。プロジェクトの複雑さやCLAUDE.mdの行数によって変動します。

ターン数	状態	対策
~10	ほぼ維持。CLAUDE.mdの指示通りに動く	特になし
10~30	軽微なブレ。細かいルールが守られないことがある	重要なルールは会話中で再提示
30+	明確に低下。行動原則レベルの指示も無視されうる	セッション分割 or /compact 後に再確認

公式ドキュメントでは「CLAUDE.md files should be under 500 lines per file」としつつ、実践的には短いほどadherence（遵守度）が高いと示唆しています。本記事ではこの性質を「注意資源の配分」として整理しています。

CLAUDE.mdの全行には注意コストがある

CLAUDE.mdの各行は、Claudeの限られた注意資源を消費します。行数そのものよりも、各行がどれだけの「判断改善」をもたらすかが重要です。

注意コストに見合う行

## 技術スタック
- Next.js 15 (App Router)          ← 効果: 極高。Pages Routerのコード生成を防ぐ
- TypeScript 5.7 (strict mode)     ← 効果: 高。anyを避け、型安全なコードになる

技術スタックのバージョン指定は、1行あたりの効果が最も高い記述です。「Next.js 15」と書くだけで、ClaudeはApp Router、Server Components、Server Actionsを前提としたコードを生成します。

注意コストに見合わない行

## コーディング規約
- インデントは2スペース              ← 効果: 低。Prettierで自動修正される
- セミコロンを付ける                 ← 効果: 低。ESLintで自動修正される
- import文はアルファベット順に並べる   ← 効果: 低。eslint-plugin-importで自動修正される

Linterやフォーマッターで強制できるルールは、CLAUDE.mdに書く優先度が低いです。Claudeが規約に沿わないコードを書いても保存時に自動修正されるため、貴重な注意資源を使う必要がありません。

公式ドキュメントには Use 2-space indentation のような例も掲載されています。Linter未導入のプロジェクトでは有効ですが、Linterが動いている環境ではより重要な指示に行を使う方が効果的です。

最も効果が高い行（見過ごされがち）

## 行動原則
- 3ステップ以上のタスクは必ずPlanモードで開始する

この1行の効果は計り知れません。Claudeが複雑なタスクにいきなりコードを書き始めて途中で破綻する問題を根本から防ぎます。

- コードを読まずに書かない。必ず既存コードを確認してから変更する

これも同様です。Claudeが既存の実装を無視して別のアプローチで書き直してしまう問題を防ぎます。

技術スタックや規約より、行動原則の方が注意コストあたりの効果が高い。これが実運用から得られた最も重要な知見です。

CLAUDE.mdに書くべき行、書くべきでない行

書くべき（CLAUDE.mdに残す）

セクション	効果	理由
プロジェクト概要（1-2行）	高	Claudeの全行動の文脈を決定する
技術スタック（バージョン付き）	極高	生成コードのAPI選択を直接制御する
コマンド一覧	高	テスト・ビルド実行の正確性に直結する
ディレクトリ構造	高	ファイル配置の正確性に直結する
行動原則	極高	Claudeの思考プロセス自体を制御する

書くべきでない（.claude/rules/ に移す）

セクション	効果	理由
コードスタイル詳細	低	Linter/Formatterで強制可能
テスト規約	中	テストファイル作業時のみ必要
セキュリティルール	中	常時必要だが詳細すぎると肥大化する
Git/コミット規約	低	コミット時のみ必要
エラーハンドリング規約	中	コード作業時のみ必要

書くべきでない（どこにも書かない）

内容	理由
古いコードスニペット	コードは変化する。CLAUDE.mdに貼ったスニペットは1週間で腐る
一般的なベストプラクティス	「DRYに書く」「SOLIDに従う」はClaudeが既に知っている
READMEの内容をコピペ	READMEは人間向け。Claudeに必要な情報は異なる

Conditional Rules — セッション後半でも効く仕組み

CLAUDE.mdから分離したルールの受け皿が .claude/rules/ です。

なぜCLAUDE.mdより効果的なのか

.claude/rules/ のファイルは、マッチするファイルをClaudeが扱う時にコンテキストに注入されます。

赤のCLAUDE.mdは50メッセージ前に埋もれていますが、緑のConditional Rulesは必要な時に直近の位置に注入されます。セッション後半でも高い効果を発揮します。

パス指定の実践例

.claude/rules/ ではfrontmatterの paths フィールドでルールの適用対象を指定できます。

paths はカンマ区切り（CSV形式）で記述します。YAML配列形式（- "..." のリスト）は内部パーサーのバグにより正しく処理されません（修正PR）。

.claude/rules/api-validation.md

---
paths: src/api/**/*.ts,src/routes/**/*.ts
---

# API バリデーション規約

- 全エンドポイントにZodスキーマでバリデーションを実装する
- リクエストボディ、クエリパラメータ、パスパラメータすべてが対象
- バリデーションエラーは422で返し、エラー詳細をレスポンスに含める

.claude/rules/react-components.md

---
paths: src/components/**/*.tsx,src/app/**/page.tsx
---

# React コンポーネント規約

- Server Componentsをデフォルトにする。"use client"は最小限に
- Propsは interface で定義し、コンポーネント直上に配置する
- children以外のレンダリングPropsは避ける

.claude/rules/testing.md

---
paths: "**/*.test.ts,**/*.test.tsx,**/*.spec.ts"
---

# テスト規約

- テスト名は「〜した場合、〜になる」形式
- モックは最小限に。実際のDB/APIを叩くintegration testを優先する
- テストデータはファクトリ関数で生成する

この構成により、Claudeがコンポーネントを書いている時にはReact規約が、テストを書いている時にはテスト規約が、それぞれ最適なタイミングで注入されます。

どこに何を書くかの判断表

行動原則の設計 — Claudeの思考プロセスを制御する

技術スタックは「何を作るか」を制御しますが、行動原則は「どう作るか」を制御します。注意コスト分析で最も効果が高いセクションです。

制御すべき3つの行動

1. 計画を立てさせる

- 3ステップ以上のタスクは必ずPlanモードで開始する
- プランには意図（なぜ必要か）と選択理由を含める
- 途中でうまくいかなくなったら、無理に進めず立ち止まって再計画する

Claudeは計画なしにコードを書き始める傾向があります。複雑なタスクでこれが起きると、途中で方針が破綻し、手戻りが大量に発生します。

2. 検証を強制する

- 動作を証明できるまでタスクを完了とマークしない
- テストを実行し、ログを確認し、正しく動作することを示す

「できました」と言われて確認したらエラーだった、という経験は誰にもあるはずです。検証の強制は、この手戻りコストを劇的に削減します。

3. コンテキストの自己管理を求める

- コードを読まずに書かない。必ず既存コードを確認してから変更する
- コンテキストが残り少ない場合、その旨を伝えて区切りを提案する
- リサーチ・調査はサブエージェントに委譲してメインコンテキストを節約する

コンテキストウィンドウが逼迫すると、Claudeは品質を犠牲にして作業を急ぐ傾向があります。品質を落とすくらいなら止まることを明示するルールです。

Before / After — 設定だけでなく、挙動がどう変わるか

Before: 行動原則なし（50行のCLAUDE.md）

# MyApp

## 技術スタック
- Next.js 15 (App Router)
- TypeScript 5.7
- Tailwind CSS v4

## コマンド
- npm run dev
- npm run build
- npm test

## コーディング規約
- 2スペースインデント
- セミコロンなし
- シングルクォート
- ファイル名はkebab-case
- コンポーネントはPascalCase
- 変数名はcamelCase
- constを優先
- 型アノテーション必須
- any禁止
- interface優先
- default export禁止（ページ除く）
... (以下、コードスタイルが30行続く)

問題点は3つあります。

1. コードスタイルに30行使い、行動原則がゼロ
2. Linterで強制できる内容が大半
3. Claudeの「どう働くか」が未定義

このCLAUDE.mdで「ユーザー認証機能を追加して」と依頼すると、Claudeは計画なしにいきなりコードを書き始め、途中で設計が破綻し、3回の手戻りが発生しました。

After: 注意資源を最適配分（35行のCLAUDE.md + 3つのrulesファイル）

# MyApp

React + TypeScriptで構築されたタスク管理アプリ。Supabaseをバックエンドに使用。

## 技術スタック
- Next.js 15 (App Router)
- TypeScript 5.7 (strict mode)
- Tailwind CSS v4 + shadcn/ui
- Supabase (PostgreSQL + Auth + Storage)

## コマンド
| コマンド | 用途 |
|---------|------|
| `npm run dev` | 開発サーバー |
| `npm run build` | ビルド |
| `npm test` | Vitest |
| `npm run e2e` | Playwright |

## ディレクトリ構造
| パス | 役割 |
|-----|------|
| `src/app/` | ページ・レイアウト |
| `src/components/` | UIコンポーネント |
| `src/lib/` | ユーティリティ |
| `src/types/` | 型定義 |

## 行動原則
- 3ステップ以上のタスクは必ずPlanモードで開始する
- 動作を証明できるまでタスクを完了とマークしない
- コードを読まずに書かない
- 変更は必要な箇所のみ。影響範囲を最小化する
- コンテキストが逼迫したら正直に伝える

コードスタイルは .claude/rules/code-style.md、テスト規約は .claude/rules/testing.md、セキュリティは .claude/rules/security.md にそれぞれ分離。

同じ「ユーザー認証機能を追加して」の依頼に対して、Claudeはまず計画を提示し、承認を得てから実装に入り、テストが通ることを確認してから完了を報告しました。手戻りはゼロです。

Afterの方が行数は少ないですが、行動原則の5行がClaudeの思考プロセスを直接制御しています。

パーソナリティ設計 — 「どんなClaudeと働くか」を定義する

行動原則の中でも特に効果が高いのが、パーソナリティとワークスタイルの指定です。

同じ「Reactコンポーネントを作って」という指示でも、パーソナリティによって出力が変わります。

パーソナリティ	出力の傾向
ミニマリスト	最小限のProps、最小限のstate。余計な抽象化をしない
設計品質重視	エッジケースを考慮した型設計。「もっと良い方法はないか」を自問する
自律型	周辺の型定義やユーティリティも自発的に作成。報告は結果のみ簡潔に
寄り添い型	「このアプローチでよいですか?」と確認しながら段階的に進める

どれが正解というわけではなく、プロジェクトのフェーズや作業内容によって最適解が変わります。

場面	推奨組み合わせ	理由
プロトタイプ段階	ミニマリスト + 自律型	スピード優先。余計な確認を減らす
本番コード	設計品質重視 + 慎重型	品質優先。破壊的変更の前に確認を取る
初めてのフレームワーク	メンター型 + 寄り添い型	学習優先。なぜそうするかを説明してもらう
レビュー依頼	論理的 + ファクトチェッカー	正確性優先。根拠を示し事実確認を行う

実際の指定例

## 行動原則

### パーソナリティ: 論理的 + ミニマリスト
- 結論ファーストで伝える
- 変更の根拠を必ず示す
- 説明は最小限。コードで語る
- 不要な抽象化・過剰設計を避ける

### ワークスタイル: 検証重視 + コンテキスト管理
- 動作を証明できるまで完了としない
- テスト実行・ビルド確認を省略しない
- コンテキストが逼迫したら正直に伝え、区切りを提案する
- リサーチはサブエージェントに委譲する

この組み合わせは「論理的で無駄のない実装をしつつ、品質保証は手を抜かない」Claudeを生み出します。

コピペ用: 最小CLAUDE.mdテンプレート

ここまでの知見を凝縮した、すぐに使えるテンプレートです。{...} 部分を自分のプロジェクトに合わせて書き換えてください。

# {プロジェクト名}

{1-2行のプロジェクト概要}

## 技術スタック
- {フレームワーク + バージョン}
- {言語 + バージョン}
- {主要ライブラリ}

## コマンド
| コマンド | 用途 |
|---------|------|
| `{dev command}` | 開発サーバー |
| `{build command}` | ビルド |
| `{test command}` | テスト |
| `{lint command}` | Lint |

## ディレクトリ構造
| パス | 役割 |
|-----|------|
| `{src dir}` | {役割} |
| `{components dir}` | {役割} |
| `{lib dir}` | {役割} |

## 行動原則
- 3ステップ以上のタスクは必ずPlanモードで開始する
- 動作を証明できるまでタスクを完了とマークしない
- コードを読まずに書かない
- 変更は必要な箇所のみ。影響範囲を最小化する
- コンテキストが逼迫したら正直に伝える

このテンプレートは約30行です。ここに自分のプロジェクト情報を埋め、パーソナリティやワークスタイルの行動原則を追加するだけで、効果的なCLAUDE.mdが完成します。

テンプレートをゼロから書くのが面倒な場合は、40以上の言語・フレームワークに対応したテンプレートとカスタムビルダーを用意しています。

CLAUDE.md ビルダー — この記事の設計原則をツール化した

ここまで解説してきた設計原則を、毎回手作業で適用するのは現実的ではありません。

そこで、この方法論をツール化したCLAUDE.md ビルダーを作りました。

ビルダー（カスタム生成）

8つのステップで選択するだけで、注意資源を最適配分したCLAUDE.mdを即座に生成します。

ステップ	選択内容
プロジェクト概要	名前と概要文（任意）
ベース	40+種の言語/FW（Frontend, Backend, Mobile, Infra, Data/AI, Game, Embedded）
ユースケース	個人開発 / チーム / OSS / エンタープライズ / プロトタイプ / 学習
レベル	初心者 / 中級者 / 上級者
役割	テックリード / パートナー / レビュアー等（複数可）
パーソナリティ	論理的 / ミニマリスト / メンター等（複数可）
ワークスタイル	検証重視 / 慎重 / 委譲型等（複数可）
トーン	丁寧 / カジュアル / 簡潔 / 詳細

右側のプレビューにリアルタイム反映されるので、選択しながら確認できます。

テンプレートをそのまま使いたい場合は、テンプレート一覧から検索・フィルタしてワンクリックでコピーできます。CLAUDE.mdの書き方を体系的に学びたい場合は、解説ガイドも用意しています。

まとめ — CLAUDE.mdのどこに書くかチェックリスト

判断基準	配置先
セッション開始直後に必要	CLAUDE.md
特定ファイル作業時のみ必要	.claude/rules/ (paths指定)
Linter/Formatterで自動修正可能	書かない
タスク固有の手順	skills

CLAUDE.mdの設計原則を一言でまとめると、**「少なく書いて、多く制御する」**です。

100行のCLAUDE.mdを35行に削って、削った分を .claude/rules/ に移す。それだけでClaudeの出力品質は変わります。