コンテキスト窓の限界とCLAUDE.mdモジュール化：460行の指示書を分割した理由

概要

CLAUDE.mdは20行から始まった。プロジェクトが成長するにつれ、ビルド手順、アーキテクチャ、DBスキーマ、認証情報、運用手順、インシデント防止策——全てがCLAUDE.mdに追加されていった。気がつけば460行を超え、さらに7つのモジュールファイルに分割する必要が出てきた。

本記事では、CLAUDE.mdをモジュール化した設計判断と、「いつ参照するか」テーブルによるAIのファイル選択最適化について記録する。

問題：肥大化するCLAUDE.md

成長の経緯

1
Phase 1（開始直後）:    20行  — ビルドコマンドとディレクトリ構造だけ
2
Phase 2（3ヶ月後）:    100行  — テスト方法、lint設定を追加
3
Phase 3（6ヶ月後）:    200行  — DB操作ルール、エラーハンドリング規約を追加
4
Phase 4（9ヶ月後）:    350行  — API認証、launchd運用手順を追加
5
Phase 5（12ヶ月後）:   460行  — インシデント防止策、施策管理を追加
6
Phase 6（現在）:       460行 + 7モジュール

なぜ1ファイルでは限界か

CLAUDE.mdが長くなると、以下の問題が発生する。

1. コンテキスト窓の消費

AIのコンテキスト窓（入力トークン数の上限）は有限だ。460行のCLAUDE.mdを毎回全量読み込むと、実際のコード修正に使えるコンテキストが減る。特に大きなファイルの修正時に「ファイルの後半を読めない」事態が起きた。

2. 情報の希釈

DB操作をする時にlaunchdの運用手順は不要だ。API統合をする時にGitワークフローのルールは関係ない。全情報が1ファイルにあると、今のタスクに関係ない情報がノイズになる。

3. 「ファイルの末尾が読まれない」問題

実際に観測した事象として、非常に長いCLAUDE.mdの末尾に書いたルールがAIに無視されるケースがあった。冒頭に書いたルールは守られるが、400行目以降のルールの遵守率が下がる傾向があった。

解決策：モジュール化

ファイル構成

1
project/
2
  CLAUDE.md                      # 460行：目次 + Quick Start + 必須ルール
3
  CLAUDE_02_ENTRYPOINTS.md       # 14プログラムの実行方法
4
  CLAUDE_03_ARCHITECTURE.md      # アーキテクチャパターン
5
  CLAUDE_05_DATABASE.md          # PostgreSQL + TimescaleDB スキーマ
6
  CLAUDE_06_SECURITY.md          # 認証情報、6つの外部サービス
7
  CLAUDE_07_OPERATIONS.md        # launchd、Gitワークフロー、エラーハンドリング
8
  CLAUDE_08_PROGRESS.md          # アクティブな施策の進捗状態
9
  CLAUDE_10_INCIDENT_PREVENTION.md  # インシデント防止（392件の知見）

各ファイルの責務

1
# ファイル構成をコードで表現すると
2
CLAUDE_MODULES = {
3
    "CLAUDE.md": {
4
        "lines": 460,
5
        "role": "目次 + Quick Start + Architecture Overview + Critical Rules",
6
        "always_loaded": True,
7
    },
8
    "CLAUDE_02_ENTRYPOINTS.md": {
9
        "lines": 180,
10
        "role": "14プログラムの実行コマンドと引数",
11
        "load_when": "実行コマンドを確認する時",
12
    },
13
    "CLAUDE_03_ARCHITECTURE.md": {
14
        "lines": 220,
15
        "role": "3エンジンのアーキテクチャ、データフロー",
28 collapsed lines
16
        "load_when": "コードを修正する時",
17
    },
18
    "CLAUDE_05_DATABASE.md": {
19
        "lines": 150,
20
        "role": "テーブル定義、インデックス、クエリパターン",
21
        "load_when": "DB操作をする時",
22
    },
23
    "CLAUDE_06_SECURITY.md": {
24
        "lines": 130,
25
        "role": "API認証方式、環境変数、エラーコード表",
26
        "load_when": "API/認証エラーが発生した時",
27
    },
28
    "CLAUDE_07_OPERATIONS.md": {
29
        "lines": 200,
30
        "role": "launchdジョブ管理、Gitワークフロー",
31
        "load_when": "運用トラブルが発生した時",
32
    },
33
    "CLAUDE_08_PROGRESS.md": {
34
        "lines": 100,
35
        "role": "施策の進捗状態、WBSリンク",
36
        "load_when": "施策の状態を確認する時",
37
    },
38
    "CLAUDE_10_INCIDENT_PREVENTION.md": {
39
        "lines": 350,
40
        "role": "392件のインシデントから抽出した防止策",
41
        "load_when": "重大判断前、デプロイ前",
42
    },
43
}

