「CLAUDE.mdの書き方」で検索すると、書くべき項目のテンプレートを紹介する記事はたくさん出てくる。だが実際に運用してみて詰まるのは項目の中身より、どこに置いて、どれだけの分量にするかの方だった。自社で5週間運用しているCLAUDE.mdを実際に数えてみたところ311行あり、Claude Code公式ドキュメントが推奨する上限を超えていた。何が起きていたのかを、公式の設計と照らして整理する。

公式が示す階層——4つのスコープと「200行」

Claude Codeの公式ドキュメントによると、CLAUDE.mdは4つのスコープに分かれ、読み込む順番も決まっている。

スコープ置き場所誰と共有されるか
組織管理ポリシーOSごとの管理者専用パス組織の全ユーザー
ユーザー~/.claude/CLAUDE.md自分のみ（全プロジェクト）
プロジェクト./CLAUDE.mdチーム全員（バージョン管理経由）
ローカル./CLAUDE.local.md自分のみ（そのプロジェクト）

モノレポで複数プロジェクトを抱える場合は、さらに専用のガイドが「ルートに薄い全体方針、各パッケージ配下にそのパッケージ固有の指示」という2階層構成を勧めている。パスを限定したいだけなら.claude/rules/にpaths指定のルールを分けて置く方法もあり、他チームのCLAUDE.mdが目に入って邪魔ならclaudeMdExcludesで個別に除外できる。

分量については明確な数字がある。「1ファイルあたり200行を目安にする。長いファイルはコンテキストを消費し、指示への追従率を下げる」。理由は公式アカウント配布のガイドが具体的に説明していて、CLAUDE.mdはシステムプロンプトの一部ではなく、システムプロンプトの後に続く通常のユーザーメッセージとして毎回コンテキストに乗る仕組みだからだ。長くなるほど、それだけ他の会話に使える余地が削られる。

自分たちの実例——ルートは18行、プロジェクト側は311行

このプロジェクト自体、複数の個人開発プロジェクトを1つのリポジトリにまとめたモノレポ構成で運用している。実際に数えると次のようになっていた。

ファイル行数役割
リポジトリ直下のCLAUDE.md18行セッションの引き継ぎ手順と作業ブランチの指示のみ
このプロジェクト（claude-code-lp）のCLAUDE.md311行事業方針・LP構成・厳守事項・変更履歴
引き継ぎ用のHANDOFF.md713行セッションをまたぐ作業ログ

ルート側は公式が推奨する「薄い全体方針」の形にほぼ沿っていた。中身は「引き継ぎファイルを読んでから始める」「このブランチで作業する」の2点だけで、個別プロジェクトの詳細には踏み込んでいない。

一方、プロジェクト側のCLAUDE.mdは公式の目安を超えていた。理由ははっきりしている。5週間、ほぼ毎回のセッションで方針変更・実測結果・踏んだ落とし穴を追記し続け、一度も整理し直していなかったからだ。「書いておけば安全」という前提で追記を重ねた結果、公式ドキュメントが警告している状態——長いファイルがコンテキストを消費し、指示への追従率を下げかねない状態——に自分たちがすでに入っていた可能性がある。実際に追従率が落ちているかどうかまでは測定していないので、そこは断定しない。

崩れていた前提と、直せていない部分

公式ドキュメントには、CLAUDE.mdを短く保つための具体的な仕分け方も書かれている。ディレクトリ構成や依存関係の一覧のように、Claudeがコードを読めば自分で分かることは書かなくていい。逆に、ツールの既定動作から外れる理由・過去に踏んだ落とし穴・チーム固有の判断基準のように、コードを読んでも分からないものだけを残す。この仕分けを機械的にやる/doctorというコマンドも用意されている。

このプロジェクトのCLAUDE.mdを見返すと、両方が混在している。「セクションを増減したらSHT番号とナビを同期させる」のような今も有効なチェック項目もあれば、「この施策は効かなかった」という過去の観測結果の詳細な経緯もそのまま残っている。後者は資産としての価値はあるが、毎回のセッションでコンテキストに乗せる必要はない情報だ。この記事を書いている時点で/doctorによるトリムはまだ実行していない——「書いておけば安全」を「読ませる分だけ絞る」に切り替える作業は、次にやることとして残っている。

一つだけ、結果的に公式の考え方と一致していた運用がある。このプロジェクトのCLAUDE.mdには「グローバルルールの上書き宣言」という見出しがあり、「スキルは~/.claude/skills/配下に置く」という全社共通のルールに対し、このプロジェクトだけ例外的にプロジェクト配下にスキルを置いている理由を明記してある。公式ドキュメントも「複数のCLAUDE.mdで矛盾する指示があると、Claudeはどちらかを勝手に選んでしまう」と注意を促している。例外を作ること自体は避けられなくても、なぜ例外にしたかを同じファイルに書いておけば、矛盾ではなく意図的な分岐として扱える。

もう一つ、公式には直接対応する仕組みがなかった部分もある。713行のHANDOFF.mdは、Claude Codeが自動で学習内容を書き足す「自動メモリ」の仕組みとは別に、こちらで明示的に指示して更新させている引き継ぎ記録だ。自動メモリは端末ごとに保存される仕組みなので、端末をまたいだ作業（ターミナルとクラウド上のセッションを行き来する運用など）には対応しない。このプロジェクトが713行の手動ファイルを今も使い続けているのは、複数の実行環境をまたいで人間が読める記録を残す必要があったからで、自動メモリが解決する問題とは重ならない。

自社のCLAUDE.mdを見るときに確認すること

書き方のテンプレートより先に、次の3点を自分のプロジェクトで確認する方が実益が大きい。/contextコマンドでCLAUDE.mdが何行読み込まれているか実際に数えたことがあるか。モノレポなら、全プロジェクト共通の薄いルート指示と、各プロジェクト固有の指示が同じファイルに混ざっていないか。チーム共通のルールから外れた設定をどこかに作ったとき、その理由を同じ場所に書き残しているか。

このプロジェクトが差別化の核に据えている考え方——CLAUDE.md階層・スキル・サブエージェント・レビューゲートを開発標準として設計すること——は、書いて終わりではなく、書いたものを定期的に読み返して整理する運用まで含めて初めて機能する。導入支援の診断では、この設計と運用の両方を対象にしている。