はじめに
Claude Codeを本格運用していると、CLAUDE.mdにルールを書き足したくなる。最初は数行だったファイルが、気づけば500行、800行、そして1,000行を超えた。
そのとき何が起きたか。AIが指示と逆の動作を始めた。
これは僕が実際に経験した話だ。当社ではClaude Codeで10部門を統括するAI経営フレームワークを運用しており、自動化率98%、launchdジョブ17個、SNS自動配信27件/日という規模で回している。その過程で「CLAUDE.md肥大化問題」にぶち当たり、解決策を見つけるまでに数週間を費やした。
この記事では、CLAUDE.mdが壊れるメカニズムと、僕が実際に採用した分離設計パターンを共有する。
CLAUDE.mdが壊れるメカニズム
1. ルールの矛盾が発生する
1,000行もルールを書くと、人間ですら矛盾に気づけない。AIならなおさらだ。
たとえば僕のケースでは、こんな矛盾が生まれていた。
# 200行目あたり
「対外アクションは必ずdraftモードで生成し、承認後に実行する」
# 700行目あたり
「SNS投稿は自動で配信する」
人間が読めば「SNSはdraft不要にしたいんだな」と推測できるが、AIは文字通りに解釈する。結果、SNS投稿がdraftで止まったり、逆に承認不要で全部送信されたり、挙動が安定しなくなった。
2. 優先度がわからなくなる
CLAUDE.mdは上から下に書かれたフラットな文書だ。AIにとっては「最初に書かれたルール」も「最後に追加したルール」も同じ重みを持つ。
ところが人間の意図としては、後から追加したルールのほうが重要なことが多い。この「暗黙の優先度」をAIは読み取れない。
3. コンテキストウィンドウを圧迫する
CLAUDE.mdは会話の冒頭で毎回読み込まれる。1,000行のルールファイルがあると、それだけで貴重なコンテキストウィンドウを消費する。実際の作業に使える領域が減り、長い会話になるとAIが前半のルールを「忘れる」現象が起きた。
実際に起きた事故
僕の環境で起きた具体的な問題をいくつか紹介する。
事故1: 指示と逆の動作
CLAUDE.mdに「git push --forceは絶対禁止」と書いていたのに、別の箇所で「デプロイは迅速に行う」と書いていた。AIは「迅速なデプロイ」を優先し、force pushを実行。ブランチが消えた。
事故2: ルール追加のたびに別のルールが壊れる
新しいプロダクトを追加するたびにCLAUDE.mdにルールを追記していた。10事業を同時運用していた時期は、ルール追加→既存ルールとの矛盾→予期しない動作、というサイクルが週1で発生していた。
事故3: AIが「どのルールに従えばいいかわからない」状態に
矛盾するルールが増えすぎた結果、AIが同じ質問に対して毎回違う回答を返すようになった。ルールが多すぎて、もはやルールとして機能していなかった。
解決策: 分離設計パターン
試行錯誤の末、僕がたどり着いた設計はこうだ。
原則: CLAUDE.mdは200行以内。詳細はエージェントファイルに分離する
CLAUDE.md（200行以内）
├── 役割の定義（10行）
├── 基本原則（20行）
├── コマンド一覧（50行）
├── 権限ルール（20行）
├── エラー時の振る舞い（10行）
└── 参照先ポインタ（20行）
.claude/agents/（詳細ルール）
├── ai-ceo-publisher.md — 出版部門の詳細ルール
├── ai-ceo-cto.md — 開発部門の詳細ルール
├── ai-ceo-cmo.md — マーケ部門の詳細ルール
├── ai-ceo-cfo.md — 経理部門の詳細ルール
└── ...
なぜこの設計が効くのか
1. コンテキストの分離
CLAUDE.mdは「全体のルール」だけを持つ。出版の詳細ルールは、出版タスクを実行するときだけ読み込まれる。マーケの詳細ルールは、マーケタスクのときだけ。これにより、無関係なルールがコンテキストを汚染しない。
2. 矛盾の局所化
仮に出版部門のルールに矛盾があっても、マーケ部門には影響しない。矛盾の影響範囲がファイル単位に限定される。
3. メンテナンス性
「SNS投稿のルールを変えたい」→ ai-ceo-cmo.md だけ編集すればいい。CLAUDE.mdを触る必要がない。
実装のポイント
CLAUDE.mdに書くべきもの:
## あなたの役割
あなたはCEOと直接対話するインターフェースです。
## 基本原則
- 対外アクションはdraft→承認→実行のパイプライン
- 絶対禁止: git push --force, 本番DB直接操作
## 参照先
- 出版部門の詳細: .claude/agents/ai-ceo-publisher.md
- 開発部門の詳細: .claude/agents/ai-ceo-cto.md
エージェントファイルに書くべきもの:
# 出版部門エージェント
## 実行フロー
1. 市場調査 → 章構成 → 執筆 → 品質チェック → 公開
## 品質基準
- 各章は3,000〜5,000文字
- コード例は必ず動作確認済みのものを使用
## このエージェント固有のルール
- Zenn投稿は1日1件まで
- 書籍CTAを全記事に含める
steering/ディレクトリの活用
ルールの中でも「ブランドガイドライン」「技術スタック」「権限設定」のように、複数部門が参照する共通ルールは、steering/ディレクトリに切り出す。
.company/steering/
├── brand.md — トーン、表記ルール
├── tech-stack.md — 使用技術の制約
├── permissions.md — 権限・閾値設定
└── policies.md — 全社共通ポリシー
これにより、CLAUDE.md → エージェントファイル → steeringファイルという3層構造ができる。各層の責務が明確で、変更の影響範囲が制御できる。
分離前後の比較
| 分離前 | 分離後 | |
|---|---|---|
| CLAUDE.mdの行数 | 1,000行超 | 約200行 |
| ルール矛盾の頻度 | 週1回 | ほぼゼロ |
| AIの挙動安定性 | 不安定（同じ質問に違う回答） | 安定 |
| ルール変更の影響範囲 | 全体 | 該当ファイルのみ |
| 新部門追加の手順 | CLAUDE.mdに追記（リスク大） | 新エージェントファイル作成 |
よくある失敗パターンと対策
パターン1: 「念のため」ルールの蓄積
# こういうルールが増えていく
- ファイル名にスペースを入れないこと
- コメントは日本語で書くこと
- インデントはスペース2つ
- 変数名はcamelCase
- ...
これらはCLAUDE.mdに書くべきではない。.editorconfigやeslintで制御すべきことをAIのルールファイルに書いている。ツールで制御できることはツールに任せる。
パターン2: 過去の事故の「再発防止策」を全部書く
事故が起きるたびにルールを追加すると、CLAUDE.mdが「過去の事故アーカイブ」になる。
対策: 再発防止策は仕組みで解決する。「git push --forceをしない」ではなく、pre-pushフックでforce pushをブロックする。ルールではなくコードで防ぐ。
パターン3: 具体的すぎるルール
# 悪い例
- 田中さんへのメールは「お世話になっております」で始める
- 請求書の振込先はXX銀行YY支店
# 良い例
- メールテンプレートは .company/templates/email/ を参照
- 請求書設定は .company/steering/billing.md を参照
具体的な情報はCLAUDE.mdに書かず、専用ファイルに外出しする。
まとめ
CLAUDE.mdの肥大化は、Claude Codeを本格運用していれば誰もが通る道だと思う。僕の場合は1,000行を超えたあたりでAIが壊れ、分離設計に移行するまで数週間のロスが発生した。
ポイントを3つにまとめる。
- CLAUDE.mdは200行以内に抑える — 役割定義、基本原則、コマンド一覧、参照先ポインタだけ
- 詳細ルールはエージェントファイルに分離 — 必要なときだけ読み込まれる
- ツールで制御できることはルールに書かない — eslint、フック、CI/CDに任せる
「AIは実行に使う。判断は人間。」これは僕がAI経営を1年やってきて得た結論だ。ルールファイルも同じで、AIに「正しく判断させる」のではなく、「判断しなくて済む仕組み」を作るほうがうまくいく。
📚 もっと詳しく知りたい方へ
Claude CodeによるAI経営の実践ノウハウを書籍にまとめています。CLAUDE.mdの設計パターン、エージェント分離、自動化の具体的な実装まで、すべて実体験ベースで解説しています。