「いつ参照するか」テーブル

モジュール化で最も重要なのは、CLAUDE.md本体に「いつ、どのファイルを参照すべきか」を明示することだ。

1
| File | Contents | いつ参照するか |
2
|------|----------|--------------|
3
| CLAUDE_02 | 14プログラム実行方法 | 実行コマンド確認時 |
4
| CLAUDE_03 | アーキテクチャ | コード修正時 |
5
| CLAUDE_05 | DB スキーマ | DB操作時 |
6
| CLAUDE_06 | 認証情報 | API/認証エラー時 |
7
| CLAUDE_07 | 運用手順 | 運用トラブル時 |
8
| CLAUDE_08 | 施策進捗 | 施策状態確認時 |
9
| CLAUDE_10 | インシデント防止 | 重大判断前・デプロイ前 |

なぜこのテーブルが効くのか

AIは「全ファイルを毎回読む」のではなく、「今のタスクに関連するファイルだけを読む」ことで、コンテキスト窓を効率的に使える。

1
例1: 「DBのテーブルにカラムを追加して」
2
  → AIは CLAUDE_05_DATABASE.md を参照
3
  → DB操作のルール、スキーマ定義、インデックス戦略がわかる
4

5
例2: 「デプロイの手順を教えて」
6
  → AIは CLAUDE_07_OPERATIONS.md を参照
7
  → launchdのジョブ管理、plistの配置方法がわかる
8

9
例3: 「この変更をデプロイしても大丈夫？」
10
  → AIは CLAUDE_10_INCIDENT_PREVENTION.md を参照
11
  → 392件のインシデントから類似ケースを確認

設計判断：なぜ「巨大1ファイル」でも「細かすぎる分割」でもダメか

巨大1ファイルの問題

1
CLAUDE.md（1,500行の場合）
2
├── Quick Start          ... 1-50行     ← AIは確実に読む
3
├── Build & Test         ... 51-100行    ← AIは読む
4
├── Architecture         ... 101-300行   ← AIはたぶん読む
5
├── Database             ... 301-450行   ← AIは読むかもしれない
6
├── API Authentication   ... 451-580行   ← AIは読まないかもしれない
7
├── Operations           ... 581-780行   ← AIはたぶん読まない
8
└── Incident Prevention  ... 781-1500行  ← AIは読まない可能性が高い

1,500行のファイルの末尾にある情報は、AIの注意を引きにくい。特にコンテキスト窓が逼迫している状況では、ファイルの後半が切り捨てられるリスクがある。

細かすぎる分割の問題

1
# 30ファイルに分割した場合
2
CLAUDE_01_QUICK_START.md
3
CLAUDE_02_BUILD.md
4
CLAUDE_03_TEST.md
5
CLAUDE_04_LINT.md
6
CLAUDE_05_ARCHITECTURE_ENGINE_A.md
7
CLAUDE_06_ARCHITECTURE_ENGINE_B.md
8
CLAUDE_07_ARCHITECTURE_ENGINE_C.md
9
... （30ファイル続く）

分割しすぎると、AIは「どのファイルを読むべきか」の判断に時間がかかる。30ファイルの中から適切なものを選ぶコストが、情報アクセスのメリットを上回る。

最適解：7モジュール + 目次テーブル

1
CLAUDE.md（460行）← 常に読まれる。目次 + 最重要ルール
2
  + 7モジュール   ← 必要な時だけ読まれる

460行は「AIが確実に全量読める長さ」だ。7モジュールは「AIが選択判断できる数」だ。この組み合わせが実運用で最も効果的だった。

CLAUDE.md本体に残すべき情報

モジュール化しても、CLAUDE.md本体には460行分の情報が残っている。削れない情報とは何か。

必ず本体に残す情報

1
1. Quick Start（ビルド・テスト・lint コマンド）
2
   → 全タスクで必要
3

4
2. ディレクトリ構造の概要
5
   → ファイルの配置を理解するために必須
6

7
3. Critical Rules（絶対に破ってはいけないルール）
8
   → モジュールに移動すると見落とされるリスク
9
   例: "本番DBに直接INSERTしない"
10
       "launchdジョブの.plistを直接編集しない"
11

