本シリーズ（全3回）: ① OSS導入編 → ② Two-Tier Context Strategy 編（本記事）→ ③ [チーム展開・運用編]
正直に書きます。
自分の CLAUDE.md（Claude Codeの設定ファイル）は、ある時期200行を超えていました。AIが変なコードを書くたびにルールを追記して、「これだけ書けば大丈夫だろう」と思っていました。
でも、体感としてむしろ品質が下がっている気がしました。セキュリティを細かく指定すると命名が雑になり、命名を追記するとエラー処理が抜けます。モグラ叩き状態でした。
「もしかして、ルールを増やすこと自体が問題なのでは？」
気になってベンチマーク（品質テスト）を取ってみたら、予想以上にショッキングな結果が出ました。
| やり方 | 品質スコア |
|---|---|
| ルールなし（何も書かない） | 84点 |
| 全ルールを書く（約30ファイル分） | 79点（悪化！） |
| 3ファイルだけ + 動的チェック | 96.9点 |
ルールを全部書いた構成は、何も書かないよりスコアが低かった。
前回の記事で AI Dev OS の全体像と導入手順を紹介しました。今回は、この失敗から見つけた CLAUDE.md の正しい設計方法 を共有します。
結論: CLAUDE.md は「目次」にして、書いた後に自動チェックする
この記事で伝えたいことは、たった2つです。
1. CLAUDE.md にルールを全部書かない。「目次」（参照先だけ）にする。
2. AIがコードを書いた後に、ルール違反を自動チェックする仕組みを入れる。
この2つを組み合わせた設計を Two-Tier Context Strategy（2層コンテキスト戦略） と呼んでいます。先ほどのベンチマークで 96.9 / 100点を出した構成です。
なぜ「全部書く」が逆効果なのか、どう設計すればいいのかを順に説明します。
なぜ「全部書く」と品質が下がるのか
自分の経験を振り返ると、「ルールを追記する → 別の品質が下がる → また追記する」を繰り返していました。これには理由があります。
情報が多すぎるとAIは混乱する
人間でも、100ページのマニュアルを渡されて「全部守って」と言われたら困りますよね。AIも同じです。
CLAUDE.md に30ファイル分（約30,000トークン（AIが処理するテキストの単位））のルールを書くと、こうなります:
- AIが全ルールに等しく注意を払えない — 後半のルールほど無視されやすい
- ルール同士が暗黙に矛盾する — 「セキュリティ重視」と「シンプルに書け」が衝突すると、AIは中途半端なコードを生成する
- 注意力がバラける — セキュリティに注意を向ければ命名がおろそかに、命名を細かく指定すればエラー処理が雑に
つまり、ルールを追加するたびに、他のルールへの注意が薄まるのです。
ベンチマークの詳細データ（クリックで展開）
| CLAUDE.md の構成 | 動的チェック | スコア（100点満点） | トークン数 |
|---|---|---|---|
| ガイドラインなし（ベースライン） | なし | ~84 | — |
| 全ガイドライン 約30ファイル | なし | ~79（悪化） | ~30K |
| 厳選10ファイル | なし | ~85 | ~24K |
| ガイドラインなし + 動的チェック | あり | 87.4 | ~3K |
| 3ファイル + 動的チェック | あり | 96.9 | ~8K+3K |
測定条件: モデルは Claude Sonnet 4.6、条件あたり3回試行。タスクはタスク管理アプリ（認証・CRUD・カテゴリ・チーム・APIの5機能）の実装。9軸66チェック項目（セキュリティ20点・エラーハンドリング15点・バリデーション15点・命名10点・ディレクトリ構成10点・API設計10点・型安全性10点・パフォーマンス5点・アクセシビリティ5点）の100点満点で採点。詳細は ベンチマーク設計書 / Test 012 結果 を参照。
Two-Tier Context Strategy — 自分がたどり着いた解決策
やったことはシンプルです。CLAUDE.md を「目次」にして、ルール本体は別ファイルに分けました。
┌─────────────────────────────────────────┐
│ Tier 1: CLAUDE.md（目次） │
│ → 「どのファイルを見るか」だけ書く │
│ → ルールの本体は書かない │
│ → 3〜5ファイルの参照パスだけ │
├─────────────────────────────────────────┤
│ Tier 2: docs/guidelines/（ルール本体） │
│ → セキュリティ、命名規則、テスト等 │
│ → テーマ別にファイル分割 │
│ → AIが必要なときに必要なファイルだけ読む │
└─────────────────────────────────────────┘
本屋さんに例えると:
- Tier 1（CLAUDE.md） = 本屋のフロアマップ。「セキュリティは3F、命名規則は2F」と案内するだけ
- Tier 2（docs/guidelines/） = 各フロアに並んだ本。AIは必要なフロアにだけ行って、必要な本だけ読む
この分離のおかげで、CLAUDE.md は20行程度に収まりつつ、1000行を超えるルールセットを維持できます。
Tier 1: CLAUDE.md — 何を書いて、何を書かないか
書くべきこと
- 参照すべきファイルのパス（3〜5ファイル）
- ルールの優先順位（どれが一番大事か）
- 1行で済むプロジェクト固有のルール（「Drizzle ORM を使用」「日本語でコメント」等）
書いてはいけないこと
- セキュリティルールの詳細 →
security.mdに分離 - コーディング規約の全文 →
code.mdに分離 - API設計パターンの解説 →
api.mdに分離 - テスト戦略の詳細 →
testing.mdに分離
判断基準はシンプル: 3行以上の説明が必要なルールは CLAUDE.md に書かない。 別ファイルにして、参照パスだけ書きます。
迷ったときのフローチャート
そのルールは1行で書ける？
├─ YES → プロジェクト全体に影響する？
│ ├─ YES → CLAUDE.md に残す
│ │ （例: 「Drizzle ORM を使用」）
│ └─ NO → docs/ に分離
│
└─ NO（説明が3行以上必要）
└─ 必ず docs/ に分離する
CLAUDE.md に残してよい例:
| ルール | 理由 |
|---|---|
Drizzle ORM を使用する |
1行、プロジェクト全体に影響 |
日本語でコメントを書く |
1行、プロジェクト全体に影響 |
docs/ に分離すべき例:
| ルール | 理由 |
|---|---|
| CSRF対策の実装パターン | 説明に10行以上必要 |
| Zodスキーマの設計ルール | コード例が必要 |
| ディレクトリ命名規則の一覧 | テーブル形式の整理が必要 |
【具体例】NG な CLAUDE.md vs OK な CLAUDE.md
NG: 全部書き込み型（~200行）→ 品質スコア 79点
# プロジェクトガイドライン
## セキュリティ
- すべてのDBクエリでプレースホルダを使用すること
- ユーザー入力は必ずサニタイズすること
- APIルートではCSRFトークンを検証すること
- レート制限を全エンドポイントに設定すること
- 環境変数は.envに記載し、コードにハードコードしないこと
- ... (あと50行)
## バリデーション
- Zodをバリデーションの単一ソースとして使用すること
- ... (あと30行)
## 命名規則
- ... (あと20行)
## エラーハンドリング
- ... (あと40行)
問題点:
- 200行超え → AIが後半を無視しやすい
- ルール同士が暗黙に矛盾しやすい
- どこを直せばいいかわかりにくい
OK: 2層設計型（~20行）→ 品質スコア 96.9点
# プロジェクト名 - Claude Code ガイドライン
このプロジェクトでは AI DEV OS に従ってコードを書いてください。
競合がある場合、上位のセクションが優先されます。
## 開発ガイドライン
### 1. セキュリティ（最重要）
- docs/ai-dev-os/03_guidelines/common/security.md
### 2. バリデーション
- docs/ai-dev-os/03_guidelines/common/validation.md
### 3. プロジェクト構造
- docs/ai-dev-os/03_guidelines/frameworks/nextjs/project-structure.md
## 優先順位（CSS Specificity 方式）
1. [最高] frameworks/nextjs/* — フレームワーク固有
2. [高] common/* — 共通ルール
3. [中] project-specific/* — プロジェクト固有
50行のセキュリティルール → 1行の参照パスに。 でもAIは必要なときに security.md を読みに行くので、ルールの網羅性は維持されています。
- ## セキュリティ
- - すべてのDBクエリでプレースホルダを使用すること
- - ユーザー入力は必ずサニタイズすること
- - APIルートではCSRFトークンを検証すること
- - レート制限を全エンドポイントに設定すること
- ... (あと50行のセキュリティルール)
+ ## セキュリティ（最重要）
+ - docs/ai-dev-os/03_guidelines/common/security.md
Tier 2: docs/guidelines/ — ルール本体の置き場所
ルール本体は 前回記事で紹介した4層モデル に沿って整理されています。
docs/ai-dev-os/
├── 01_philosophy/ # L1: 設計哲学（2〜5年変わらない）
├── 02_decision-criteria/ # L2: 判断基準（1〜3年）
├── 03_guidelines/ # L3: 具体的なルール（6〜12ヶ月）
│ ├── common/ # 言語非依存のルール
│ └── frameworks/nextjs/ # Next.js 固有のルール
└── 04_ai-prompts/ # L4: ツール固有設定（2〜4ヶ月）
ポイント: 寿命が違うものは別ファイルにする。 設計哲学（数年変わらない）とツール設定（数ヶ月で変わる）を同じファイルに書くと、ツール設定の更新時に安定すべき部分を壊すリスクがあります。
「パスを書くだけで、AIは本当にファイルを読むの？」
これはよく聞かれる疑問です。答えはツールごとに異なります。
-
Claude Code: CLAUDE.md に書かれたファイルパスを認識し、タスクに関連するファイルを自動的に読みに行きます。「認証を実装して」と指示すると、
security.mdを優先的に参照します -
Cursor:
.cursor/rules/配下のファイルは起動時に自動読み込みされます - Kiro: Steering Rules（Kiroのルール設定機能）に登録されたファイルは自動的にコンテキストに含まれます
どのツールでも、AIが全ファイルを一度に読むのではなく、タスクに関連するファイルだけ選んで読むのがポイントです。
動的チェック — 「書いた後にレビューする」仕組み
2層設計（目次 + 別ファイル）だけでもスコアは上がりますが、最高スコア 96.9点を出した決め手は「動的チェック」 です。
動的チェックとは、AIがコードを生成した 後 に、ルール違反がないか自動で確認・修正する仕組みです。人間の開発でいう「コードレビュー」をAIが自動でやるイメージです。
① AIがコードを書く
↓
② /ai-dev-os-check を実行（自動レビュー）
→ ルール違反を検出してリストアップ
↓
③ AIが違反箇所を自動修正
↓
④ ルールに準拠したコードが完成
実際の /ai-dev-os-check の出力例:
## AI Dev OS Compliance Report
### Summary
- ✅ Passed: 58 / ⚠️ Review: 3 / ❌ Violation: 5
### Violations
| # | File | Rule | What was fixed |
|---|-------------------|--------------|-----------------------------|
| 1 | route.ts:42 | security.md | Added rate limiting |
| 2 | user-card.tsx:7 | naming.md | Renamed to kebab-case |
| 3 | action.ts:15 | validation.md| Added .refine() for dueDate |
なぜ動的チェックが効くのか？ 人間の開発でも、コーディング規約を配っただけでは品質は上がりません。コードレビューで指摘し、修正する——そのサイクルが品質を作ります。AI開発でも同じでした。
「少ないルール（CLAUDE.md）」×「書いた後のレビュー（動的チェック）」——この組み合わせがベンチマーク最高スコアの理由です。
ai-coding.md — AIがよくやるミスの一覧表
Two-Tier のもう一つの便利なファイルが ai-coding.md です。これは、AIが頻繁にやらかす「あるある」を一覧テーブルにまとめたものです。
# AI Coding — Common AI Pitfalls
| Category | Pitfall | Rule | Status |
|----------|---------|------|--------|
| Security | CSRF token not validated | MUST verify on all state-changing endpoints | [proven] |
| Validation | Client-only validation | MUST duplicate on server with same Zod schema | [proven] |
| Naming | Inconsistent handler naming | MUST use handle{Action} pattern | [proven] |
| Structure | Flat directory | MUST use features/ vertical slice | [proven] |
| Type Safety | Excessive `as` casts | SHOULD use Zod inference instead | [draft] |
ポイント:
- テーブル形式 → AIが瞬時にルールを把握できる
-
ステータス管理 →
[draft]（仮説）→[proven]（実証済み）→[deprecated]（廃止）でルールの成熟度を追跡
このファイルは、小規模プロジェクトなら CLAUDE.md に直接書いてもOK。チーム開発なら docs/guidelines/ に分離する——が目安です。
既存の CLAUDE.md を2層構造に移行する3ステップ
自分が200行のCLAUDE.mdを移行したときの手順をそのまま書きます。30分でできました。
ステップ1: 分類する（10分）
今のCLAUDE.mdの各ルールに、ラベルをつけます。
-
[S]セキュリティ系 -
[V]バリデーション系 -
[N]命名規則系 -
[E]エラーハンドリング系 -
[D]ディレクトリ構成系 -
[P]プロジェクト固有（1行で済むもの）
ステップ2: 分離する（15分）
ラベルごとに docs/guidelines/ にファイルを作成し、ルールを移動します。[P] だけ CLAUDE.md に残します。
mkdir -p docs/guidelines
# ラベルごとにファイルを作成（中身は CLAUDE.md からカット&ペースト）
ステップ3: CLAUDE.md を目次に書き換える（5分）
## 開発ガイドライン
- docs/guidelines/security.md
- docs/guidelines/validation.md
- docs/guidelines/project-structure.md
200行が10行以下になります。
AI Dev OS を使わなくても、この「CLAUDE.md を目次にする」パターンは単独で適用できます。自分のルールを分割するだけで効果があります。
Rule Harvesting（ルールの収穫） — 完璧なルールは最初から書けない
最初は「完璧なルールセットを作ろう」としていましたが、無理でした。実際にAIにコードを書かせて初めて「ああ、ここにもルールが必要だったのか」と気づくことばかりです。
ガイドラインは実装しながら発見していくものだ、というのが半年やって得た実感です。
① 実装する
↓
② AIが書いたコードで問題を発見
（例: エラーメッセージの形式が毎回違う）
↓
③ それを防ぐルールを1行で書く
（例: 「エラーコードは ERROR_XXXX_NNN 形式で統一」）
↓
④ docs/guidelines/ に追記する
↓
①に戻る
ルールは「書くもの」ではなく「収穫するもの」。 畑のイメージです。最初から完璧な種を蒔くのではなく、実装の中に自然と生えてくるパターンを見つけて摘み取ります。
AI Dev OS の Claude Code プラグインには /ai-dev-os-extract というスキルがあり、コードレビューのやり取りからルールを自動抽出できます。
3ツールへの適用
Two-Tier Context Strategy は Claude Code 専用ではありません。3ツールすべてに使えます。
| Tier 1（目次） | Tier 2（ルール本体） | |
|---|---|---|
| Claude Code |
CLAUDE.md にパスを記述 |
docs/guidelines/ を参照 |
| Cursor |
.cursor/rules/ に .mdc ルールを配置 |
同じ docs/guidelines/ を参照 |
| Kiro |
.kiro/steering/ に Steering Rules を配置 |
同じ docs/guidelines/ を参照 |
Tier 2（ルール本体）は全ツール共通。 ツールを乗り換えても、ルールの中身を書き直す必要がないのがこの設計の強みです。
正直、まだ解決できていないこと
この設計で多くの問題は解消しましたが、正直に限界も書いておきます。
- 「3ファイル」が万能な組み合わせではない: ベンチマークはタスク管理アプリでの測定結果です。データパイプラインや機械学習など、ドメインが違えば最適なファイル構成も変わります。自分のプロジェクトで試して調整する手間は省けません
-
動的チェックは万能ではない:
/ai-dev-os-checkはガイドラインに書かれたルールしかチェックできません。ガイドラインにない暗黙の品質基準（パフォーマンス要件、特定のビジネスロジック等）は検出対象外です - ベンチマーク自体の限界: 9軸66項目のチェックリストで採点していますが、「実際のプロダクト品質」とスコアがどこまで相関するかは、正直まだ検証途中です。スコアは参考値として見てください
- モデル依存の可能性: Claude Sonnet 4.6 での結果なので、他のモデル（GPT系、Gemini等）で同じ効果が出るかは未検証です。たぶん傾向は同じだと思いますが、断言はできません
半年後にはモデルも変わりますし、ツールも進化します。この記事の数字が古くなる日は来ると思います。でも「情報を詰め込みすぎると逆効果」「静的ルールだけでは不十分」という原則は、しばらく変わらないはずです。
まとめ
この記事のポイント
- CLAUDE.md にルールを全部書くのは逆効果。 情報過多でAIの注意力が分散し、品質が下がる
- CLAUDE.md は「目次」にする。 参照パス3〜5ファイルだけ書き、ルール本体は docs/ に分離
- 動的チェックを組み合わせる。 AIが書いたコードをルールに照らして自動レビュー → 自動修正
- この2つの合わせ技で 96.9/100 点を達成
やるべきこと vs やってはいけないこと
| やるべきこと | やってはいけないこと |
|---|---|
| CLAUDE.md を「目次」にする | CLAUDE.md に全ルールを書く（200行超え） |
| ルールを個別ファイルに分離 | ファイルを10個以上 CLAUDE.md に列挙 |
動的チェック（/ai-dev-os-check）で検証 |
静的なルール記述だけに頼る |
| 実装からルールを収穫する（Rule Harvesting） | 最初から完璧なルールを書こうとする |
ベンチマーク結論
| アプローチ | スコア | 判定 |
|---|---|---|
| ルールなし | 84点 | ベースライン |
| 全ルール記載 | 79点 | ルールなしより悪い |
| 2層設計 + 動的チェック | 96.9点 | 最適解 |
「Less is More」——少なく書いて、後からチェック。これが数値で実証された最適解です。
前回記事: AIが書くコード、毎回バラバラ問題を解決するOSSを作った【Claude Code / Cursor / Kiro 対応】 — 導入手順編
次回記事: チーム展開・運用編 — 「一人で使うと便利だけどチームに広がらない」問題を解決する話
皆さんの CLAUDE.md は何行ですか？ 自分は200行から20行に減らして劇的に改善しました。「うちはこうしてる」「こういう問題がある」など、ぜひコメントで教えてください。
GitHub リポジトリ: AI Dev OS（MIT License）
関連記事