はじめに
CLAUDE.mdを一つのファイルに書き続けて壊れる経験を、最初の三ヶ月でしました。情報が増えるほど指示同士が衝突し、Claude Codeの挙動が予測しづらくなっていきます。原因は内容の量ではなく、内容を置く場所の設計でした。
このシリーズの第2回は、CLAUDE.mdをグローバル・プロジェクト・タスクの三層に分けた設計判断を記録します。何を書くかではなく、何をどこに置くか。境界線の引き方で運用の安定度が変わります。
三層構造の全体像
CLAUDE.mdは「Claude Codeに毎回読ませる前提テキスト」です。ルール、コンテキスト、用語定義、優先順位を一度書いておけば、毎回同じ指示を打たずに済みます。
問題は、一つのファイルにすべて書こうとすると、無関係なルールが常に文脈に混ざることです。ゴルフ記事を書いているときに「Rinkerの登録フロー」がコンテキストに乗っている状態は、ノイズでしかありません。逆に、ある記事カテゴリだけ守りたい文体ルールを全体に適用すると、別カテゴリの記事まで縛られてしまいます。
三層で責務を分けると、この問題が一段消えます。
下に行くほど具体度が上がり、寿命が短くなる設計です。グローバルは「私はこういう人」、プロジェクトは「このブログはこういうもの」、タスクは「今この記事を書いている」。
一文で各層の責務をまとめると、こうなります。
- グローバル：人としての作法（言語、敬語、危険操作の確認、報告形式）
- プロジェクト：そのドメインの語彙と禁則（文体ルール、テンプレート、カテゴリ表）
- タスク：その瞬間のローカル文脈（観点メモ、引き継ぎファイル、当面のTODO）
この三つを混ぜないことが、CLAUDE.md運用の核です。
何をどの層に置くか
書く場所の判断は、二つの軸で決めます。
- 寿命：その情報は何ヶ月もつか
- 対象範囲：すべてのプロジェクトで有効か、特定プロジェクトのみか、今日だけか
この二軸で並べると、各層の守備範囲が見えてきます。
判断に迷ったときは、「これは別プロジェクトでも使うか」と「半年後も同じことを言いたいか」を自分に問います。両方Yesならグローバル、片方ならプロジェクト、両方Noならタスク層。
グローバル層に書くもの
人格や作法に関わる項目だけです。Claude Codeに対する「あなたへの基本指示」と読み替えると分かりやすい。
- 言語と敬語（日本語、敬語、断定を避けない）
- 不確実なときの挙動（推測で進めずに確認する）
- 危険操作の確認ルール（削除・上書き前に確認）
- ファイルの基本設定（文字コード、ライブラリ方針）
- 完了報告の形式（やったこと、ファイルパス、次のアクション）
ここに書いたものは、ゴルフ記事を書くときも、業務スクリプトを書くときも、すべての作業に効きます。逆に、特定プロジェクトでしか使わない情報を書くと、無関係な作業中もノイズになります。
プロジェクト層に書くもの
ドメイン語彙、テンプレート、禁則ルールが中心です。ブログ運営なら、文体・カテゴリ・タグ運用・記事構成テンプレが該当します。
- 想定読者プロフィール
- 禁止表現と推奨スタイル
- 記事構成テンプレート（領域別）
- カテゴリID表
- 個人情報・プライバシー配慮の境界
このレベルで決めたルールが、その後に書くすべての記事の品質を均します。プロジェクト層が薄いと、記事ごとに揺れが出るというのが運用一年での実感です。
タスク層に書くもの
その作業セッションでしか効かない情報です。観点メモ、引き継ぎファイル、当面のTODO、今書いている記事固有の制約など。
長期保存が前提のグローバル・プロジェクト層と違って、タスク層は書いた瞬間に意味があり、終わったら捨てるものです。これを上の層に混ぜると、過去の文脈が現在の判断を歪めます。
衝突したときの優先順位
各層に書かれた指示が矛盾した場合の解決順序を、最初に決めておく必要があります。決めずに運用すると、Claude Codeの挙動が回ごとにぶれます。
優先順位は下の層から見るのが原則です。具体的な指示が抽象的なルールを上書きします。これは「タスク層が一番偉い」という意味ではなく、「目の前の状況に近い情報を優先する」という運用ルールです。
ただし、一点だけ例外を置いています。安全に関わる項目はグローバル層が常に勝ちます。たとえば「削除前に確認する」はタスク層で上書きできないルールにしています。短期的な作業効率より、事故の不可逆性が大きいからです。
書きすぎ・書かなさすぎの境界
三層に分けても、各層の中で「書きすぎ」と「書かなさすぎ」の問題が残ります。
書かなさすぎのサインは、同じ指示を何度も繰り返している状態です。三回以上同じ指示を出していたら、その指示をどこかの層に昇格させる候補と見なします。
書きすぎのサインは、過去に一度だけ起きた例外をそのままルールとして残している状態です。一年前のある記事で発生した特殊事情が、今もすべての記事に影響している。これは書きすぎです。半年ごとに見直して、過去の事情を削っていきます。
どちらに倒れがちかは人によりますが、私の場合は「書きすぎ」に倒れます。一度書いたルールを消すことに心理的な抵抗があるためです。半年ごとに棚卸しの時間を取って、明示的に削る作業を入れています。
設計時に却下した代替案
一つだけ却下した案を残します。
案：一枚岩の長いCLAUDE.md
最初に試したのはこの構成でした。グローバルもプロジェクトも、すべてホームディレクトリの一枚のCLAUDE.mdに集約する。シンプルで、ファイル管理の手間がない。
却下した理由は、コンテキストの汚染です。ブログ記事を書いているときに業務用Pythonスクリプトのルールが混ざる。ゴルフ記事の制約が業務記事の判断に影響する。一度ノイズが入ると、Claude Codeの提案精度が体感で落ちます。
「分けないコスト」の方が「分けるコスト」より大きい、というのが運用での結論でした。
次回予告
次回は HTML+YAML方式を選んだ理由 を扱います。なぜMarkdownを選ばなかったか、YAMLフロントマターに何を入れるか、人間が書く領域と機械が読む領域をどう分けたか。原稿レイヤーの設計判断を解説します。
このシリーズで紹介する設計は、執筆時点の各ツールバージョンに基づきます。Claude Code、MCP、WordPress、各種APIは仕様変動が大きいため、最新ドキュメントとの照合をおすすめします。
