
【衝突ゼロ達成】CLAUDE.md育成3ヶ月——10ルール×2層構造の設計思想
CLAUDE.mdを1ファイルで管理していた頃、プロジェクトが3つを超えた時点でルールが崩壊しました。グローバル10ルール×プロジェクト別の2層構造に移行して3ヶ月、ルールの衝突がゼロになりました。
この記事でわかること: Claude CodeのCLAUDE.mdを「グローバル層」と「プロジェクト層」に分離し、10個のルールファイルで管理する設計思想と、3ヶ月運用して見えた効果・失敗を紹介します。
Claude Codeを使っていてCLAUDE.mdが肥大化してきた方、複数プロジェクトでルール管理に悩んでいる方向けの記事です。Claude Code未経験の方にも、「AIエージェントへの指示書をどう設計するか」という観点で参考になります。
このnoteでは、非エンジニア向けにAI活用を実務ベースで解説しています。
はじめに
私はClaude Codeを2026年3月から本格的に使い始め、現在5つのプロジェクトを並行して運用しています。最初はCLAUDE.mdを1つのファイルに全部書いていました。Gitのコミット規約、セキュリティルール、プロジェクト固有のテンプレート指示——すべてが1ファイルに詰め込まれた状態です。
プロジェクトが3つを超えた時点で限界が来ました。あるプロジェクト用のルールが別のプロジェクトで誤って適用され、Claude Codeが意図しない動作をする。ルールを追加するたびに他のルールと矛盾していないか全文を確認する必要がある。CLAUDE.mdが200行を超えた頃には、もう管理不能でした。
この記事では、その混乱から3ヶ月かけて辿り着いた「2層×10ルールファイル」の設計思想を共有します。
CLAUDE.mdの構造設計に取り組んだ背景
Claude Codeは「コンテキストを与えるほど精度が上がる」ツールです。CLAUDE.mdはそのコンテキストの核——プロジェクトのルール、コーディング規約、禁止事項を定義する場所です。
しかし、ルールを書けば書くほど問題が起きました。
問題1: ルールの衝突
記事制作パイプライン(note-gen)では「Markdownテーブル禁止」というルールがあります。note.comがテーブルをレンダリングしないためです。一方、SaaS開発プロジェクトではMarkdownテーブルを使ったドキュメント生成が日常的です。1つのCLAUDE.mdに両方書くと、Claude Codeはどちらに従うべきか迷います。
問題2: コンテキストの肥大化
全プロジェクト共通のルール(Gitコミット規約、セキュリティポリシー等)を各プロジェクトのCLAUDE.mdにコピペしていました。5プロジェクトで同じ内容を5箇所に書く。1箇所を更新したら他の4箇所も手動で同期する必要がある。当然、同期漏れが発生します。
問題3: ルールの優先順位が不明
「セキュリティルールとプロジェクト固有ルールが矛盾したらどちらが優先か」——この判断基準がなかったため、Claude Codeの挙動が予測不能になっていました。
CLAUDE.mdの構造で実践した3つの設計アプローチ
アプローチ1: グローバルとプロジェクトの2層分離
最初に取り組んだのは、ルールを「どのプロジェクトでも共通」と「プロジェクト固有」に分離することです。
Claude Codeは2つの場所からCLAUDE.mdを読み込みます。
グローバル: `~/.claude/CLAUDE.md` — 全プロジェクトに適用される
プロジェクト: `{プロジェクトルート}/CLAUDE.md` — そのプロジェクトだけに適用される
私のグローバルCLAUDE.mdには、設計ドキュメント自動生成と開発ログ出力の2つのルールだけを書いています。「コミット後にObsidianにログを書き出す」「plan modeの計画が完了したらdocs/に設計書を保存する」——これらはプロジェクトを問わず常に必要なルールです。
一方、プロジェクト固有のルールはプロジェクトのCLAUDE.mdに書きます。たとえば記事制作パイプライン(note-gen)には「Markdownテーブル禁止」「タイトルに固有名詞を必ず含める」「note.com APIからURLを取得する」といったルールがありますが、これらはSaaS開発には一切関係ありません。
なぜこの分離にしたか: 最初は「よく使うルールをグローバルに」と考えましたが、それだと境界が曖昧になります。判断基準を「プロジェクトを問わず常に必要か」の一点に絞ったことで、グローバルに入れるルールが2つだけに収まりました。少ないほうが衝突リスクが下がります。
アプローチ2: 10個の独立ルールファイルに分割
グローバルCLAUDE.mdが2ルールだけだと少なすぎるように見えますが、実際にはClaude Codeのsettingsで追加のルールファイル(.claude/settings.json の include設定)を参照させています。私はdotfilesリポジトリに10個のルールファイルを管理しています。
core.md — セッション復帰時の最優先プロトコル(コンパクション後に「自分が誰か」を確認してから作業する)
git-workflow.md — コミット規約、ブランチ戦略、push前の確認フロー
security.md — 機密ファイルの取り扱い、APIキー管理、DB操作の安全策
error-handling.md — デバッグの手順、エスカレーション基準
delegation-policy.md — マルチエージェント環境での委譲基準
output-contracts.md — エージェント出力の品質基準(根拠の明示、確信度の付記)
kitchen-roles.md — マルチエージェントの権限制約(Chef/Sous Chef/Cook)
global-vs-project-boundary.md — グローバルとプロジェクトの責務分離
hypothesis-cycle.md — 仮説検証サイクル(機能追加は仮説として扱う)
obsidian-log.md — 開発ログの出力フォーマット
なぜ10ファイルに分けたか: 1ファイルにまとめると200行を超え、ルール間の依存関係が見えなくなります。ファイルを分けることで「Gitのルールを変えたい → git-workflow.mdだけ編集」「セキュリティポリシーを強化したい → security.mdだけ編集」と、変更の影響範囲が明確になります。
もう1つの理由は、dotfilesリポジトリで管理することで、新しいマシンでも `git clone` 一発で同じルール環境が再現できることです。CLAUDE.mdの設定は「コードと同じようにバージョン管理する」のが正解だと考えています。
アプローチ3: 衝突時の優先順位を明文化
10個のルールとプロジェクトCLAUDE.mdが同時に読み込まれると、矛盾が起きる可能性があります。そこで `global-vs-project-boundary.md` に明文化したルールがあります。
「衝突時はプロジェクトルールが優先」
これは単純ですが強力な原則です。たとえば、グローバルのoutput-contracts.mdには「日本語で出力する」とあります。しかし英語圏向けのプロジェクトがあれば、そのプロジェクトCLAUDE.mdに「英語で出力する」と書くだけでオーバーライドできます。
さらに、責務の境界も定義しました。
セキュリティの専門判断 → グローバルのsecurity-reviewerエージェントに委譲
コード品質・命名規則 → プロジェクト固有のquality-reviewerが担当
エラーの根本原因分析 → グローバルのdebuggerが担当
修正の実装 → プロジェクトのcookが担当
何を捨てたか: 当初は「ルールの優先度を数値(priority: 1-10)で管理する」案も検討しました。しかし数値による優先度管理は、ルールが増えるほど調整が複雑になります。「プロジェクトが勝つ」という単純なルール1つのほうが、運用コストが低いと判断しました。
CLAUDE.mdの管理工数:確認範囲が200行 → 30行に縮小
定量的な変化を整理します。
Before(1ファイル管理)
ルール総行数: 約200行(1ファイル)
ルール追加時の確認範囲: 全200行
プロジェクト間のルール衝突: 月2-3回
新プロジェクト追加時の作業: CLAUDE.mdを全文コピー → 不要な部分を削除(30分程度)
After(2層×10ファイル管理)
ルール総行数: グローバル約300行(10ファイル合計)+ プロジェクト別50-150行
ルール追加時の確認範囲: 該当ファイルの30行程度
プロジェクト間のルール衝突: 3ヶ月でゼロ
新プロジェクト追加時の作業: プロジェクトCLAUDE.mdを新規作成するだけ(5分程度)
ルールの総行数は増えました。しかし「確認すべき範囲」が200行 → 30行に縮小したことで、ルール追加・変更の心理的ハードルが大幅に下がりました。以前は「何か壊れるかもしれない」と思ってルール追加を躊躇していましたが、今は気軽に試せます。
CLAUDE.md設計の失敗と注意点
CLAUDE.mdのファイル分割で失敗した初期設計
最初は「git.md」「code.md」「agent.md」の3ファイルだけで分割しました。しかし「code.md」にセキュリティルールとエラーハンドリングとコーディング規約が混在し、結局1ファイルが100行を超えて見通しが悪くなりました。
現在の10ファイル構成にたどり着くまでに、3回の再構成を経ています。「1ファイル = 1つの関心事」を徹底したことで安定しました。
dotfilesで管理するリスク
ルールファイルをdotfilesリポジトリで管理しているため、うっかりpublicリポジトリにpushすると、自分の開発プロセスや使用ツールが全公開されます。私はprivateリポジトリで管理していますが、この点は注意が必要です。
過剰なルール追加の誘惑
ルールを分割して管理しやすくなった結果、「あれもルールにしよう」「これも書いておこう」と追加しがちです。3ヶ月で10ファイル・300行に膨れましたが、Claude Codeが毎回すべてを読み込むことを考えると、不要なルールは削除すべきです。
私の基準は「過去2週間で実際にこのルールが効いた場面があったか」です。効いていないルールは `deprecated/` に移動して様子を見ます。
全プロジェクトに適用されるルールの副作用
グローバルルールの「gitコミット後にObsidianにログを出力する」は便利ですが、一時的な検証プロジェクトでもログが生成されます。小さなPoCや実験用のプロジェクトでは邪魔になることがあります。Claude Codeには「特定のプロジェクトでグローバルルールを選択的に無効化する」専用の仕組みはありません。私はプロジェクトCLAUDE.mdに「Obsidianログは不要」と書いてオーバーライドしています。
CLAUDE.md設計で得た独自の学び
「ルール」ではなく「判断基準」を書く
初期のCLAUDE.mdには「コミットメッセージは50文字以内にすること」のような具体的なルールを書いていました。しかし、これだとルールが膨大になります。
現在は「判断基準」を書くようにしています。たとえば、delegation-policy.mdには「3ステップ未満のタスクは委譲しない」「セキュリティ関連の変更時はsecurity-reviewerを起動する」といった判断フローを書いています。Claude Codeに「何をするか」ではなく「どう判断するか」を教えるほうが、未知の状況への対応力が上がります。
CLAUDE.mdは「育てるもの」
CLAUDE.mdを最初から完璧に設計しようとすると失敗します。私のCLAUDE.md関連ファイルは3ヶ月で約50回コミットされています。最初の1週間は3行しかなかったものが、実際の開発で問題にぶつかるたびに1-2行ずつ追加され、現在の構成になりました。
重要なのは、ルールを追加するタイミングです。「Claude Codeが意図しない動作をした時」がルール追加のシグナルです。事前に網羅的にルールを書くのではなく、実際の問題からルールを抽出するアプローチが最も効率的でした。
仮説検証サイクルとの統合
私のルールファイルの1つ(hypothesis-cycle.md)は、機能追加や設計変更を「仮説」として扱うことを定めています。実装完了後に「仮説どおりだったか」を振り返り、正しければpatternsとして、間違っていればpitfallsとして記録します。
これをCLAUDE.mdの運用自体にも適用しています。新しいルールを追加する時は「このルールがあれば〇〇の問題が防げるはず」という仮説を立て、2週間後に検証します。効果がなければ削除する。この仮説駆動のアプローチが、ルールの肥大化を防いでいます。
次にやるべきこと
まずグローバルCLAUDE.mdとプロジェクトCLAUDE.mdを分離する。 `~/.claude/CLAUDE.md` にプロジェクト共通のルール(Git規約、セキュリティポリシー等)を移動し、プロジェクトのCLAUDE.mdにはプロジェクト固有のルールだけを残します
グローバルルールが50行を超えたら、関心事ごとにファイルを分割する。 「git-workflow.md」「security.md」から始めて、必要に応じて増やします。最初から10ファイルにする必要はありません
2週間ごとに「このルールは最近効いたか」を確認する習慣をつける。 効いていないルールは削除候補です。CLAUDE.mdは書くことより「削ること」のほうが難しい
この記事が参考になったら、スキとフォローで応援お願いします。次回はCLAUDE.mdの「育て方」を具体的なルール追加プロセスとして深掘りする予定です。