12
4. 「いつ参照するか」テーブル
13
   → モジュール選択の判断材料
14

15
5. Architecture Overview（概要レベル）
1 collapsed line
16
   → 詳細はCLAUDE_03に委譲するが、概要は本体に必要

モジュールに移動した情報

1
移動した情報:
2
  - 14プログラムの実行コマンド詳細 → CLAUDE_02
3
  - データフロー図、シーケンス図 → CLAUDE_03
4
  - テーブル定義（CREATE TABLE文） → CLAUDE_05
5
  - API認証の実装詳細 → CLAUDE_06
6
  - launchdジョブ一覧（90ジョブ分） → CLAUDE_07
7
  - インシデント一覧と対策 → CLAUDE_10

進化の記録：20行から460行+7モジュールへ

Phase 1: 20行（開始直後）

1
## Build
2
python -m pytest tests/
3

4
## Structure
5
engine_a/ - データ処理エンジンA
6
engine_b/ - データ処理エンジンB

Phase 3: 200行（6ヶ月後）

1
## Quick Start
2
（ビルド・テスト・lint手順）
3

4
## Architecture
5
（3エンジンの概要）
6

7
## Database
8
（テーブル定義）
9

10
## Error Handling Rules
11
（エラーハンドリング規約）
12

13
## Common Module Usage
1 collapsed line
14
（共通モジュールの利用ルール）

Phase 6: 460行+7モジュール（現在）

1
## Quick Start
2
（ビルド・テスト・lint手順）
3

4
## Module Reference Table
5
| File | Contents | いつ参照するか |
6
（7モジュールへのガイド）
7

8
## Architecture Overview
9
（概要のみ。詳細はCLAUDE_03）
10

11
## Critical Rules
12
（絶対に破ってはいけないルール群）
13

2 collapsed lines
14
## Active Projects
15
（進行中の施策サマリー。詳細はCLAUDE_08）

各フェーズで追加した情報が「本体に残すべきか、モジュールに移動すべきか」を判断する基準は、「全タスクで必要か、特定タスクでのみ必要か」だ。

実際の効果

Before（1ファイル460行）

DBスキーマの情報が400行目付近にあり、AIが参照しないことがあった
インシデント防止策が末尾にあり、デプロイ前チェックが漏れることがあった
コンテキスト窓の消費が大きく、大きなファイルの修正時に支障が出た

After（460行 + 7モジュール）

「いつ参照するか」テーブルにより、AIが適切なモジュールを自発的に読む
Critical Rulesは本体の冒頭付近に配置し、常に参照される
必要なモジュールだけ読み込むため、コンテキスト窓の効率が向上

1
# 効果の定量化（概算）
2
context_usage = {
3
    "before": {
4
        "claude_md": 460,  # 行
5
        "always_loaded": 460,
6
        "utilization": "30%",  # 多くの情報がタスクと無関係
7
    },
8
    "after": {
9
        "claude_md": 460,
10
        "average_modules_loaded": 1.5,  # タスクあたり平均1.5モジュール
11
        "average_additional_lines": 250,
12
        "utilization": "70%",  # 関連情報の比率が向上
13
    },
14
}

学んだこと

1. CLAUDE.mdは「目次」の役割を果たす

CLAUDE.md本体は、AIが「何がどこにあるか」を理解するための目次だ。詳細情報は各モジュールに委譲する。目次がなければ、AIは7つのモジュールファイルの存在すら知らない。

2. 「いつ参照するか」列がAIのファイル選択を助ける

ファイル名だけでは不十分だ。「CLAUDE_05_DATABASE.md」と書いても、AIがDB操作時に自発的に参照するとは限らない。「DB操作時に参照」と明記することで、AIのファイル選択精度が上がった。

3. モジュール化してもCLAUDE.md自体は460行ある

「モジュール化したら本体は100行くらいになるだろう」と期待していたが、実際にはCritical Rules、Quick Start、Architecture Overview、Module Reference Tableだけで460行になった。削れない情報が多いというのが現実だ。

まとめ

CLAUDE.mdモジュール化で重要なのは以下の3点だ。

「いつ参照するか」テーブルの設置: モジュールファイルの存在を知らせるだけでなく、「どのタスクの時に読むべきか」を明記する
7モジュールが最適な粒度: 巨大1ファイルでも細かすぎる30ファイルでもなく、AIが選択判断できる7ファイルに分割
Critical Rulesは本体に残す: モジュールに移動すると見落とされるリスクがある重要ルールは、常に読まれるCLAUDE.md本体の冒頭付近に配置