CLAUDE.md に細かいコーディングルールを全部書くのはアンチパターン

投稿日 2026/05/19

投稿者 rengotaku

7 分で読めます

CLAUDE.md に細かいコーディングルールを全部書くのはアンチパターン

まとめ

CLAUDE.md はセッション中毎ターンプロンプト先頭に積まれるので、細かい規約を全部書くとトークンを毎回払う
トークン以上に深刻なのはアテンションが薄まること。長くなるほど一行一行の効きが弱くなり、肝心の禁止事項が守られなくなる
長セッションでは CLAUDE.md もコンパクションで要約に巻き込まれて潰れる。細かいルールほど消えやすい
推奨は薄いルーター + Skill / scene-rules 。CLAUDE.md には絶対ルール 3-5 行と Skill 参照だけ書き、詳細は対象ファイルを触る時にロードされる仕組みに寄せる

背景

「コーディングルールを rules/ フォルダに置こうぜ」という議論があった。ここで「rules/ に置く＝ CLAUDE.md に書くのと同じ（読み込まれる）」という前提が共有された上で、

詳細なプロジェクト固有のコーディング規約を CLAUDE.md に書くのはアリか？

を考えた結果のメモ。結論から言うと NG 。理由を 3 つ。

1. 毎ターン全文を払う

CLAUDE.md は会話中の毎メッセージで Claude のプロンプト先頭に積まれる。コントローラのルール 200 行 + モデルのルール 150 行 + テストのルール 100 行 + … を全部書くと、 RSpec ファイルを編集する時にもコントローラのルール分のトークンが課金される。元々 2,000 トークン程度だった CLAUDE.md が一気に 4-5 倍に膨れ、全セッションでコストが乗る。

ローカル開発で 1 人が触る分には気にならないが、CI で AI レビュー / 自動修正を回したり、Sub Agent をたくさん起動する運用だと乗算で効いてくる。

2. アテンションが薄まる（これが本質）

トークン課金より遥かに深刻なのがこれ。 CLAUDE.md が長くなるほど一行の効きが弱くなる。経験的に “Don’t” 系のルールは 50 行を超えたあたりから守られなくなる肌感がある。重要度のシグナルが希釈されるためだ。

「全部書いてあるのに守ってくれない」状態になるくらいなら、編集対象に応じて 2-3 ファイルだけロードされる方が遥かに効く。「ガイドラインが分厚すぎて誰も読まないドキュメント」と同じ落とし穴。

3. コンパクション耐性が無い

長セッションでは Claude Code の自動圧縮（コンパクション）が走り、過去のメッセージが要約に置き換わる。この時 CLAUDE.md 由来の細かいルールも要約で潰れる。

「コントローラの XXX なメソッドにはバリデーションをかけ、エラーはこういう形式で返し、ログは…」みたいな細かい指示は、要約で消える代表格。書いた意味が無くなる。

Skill や scene-rules 経由でロードする場合は、呼ばれた時に fresh に読み直されるので、コンパクションで潰れる問題が起きにくい。

ではどうするか

CLAUDE.md を薄いルーターに保つのが筋。

# CLAUDE.md

## 絶対ルール（3-5 行だけ）
- Sub Agent / Skill の使用を徹底
- テストが pass しない実装は完了とみなさない

## 編集時のルール参照
- Controller / Routes を触る → `/rules-backend-controller`
- Model を触る → `/rules-backend-model`
- RSpec を書く → `/rules-test-rspec`

詳細ルール本体は次のどちらかに置く:

a. Skill 化する

/rules-backend-controller のような Skill を作り、CLAUDE.md からは「触る時に呼べ」と指示するだけ。

Skill 呼び出し時にしかロードされないのでトークン節約
ロード時はそのトピックだけにフォーカスされるのでアテンションが集中
更新は Skill ファイルだけ直せばよく、CLAUDE.md 本体は触らない

b. scene-rules 系の仕組みに乗せる

各ルールファイルに frontmatter で対象ファイルパターンを宣言:

---
paths:
  - "app/controllers/**/*.rb"
  - "config/routes.rb"
---

別途 index.yaml 的なインデックスに applies_to: で同じ glob を持たせ、編集中ファイルとマッチしたものだけをロードする。常時適用は always_apply: [common] のように共通ルールだけに限定する。

これは Codex / Cursor 系のエコシステムで先行している規約だが、Claude Code でも同等の Skill を作れば再現できる。

一行サマリ

CLAUDE.md は路線図であって時刻表ではない。詳細は Skill / scene-rules に置こう。

claude-code ai management