📝

CLAUDE.mdは50行で十分だった——200行超えたら指示の30%が消える話

に公開
AI
初心者
開発環境
Claude Code
tech

長いほうが丁寧だと思ってた

CLAUDE.mdに全部書いた方がいい。

直感的にはそう思う。プロジェクトの構成、コーディングルール、テストの方針、禁止事項……Claudeに伝えたいことは山ほどある。全部書けばClaudeは全部理解してくれる。そう信じてた。

違った。

200行を超えると、指示の30%がtruncation（切り詰め）される。 300行超はむしろ逆効果。Claudeが指示を見落とす頻度が上がる。

書けば書くほど丁寧。そう思ってたのが恥ずかしい。

数字で見る「短い方が強い」

指標 未最適化 最適化後 改善
トークン消費 4,500 1,800 -60%
セッション修正回数 5回 3回 -40%
レスポンス時間 45秒 30秒 -33%
生成エラー 60%が曖昧指示に起因 35%低減 —

短くした方がトークン節約になるだけじゃなく、修正回数もレスポンス時間も減る。情報が少ない方がClaudeは的確に動く。人間だってマニュアル300ページ渡されたら読まないでしょ。同じ。

最適な長さ

行数 評価
50行以下 理想。全指示が有効
50-150行 許容。modular rulesで補完推奨
150-200行 注意。truncation開始域
200行超 30%の指示が喪失
300行超 逆効果

HumanLayerの推奨は60行以下。もっと攻めてる。

「でも伝えたいことがいっぱいあるんだけど」。わかる。自分もそうだった。

答えは2つある。

解決策1: WHY/WHAT/HOW構造

日本語Xコミュニティで広まっている書き方。CLAUDE.mdの構造をこの3つに絞る。

# IMPORTANT: プロジェクトルール（MUST遵守）

## WHY（なぜこのプロジェクトが存在するか）
ユーザー体験最優先のNext.jsアプリ。SSRで高速化。

## WHAT（何があるか）
- src/app: ルーティング
- lib/: ユーティリティ
- 詳細はdocs/api.md参照

## HOW（どう作業するか）
- ビルド: npm run build
- テスト: npm test --watch
- 新機能追加時: テスト同梱（MUST）
- 禁止: 本番DB直接操作

これだけ。40行もいかない。

ポイントは「MUST」「IMPORTANT」を冒頭に配置すること。Primacy効果——先に出た情報ほど遵守されやすい。

書くもの・書かないもの

書くもの 書かないもの
プロジェクト固有の罠 コードスタイル（Linter任せ）
運用ルール Git構造（Claudeが読める）
暗黙知（ドキュメントにない決定） 冗長な説明
トリガー+アクション 「～とは何か」の定義

例: 「新コンポーネント作成時 → *.test.tsx同時作成」。こういうトリガー+アクションの形式が一番確実に守られる。

解決策2: .claude/rules/への分割

CLAUDE.mdに全部書かなくていい。

.claude/rules/ にトピック別のファイルを置く。Claudeは関連するルールだけを読み込む。

.claude/rules/
├── security.md      # セキュリティルール
├── workflow.md       # ワークフロー
├── git.md           # Git運用
├── quality.md       # 品質基準
├── pr-review.md     # PRレビュー対応
├── research.md      # 研究ルール
└── autonomous.md    # 自律動作ルール

自分の環境はこの7ファイル構成。各30行以下。

効果:

  • トークン40%削減（全部読まなくていい）
  • 関連性35%向上（ノイズが減る）

全部を1つのCLAUDE.mdに詰め込むのがO(n)（足すほどコスト増加）だとしたら、ルール分割は**O(1)**に近い。必要なものだけ読むから、追加してもベースコストが変わらない。

「Claudeは既に賢い」という前提

公式ドキュメント（platform.claude.com）にこう書いてある:

「Claudeは既に賢い。知らないことだけ書け」

Claudeはコードが読める。ファイル構造も見える。gitログも追える。それなのにCLAUDE.mdに「このプロジェクトはNext.jsで構築されています」とか「srcディレクトリにコンポーネントがあります」とか書いてる人が多い。

見ればわかることは書かなくていい。書くべきは:

  • 見てもわからないこと（なぜこの構造にしたか、過去の事故の教訓）
  • やらないでほしいこと（禁止事項、地雷）
  • 特殊な手順（本番デプロイの手順、特殊なテスト方法）

2週間ごとのリファクタ

CLAUDE.mdは生き物。放っておくと肥大化する。

Cem Karacaの事例がわかりやすい:

時期 行数 トークン
1ヶ月目 150行 2,000
3ヶ月目 400行 8,000
6ヶ月目 800行 20,000
9ヶ月目 1,207行 42,200

9ヶ月で42,200トークン。コンテキストウィンドウの40%が設定ファイルだけで埋まる。

推奨: 2週間ごとに見直して、150行以下を維持。「もう不要になったルール」「重複」「見ればわかる情報」を定期的に削る。

自分の環境

項目 値
CLAUDE.md 90行
.claude/rules/ 7ファイル
各ルールファイル 10-40行

90行。最適範囲内。

ただし、最初から90行だったわけじゃない。スキル予算問題をきっかけに「入れすぎは逆効果」と学んで、削った結果がこれ。

正直、何を消すかの判断が一番難しかった。「これ要るかも」と思うものを消すのは怖い。でも消してみて問題が起きたことは一度もない。

まとめ: 書くな、削れ

CLAUDE.mdは短いほど強い。

  • 50-150行が最適
  • 200行超で30%の指示が消える
  • WHY/WHAT/HOW構造で40行にまとまる
  • 溢れた分は .claude/rules/ に分割
  • 2週間ごとに見直し
  • 「Claudeは既に賢い」——知らないことだけ書く

スキル予算と同じ結論にたどり着いた。足すより引く。

使用環境: Claude Code（Maxプラン $200/月）
参考: HumanLayer "Skill Issue"、SFEIR "CLAUDE.md Optimization"

GitHubで編集を提案

Discussion