Claude Codeを使い始めて最初に書くファイルがCLAUDE.mdだ。ここに何を書くかでエージェントの振る舞いが変わる。今回は、このブログの運用リポジトリで1年弱運用してきた結果、4枚に分かれたCLAUDE.mdの構成と、そこへ至る判断を書く。
先に結論を書くと、分けた軸は「対象範囲」ではなく守られなかったときの被害の大きさだった。全部を1枚に書いていた時期もあるが、長くなるほど後半の記述が効かなくなる。
今の構成：ルート1枚＋チャネル3枚
現在の配置はこうなっている。
| ファイル | 行数 | 書いてあるもの |
|---|---|---|
CLAUDE.md（ルート） |
111行 | 絶対ルール、並行作業の事故防止、セットアップ |
blog/CLAUDE.md |
112行 | ブログ作業の開始手順、ディレクトリの構成 |
threads/CLAUDE.md |
382行 | Threads運用の詳細ルール |
x/CLAUDE.md |
335行 | X運用の詳細ルール |
Claude Codeは、作業対象のファイルがあるディレクトリの親をたどってCLAUDE.mdを読む。blog/配下のファイルを触るときはルートとblog/の2枚が効き、x/配下ならルートとx/の2枚になる。チャネルをまたがない作業では、他チャネルの300行超を読まずに済むのがこの構成の利点だ。
子ファイルの冒頭は3枚とも同じ形にしている。
# x/ CLAUDE.md
X（`@amazenpapa`）チャネルの作業ディレクトリ。ここ配下のファイルを扱う作業では、
以下を必ず確認すること。書き出しを揃えるのは好みの問題に見えるが、実務では効いた。エージェントは複数のCLAUDE.mdを同時に読むので、どのファイルの記述なのかが本文から分かるようにしておかないと、ルートのルールと子のルールを取り違える。
分ける軸は「対象範囲」ではなく「破られたときの被害」
最初は「ルートには全体の話、子には個別の話」という素朴な基準で分けていた。だがこれだと、書く場所に迷う記述が大量に出る。ブログとXの両方に関わる記述は? 特定チャネルだが重大なルールは?
今使っている基準はこうだ。
- ルートに置く: 破られると復旧が困難なもの。main直push禁止、守秘義務、シークレットの置き場所
- 子に置く: 破られても作業をやり直せば済むもの。投稿の型、確認の順序、ファイルの役割
この基準にしてから、置き場所で迷うことがほぼなくなった。「これを破られたら何が起きるか」を一度考えれば、答えが出る。
ルート側は実際に短い。111行のうち、絶対ルールは6項目で20行程度しかない。重要なものほど短く、上に置く。長い説明が要ると感じたら、それは子ファイル側に書くべき運用手順である場合が多い。
長い記述は「なぜそうするか」を先に書く
子ファイルが300行を超えているのは、単にルールが多いからではない。事故の経緯を書いているからだ。
ルート側にある並行作業のルールを例にすると、こういう構造になっている。
- このリポジトリでは複数セッションが並行作業するのが常態
- 過去にクリップボード競合・編集競合・ブラウザタブの誤操作が起きた
- worktreeという仕組み自体は分離するが、事故を防いでいるのは都度の目視確認という運用である
- だから以下を守る（具体的な手順）
3を書くかどうかで、エージェントの振る舞いが変わった。手順だけを書くと、似て非なる状況で「これは該当しないだろう」と判断されることがある。何を守るための手順かが書いてあると、手順に書いていない状況でも同じ趣旨の行動を取る。
逆に言えば、経緯を書くほどファイルは長くなる。だからこそ、長くなるものを子ファイルへ追い出す構造が要る。
守られなかったルールは、CLAUDE.mdから降ろす
運用していて一番はっきりした学びがこれだ。CLAUDE.mdに書いても守られないルールが一定数ある。
私の場合、運用の数値基準を書いたファイル（投稿頻度やエンゲージ率の閾値）を「基準の見直し作業でないときは変更しない」とCLAUDE.mdに書いていたが、守られなかった。基準を参照しながら別の作業をしている最中に、ついでに直されるという形で通過する。
対処は、ルールを強い言葉で書き直すことではなく、フックに降ろすことだった。ファイルへの書き込みを検査して、条件に合わなければ止める。判断がモデルの外側にあるので、文脈の長さにも、その場の推論にも左右されない。
この降格ができるかどうかで、CLAUDE.mdに何を書くべきかが変わる。
- 機械的に判定できるもの: フックか検査スクリプトへ降ろす。CLAUDE.mdには書かない（あるいは補足として残す）
- 判定に文脈が要るもの: CLAUDE.mdに残す。「実体験は複数案件を合成して抽象化する」のような、内容の良し悪しに関わる判断
CLAUDE.mdは機械化できなかったものの受け皿だと考えると、書く量が自然に減っていく。
迷ったときの3つの確認
自分で書くときに使っている確認をまとめておく。
- これは機械的に判定できるか: できるならフックか検査へ。CLAUDE.mdは最後の手段
- 破られたら復旧できるか: できないならルート、できるなら子ファイル
- なぜそうするかを1文で書けるか: 書けないなら、そのルールはまだ言語化が足りていない
3が一番効いた。経緯を書こうとして書けないルールは、たいてい「なんとなくそうしている」だけで、実は守る必要がなかったり、別の書き方が適切だったりする。
まとめ
- CLAUDE.mdは1枚に全部書かず、ルート＋サブディレクトリの階層に分ける。Claude Codeは親をたどって読むので、作業範囲に関係ないルールを読ませずに済む
- 分ける軸は「対象範囲」ではなく「破られたときの被害の大きさ」。復旧困難なものをルートへ、やり直せるものを子へ
- 手順だけでなく「なぜそうするか」を書くと、手順に書いていない状況でも同じ趣旨の行動が取られる
- 守られなかったルールは、言葉を強くするのではなくフック・検査スクリプトへ降ろす
- CLAUDE.mdは「機械化できなかったものの受け皿」と考えると、書く量が減って効き目が上がる
