Claude Code を使い込んでいくと、CLAUDE.md にルールがどんどん増えていきます。
「日本語で出力して」「rm は使わないで」「テストは必ず実行して」「シンプルな実装を優先して」…。
気付くとルールが数十個になり、「あれ、このルール守られてなくない？」 という場面が増えてきます。
本記事では、肥大化した CLAUDE.md を 優先度ラベル付きの階層構造 に整理したら、ルールの効きが安定した話を紹介します。
今後みなさんが CLAUDE.md を育てるときの参考にしていただけたら幸いです。
今回題材にしたい状況
私の CLAUDE.md も、使い始めの頃はシンプルな箇条書きでした。
# CLAUDE.md
- 日本語で出力すること
- rm コマンドは使わないこと
- シンプルな実装を優先すること
- テスト実行を忘れないこと
- ...
ところが運用していくうちに、ルールは増える一方です。
そして増えるにつれて、「書いてあるのに守られない」ルールが出てきました…。
この記事で伝えたいこと
CLAUDE.md のルールには、「絶対に守るべきもの」と「状況次第のもの」が混在 しています。
これをフラットな箇条書きのまま増やすと、Claude くんはどれを優先すべきか判断できません…。
そこで、P0〜P4 の優先度ラベル を付けて階層化し、詳細は別ファイルに分割して参照 する構成にしました。
これだけで、ルール同士が衝突したときの挙動が安定し、重要なルールの取りこぼしが減ります。
3つの問題
フラットな箇条書きで運用していて、3 つの問題にぶつかりました。
問題① ルール同士が衝突したとき、どちらが勝つか分からない
たとえば、こんな 2 つのルールがあったとします。
- 「ユーザーの指示には必ず従うこと」
- 「rm コマンドは絶対に使わないこと」
ユーザーが「この一時ファイル、rm で消しといて」と言ったらどうなるでしょうか。
フラットな箇条書きでは、AI がどちらを優先すべきか判断する材料がありません。
セッションによって挙動が変わる、という不安定さの原因になっていました。
問題② すべてのルールを同じ熱量で書くと、重要なものが埋もれる
ルールが 50 個並んでいると、「絶対に守ってほしい安全規則」と「できれば従ってほしいコーディング好み」が同じ見た目になります。
人間のドキュメントと同じで、全部を強調すると、何も強調していないのと同じ です…。
Claude くんにとっても「すべて大事」は「優先順位が分からない」と同義です。
問題③ 詳細をすべて CLAUDE.md に書くと、コンテキストを圧迫する
ルールの背景や具体例まで全部 CLAUDE.md に書くと、ファイルが数千行になります。
これは毎セッション読み込まれるコンテキストをルールだけで消費するということです。
本来の作業に使えるコンテキストが減り、長いセッションではルール自体が忘れられやすくなるという本末転倒が起きます。
どうしたか？ 優先度ラベル + 分割参照の構成へ
P0〜P4 の優先度ラベルを付ける
ルールを 5 段階の優先度に分類し、ラベルと適用条件を見出しに明記 しました。
# CLAUDE.md
## Priority Rules (FOLLOW IN ORDER)
### [P0] CRITICAL - 安全規則と基本動作
**ALWAYS ACTIVE** - すべてのメッセージで適用、他のルールに優先する
1. 破壊的操作の安全確認（rm 禁止 → ~/.Trash/ へ移動）
2. ユーザー指示は最優先（ただし安全規則の範囲内で）
...
### [P1] REQUIRED - 言語設定
**ALWAYS ENFORCE** - 出力は常に日本語
### [P2] DEFAULT - 開発アプローチ
**ALWAYS APPLY** - オッカムの剃刀、可読性の数値基準
### [P3] CONTEXTUAL - 状況依存の参照
**APPLY AS NEEDED** - タスク種別に応じて該当ファイルを参照
### [P4] OPTIONAL - 補助的な好み
ポイントは 3 つです。
-
FOLLOW IN ORDERを宣言し、衝突したら番号が小さい方が勝つ、と明文化 - 適用条件をラベルで書くて、
ALWAYS ACTIVE/APPLY AS NEEDEDを見出し直下に明記 - 「ユーザー指示が最優先。ただし P0 の安全規則は維持する」のように、例外の優先関係そのものをルール化する
これで、冒頭の「rm で消して」問題は 「P0 の安全規則が優先されるので、~/.Trash/ への移動で代替する」 という安定した挙動になります。
詳細は別ファイルに分割して、参照だけ置く
ルールの背景・具体例・コード例は、~/.claude/rules/ 配下の個別ファイルに移しました。
CLAUDE.md 本体には 要約と参照リンクだけ を置きます。
#### Occam's Razor - 最もシンプルな解を選ぶ
- 依存は 0〜2 個を優先（3 個以上は要正当化）
- 関数は 50 行以内、条件分岐は 5 個以内
- 「念のため」の実装はしない
詳細: [@~/.claude/rules/reference/OCCAMS_RAZOR.md](./rules/reference/OCCAMS_RAZOR.md)
~/.claude/
├── CLAUDE.md ← 要約 + 優先度 + 参照リンク
└── rules/
├── core/ ← P0 級の動作原則
├── reference/ ← 設計原則（SOLID、DRY など）
└── development/ ← 実践プラクティス（TDD、可読性など）
ポイントは、CLAUDE.md 側にも 判断に必要な最小限の数値基準は残す ことです。
「詳細はファイル参照」だけにすると、参照されなかったときに何も効かなくなります。要約だけで 8 割動ける状態にして、残り 2 割を詳細ファイルに任せます。
ルールは「数値」で書く
分類と並んで効いたのが、ルールを数値で書く ことです。
❌ 関数は短く書くこと
✅ 関数は 5〜15 行（理想は 5〜10 行）。超えたら分割を検討
❌ テストが通ることを確認すること
✅ テストコマンドの exit code が 0 であることを確認。
lint はエラー 0 件（警告は 5 件未満なら許容）
「短く」「ちゃんと」のような形容詞は、AI にとって解釈の余地が大きすぎる言葉です。
数値にすると判定が機械的になり、ルールが守られたかどうかを AI 自身が検証できるようになります。
まとめ
フラットな箇条書きと優先度ラベル構成で、運用がどう変わったかを並べてみます。
| 観点 | Before（フラットな箇条書き） | After（優先度ラベル + 分割参照） |
|---|---|---|
| ルールの衝突 | セッションごとに挙動がブレる | P0 > P1 > … の順で安定して解決 |
| 重要ルールの埋没 | 安全規則も好みも同じ見た目 | CRITICAL / OPTIONAL が一目で分かる |
| コンテキスト消費 | 詳細まで全部読み込む | 要約のみ常駐、詳細は必要時に参照 |
| ルールの検証 | 「ちゃんとやった」で終わる | 数値基準で AI 自身が判定できる |
CLAUDE.md は「書けば書くほど良くなる」ものではなく、構造がないまま増やすと、むしろ効きが悪くなる ドキュメントでした。
これは人間のチームのルールブックと同じです。
新人に 50 個のルールを渡すなら、「絶対守るもの」「慣れたら意識するもの」を分けて渡すはず。AI に対しても同じ配慮が必要だった、というのが運用してみての実感です。
本記事の要点は下記のとおりです。
- CLAUDE.md のルールは増えるほど 衝突と埋没 が起きる
-
P0〜P4 の優先度ラベル と
FOLLOW IN ORDERの宣言で、衝突時の挙動を安定させる - 適用条件（
ALWAYS ACTIVE/APPLY AS NEEDED）を見出しに明記する - 詳細は別ファイルに分割し、CLAUDE.md には 要約 + 数値基準 + 参照リンク だけ残す
- ルールは形容詞ではなく 数値 で書くと、AI 自身が守れたか検証できる
CLAUDE.md は一度書いて終わりではなく、運用しながら構造を育てるドキュメント です。
ルールが増えて効きが悪くなってきたなと感じたら、まず優先度ラベルでの整理から試してみてください！