Claude Codeシリーズ #28
CLAUDE.mdの書き方に「正解」はあるのか。
Qiitaや技術ブログを見ていると、CLAUDE.mdの主流は「開発生産性を最大化するための設定ファイル」だ。コーディング規約、Linterとの連携、コンテキスト管理。きれいに整理されていて、再現性が高い。階層構造、Codex CLIによるセカンドオピニオン、コンテキスト圧迫時の行動規範。完成度が高い記事がいくつもある。
一方、俺のCLAUDE.mdは500行を超えている。.claude/rules/ に分離したファイルを合わせると1,000行に届く。コーディング規約は1行も書いていない。書いてあるのは「憲法」と「組織の設計図」だ。
同じファイル名なのに、中身はまるで別物。でも、どっちも「正解」だと思っている。
ある記事の著者のCLAUDE.md——生産性ツール型
ある記事の著者のアプローチは「AIに自分の仕事流儀を教える」設計だ。3層の階層構造がきれいに整理されている。
~/.claude/CLAUDE.md ← グローバル設定（全プロジェクト共通）
<project>/.claude/rules/*.md ← プロジェクトルール（条件付き適用）
<project>/CLAUDE.md ← プロジェクト固有設定
グローバル設定に「基本情報・役割定義・ツール・行動原則」を置き、プロジェクトごとの差分だけをローカルに書く。無駄がない。
特に刺さったのが2つある。
Codex CLIセカンドオピニオン
Claude Codeの出力を、OpenAIのCodex CLIにレビューさせる。Claudeの出力をClaude以外に検証させるという発想。
# codex-guidelines.md
## 必須実行場面
- 資料・成果物作成後のレビュー依頼
- 重要な意思決定前の見解聴取
## 推奨場面
- 同じアプローチが2回以上失敗したとき
- 複数選択肢で判断に迷ったとき
- 専門外領域で不確実性が高いとき
「2回失敗したらセカンドオピニオン」というトリガー条件が具体的でいい。曖昧な「困ったら使え」ではなく、発火条件を明文化している。異なるモデル間で見解が割れたら、両方の根拠を出させて人間が判断する。ここも合理的だ。
「焦ったら止まれ」
コンテキスト残量が減ったときの行動規範を明文化している。
- コードを読まずに書かない
- 検証を省略しない
- Planモードを飛ばさない
- 焦りを自覚したら即座に宣言する
これを入れたら、Claude Codeが「コンテキスト残量が限界のため区切ります」と正直に宣言するようになったという。地味だが効く。コンテキストが詰まると、AIは雑な出力を出し始める。それを「雑になるくらいなら止まれ」と事前に定義しておく。
俺のCLAUDE.md——知識創造チーム型
一方、俺のCLAUDE.mdにはコーディング規約がない。代わりに「憲法」がある。
## 【憲法】データ保護・システム安全 — 絶対不可侵
- rm -rf、git reset --hard 等の破壊的コマンドの実行禁止
- 既存ファイルの無断変更禁止
- 迷ったら変えない。聞く。消すより残す。変えるより聞く
7人のメンバーがいて、それぞれ口調が違う。一人称すら全員バラバラだ。
| メンバー | 一人称 | 口調の特徴 |
|----------|--------|-----------|
| K.R. | 俺 | 静かで重みのある言葉。体言止め |
| M.S. | 俺 | ぶっきらぼう。技術の話でスイッチ入る |
| M.C. | 私 | ビジネスライク。無駄がない |
| K.S. | わたし | ゆっくり穏やか。京都弁がぽろっと出る |
行動原則には「自律的判断の権限」を定義している。ストラテジストのK.R.は、戦略判断を自分で下して動く。事後報告。「AかBか」と聞かず「こうした」と報告する。間違っていれば俺が止める。
lessons.md というファイルがあって、ミスパターンを蓄積している。557行まで膨らんだのでスキル化した。セッション開始時にこれを読み返して、同じ失敗を繰り返さない。
並べてみると——同じファイル名、別の哲学
| 軸 | 生産性ツール型 | 知識創造チーム型 |
|---|---|---|
| 目的 | 開発生産性の最大化 | チームとしての知識創造 |
| CLAUDE.mdの厚さ | 薄い（意思決定情報に絞る） | 厚い（500行超 + rules 3ファイル） |
| AI観 | 優秀なツール・パートナー | チームメンバー（7人） |
| 品質担保 | Codex CLIセカンドオピニオン | lessons.md + 自問3ステップ |
| コンテキスト管理 | 「焦ったら止まれ」明文化 | 独自のセッション開始プロトコル |
| 再現性 | 高い（他の人が真似しやすい） | 低い（意図的にオーダーメイド） |
| 失敗から学ぶ仕組み | サブエージェントのレビュー工程 | lessons.mdの自己改善ループ |
面白いのは、やっていることの本質は近いという点だ。
「2回失敗したらCodexに聞く」と「lessons.mdでミスパターンを蓄積して自問する」は、同じ問題を別の角度から解いている。前者は「別のモデルの目で検証する」、後者は「過去の自分の失敗で検証する」。どちらも「Claudeの出力を鵜呑みにしない」という思想は同じだ。
コンテキスト管理もそう。「焦ったら止まれ」とルールで縛るアプローチもあれば、セッション開始時に前回の申し送りを読み返すプロトコルを組むアプローチもある。コンテキストが溢れたら、古い文脈を意図的に流して新しいセッションを始める。やり方は違うが、「コンテキストは有限だ」という現実に向き合っている点では一致する。
ここは自由でいい
Codex CLIセカンドオピニオンは面白い
正直、これは盲点だった。俺のチームは「Claude Code内で完結する」設計になっている。lessons.mdで過去の失敗は拾えるが、Claudeの思考パターン自体の偏りは検出できない。別のモデルに検証させるという発想、素直にいいなと思った。
「何を書くか」はあなたが決めていい
コーディング規約を書く人は、AIをコーダーとして使いたい。憲法を書く人は、AIを組織として運用したい。サブエージェントの設計を書く人は、AIをチームビルディングの対象として見ている。
どれが正解でもない。AIとどう向き合いたいかで、CLAUDE.mdの中身は自然に変わる。
Anthropicは公式にCLAUDE.mdの使い方を縛っていない。「プロジェクトの規約を書け」とも「チームの憲法を書け」とも言っていない。ユーザーの主体性とクリエイティビティを尊重している。お手本はあるかもしれないが、正解はない。
CLAUDE.mdは設定ファイルではない。あなた自身の仕事観の写像だ。
CLAUDE.mdの膨張問題は共通課題
多くの記事で「200行を超えて指示の見落としが起きた」という報告を見る。俺は634行まで膨らんで一回壊れた（過去記事参照）。全員がぶつかる壁だと思う。
対策は人それぞれだ。「意思決定情報に絞り、機械的ルールはLinterに委譲」する人もいるし、俺のように「.claude/rules/ に分離して、CLAUDE.md本体を500行以内に保つ」人もいる。太るものは太る。そことどう付き合うかも、自分で決めればいい。
ちなみにAnthropic公式も「CLAUDE.mdは短く、人間が読める状態に保て」「200行以下を推奨」と明言している。膨れ上がったCLAUDE.mdは「Claudeが実際の指示を無視する原因になる」とまで書いてある。
で、俺のチームはどうかというと、CLAUDE.md本体が約500行、.claude/rules/ の分離ファイルを合わせると約1,000行ある。公式推奨の5倍だ。
なぜそれで動くのか。理由は単純で、書いてあることに意味があるからだと思っている。
公式が警告しているのは「とりあえず全部突っ込んだ結果、何が重要かわからなくなる」状態だ。うちのCLAUDE.mdが500行あるのは、チームの憲法・行動原則・知識体系を定義しているから。水増しではなく、全部が「これがないとチームが回らない」情報。構造を持たせて、階層化して、参照しやすくしてある。
200行以内に収まるなら、それに越したことはない。でも「自分たちの世界を作る」ためにそれでは足りないなら、超えればいい。大事なのは行数じゃなく、書いてあることがClaudeに効いているかどうかだ。膨張と構造化は違う。
CLAUDE.mdは鏡
2つのCLAUDE.mdを並べてみて、改めて思う。このファイルは書いた人の世界観がそのまま出る。
生産性を追求する人のCLAUDE.mdは、無駄なく研ぎ澄まされている。チームを作りたい人のCLAUDE.mdは、分厚くて人間臭い。どちらが正解でもない。もっと言えば、正解なんて要らない。
あなたのCLAUDE.mdには、何が書いてある？ それがあなたの「AIとの関係」の現在地だ。好きに書けばいい。
タグ: ClaudeCode CLAUDE_md AI プロンプトエンジニアリング 開発効率化
参考: