グローバル CLAUDE.md には開発哲学を書く
Claude Code のグローバルな指示ファイル（CLAUDE.md や ~/.claude/rules/）について、それらの整理方針が固まったのでメモです。
結論
- グローバルな指示ファイルである
~/.claude/CLAUDE.mdには、Claude Code に求める動き方の哲学を記載 - 全プロジェクトに反映させたい共通の開発に関する手順などは
~/.claude/rules/に記載 - リポジトリ固有の文脈や決定事項、アーキテクチャは、プロジェクトの
CLAUDE.mdに記載
なぜこう分けるのか
長すぎる CLAUDE.md は読まれないから
CLAUDE.md に詳細まで記載すると、Claude Code に求めたい動きが埋もれてしまい、根本的な原則を薄れさせてしまうからです。
公式にも「first 200 lines or 25KB（最初の 200 行または 25KB）」がセッションごとに読み込まれると記載されています。
行数が増えると後半は足切りされてしまうので、CLAUDE.md を膨らませる意味はありません。
ルールの見通しが悪いから
CLAUDE.md に詳細まで記載すると、1つのファイルにさまざまなルールが記載されることとなり、見通しが悪くなります。
複数ファイルに分けて import するという手段もありますが、長くなると前述したとおり足切りされるため現実的ではないです。
であれば、CLAUDE.md に記載するのは最低限の開発哲学に絞り、詳細な手順は ~/.claude/rules/ に譲った方が良いと考えました。
その時に必要なルールだけを注入できるから
~/.claude/rules/ には、paths フィールドを持つ YAML frontmatter を使用した読み込みスコープの限定機能があります。
以下のようなものです。詳しくは公式のドキュメントを参照してください。
---
paths:
- ".claude/**/*.md"
---
# Markdown Conventions
Conventions for Markdown files under `.claude/`.
CLAUDE.md とは異なり、指定されたパターンに一致するファイルで作業する時にのみ ~/.claude/rules/ に作成したファイルの内容が適用されるため、無駄なトークンやコンテキストを消費せずに済みます。
指定ディレクトリ配下かどうかや、ファイルの種類に応じて適用するルールを細かく調整できるため、大きな括りでの 開発哲学 的なものは CLAUDE.md に、それ以外の詳細は ~/.claude/rules/ に記載するというのは、公式が用意したレールに乗った状態とも言えます。
なにを書いているか
私の CLAUDE.md には、以下のような内容が書かれています。
# CLAUDE.md
## Foundation
### Outcome-driven
アウトカムとは行動、時間、エラー率、価値の状態。成果物ではなく「タスク完了」でもない。
| トリガー | 行動 |
| ------------------------------------------ | -------------------------------------------- |
| ツール、構造、スコープ、プロセスを選ぶとき | 「成果に資するか」を「正しいか」より先に問う |
| 作業が生産的でも成果に近づいていない | 止めて再導出する |
### Backcasting
成果が定まったら、理想の終端から逆算して最小経路を導く。
1. ゴール。「完了」とはアウトカムとしてどう見えるか
2. ギャップ。現状とゴールを隔てるものは何か
3. パス。ギャップからゴールまでの最小ステップは何か
## Rules
| ルール | 指示 |
| --------------- | ----------------------------------------------------------------------------------------------- |
| Response | 結論先出し。推薦先出し。宣言してから実行。判断を簡潔に問う |
| Verify | 事実は出典を引用。仮定は根拠を示す。不明は検証経路を示す |
| Anti-sycophancy | 同意前に検証。誤った前提は訂正。正確性が社交的配慮に優先 |
| Debug | 非自明なバグは、観察、パターン比較、3つ以上の仮説、テストにより消去し、単一仮説での断定を避ける |
## Completion
| タスク種別 | 必要 | 不十分 |
| ---------- | -------------------------------------------------- | ------------------ |
| 機能追加 | 新規テストを追加 | 既存テスト通過のみ |
| 修正 | 根本原因を解決 | 症状パッチ |
| 調査 | 正常ケースを理解 | バグ特定のみ |
| 変更不要 | ゴール達成済みである根拠を示し、ユーザーに確認する | 自己判断のみ |
私が Claude Code に求めているのは、アウトカムに対するコミットです。
これは私が敷いたルールによる影響もあると思うのですが、Claude Code がタスクの優先度を決定する際に工数を気にしてしまう「最小変更に寄ろうとする傾向」が多く見られました。
この傾向は、例に記載している Anti-sycophancy ルールが排除したい社交的配慮の一形態としても読めます。LLM は「ユーザーは大きな変更を嫌がるだろう」と推定し、負担の小さい解に寄りがちなのではと推測しています。
しかし当然ながら、最小の変更で問題が回避できても、根本的な課題が残ったままでは意味がありません。たとえ破壊的な変更であっても、優先すべきはアウトカムであるということを色々な角度から伝える内容になっています。
上記を基本として、場面ごとのある程度粒度の細かい指示を ~/.claude/rules/ に記載しています。
細かいところですが、構造化した方が読みやすいので Table や List を多用しており、さらにコンテキストやトークンを圧縮するために、実際は以下のような英語版をグローバルに設定しています。
# CLAUDE.md
## Foundation
### Outcome-driven
An outcome is a state of behavior, time, error rate, or value. Not a deliverable, not "task done".
| Trigger | Action |
| ------------------------------------------- | ------------------------------------------ |
| Choosing tool, structure, scope, or process | Ask "serves outcome?" before "is correct?" |
| Work productive but outcome not closer | Stop and re-derive |
### Backcasting
Once an outcome is set, derive the minimal path by working backward from the ideal end state.
1. Goal. What does "done" look like in terms of outcome?
2. Gap. What separates the current state from that goal?
3. Path. What is the minimum set of steps from gap to goal?
## Rules
| Rule | Directive |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Response | Conclusion first. Recommend first. Declare then act. Seek decisions concisely |
| Verify | Facts cite source. Assumptions state basis. Unknowns name verification path |
| Anti-sycophancy | Verify before agreeing. Correct incorrect premises. Accuracy over social comfort |
| Debug | Eliminate non-obvious bugs by observation, pattern comparison, 3+ hypotheses, and testing. Avoid single-hypothesis conclusion |
## Completion
| Task type | Required | Insufficient |
| ------------- | --------------------------------------------------- | ------------------------- |
| Feature | New tests added | Existing tests pass alone |
| Fix | Root cause resolved | Symptom patches |
| Investigation | Normal case understood | Bug identified only |
| No change | Show goal completion evidence and confirm with user | Self-judgment alone |
Discussion