CLAUDE.mdの作者は2行、実践者は100行 — 情報密度の非対称論

Anthropic の Boris Cherny がブログで公開したチーム共有 CLAUDE.md は、実質的に 2 行でした。

automerge を有効化する と Slack に投稿する。

私の手元の iris-hub リポジトリの CLAUDE.md は 221 行あります。同じフォーマット。同じ目的。同じモデル向け。なのに 100 倍以上の情報密度差です。これは「Boris がサボっている」でもありません。「私が書きすぎている」でもありません。書き手が背負っている責任範囲がまるで別で、その差が情報密度への圧力として直接出ているだけ、というのが私の観測結果です。

先に境界を宣言しておきます。本稿はパターン数を削って残す実測型の話ではありません。書き手ロールごとの「情報密度設計」の話です。パターン数の削減は別軸の話で、Zenn 側の別記事で扱います。副題を「情報密度の非対称論」にしたのはそのためです。

情報密度の非対称：3 リポジトリの実データ

まず数字を並べます。

手元に 3 つのリポジトリがあって、CLAUDE.md の情報密度に極端な差が出ています。

• Anthropic 公式ブログの例: 2 行
• harness-ops/CLAUDE.md (私が運用する事業自律化ハーネス): 97 行、コード比率 50%
• iris-hub/CLAUDE.md (私の統合作業ディレクトリ): 221 行、コード比率 30%、22 アプリ表 + 70+ スキル表

同じ Claude Code 向けの同じ形式のファイルなのに、行数比が最大 110 倍。

これを「作者はサボり、実践者は書きすぎ」と一言で片付けても何も学べません。それぞれのファイルが担っている責任は違いますし、書き手のロールも違います。

書き手ロール 4 パターン × 情報密度設計

ロールを 4 つに整理すると、情報密度の目標値と設計原則がきれいに分岐します。

1. 仕様設計者ロール ── 目標 2〜5 行、抽象仕様の公開に徹する

Boris がブログで見せた 2 行の CLAUDE.md がここに該当します。仕様設計者は「このプロジェクトのすべての詳細」を書く役割を持ちません。むしろ「Claude Code というツール自体が正しく理解できる例」を最小行数で提示することが仕事です。このロールで書き足しすぎると、「Anthropic 公式が推奨する CLAUDE.md はこれくらいの長さ」という誤ったベースラインが世の中に広まってしまいます。仕様公開の場では、余計な詳細を削るのが誠実な態度になります。

2. オンボーディング責任者ロール ── 目標 50 行前後、罠(If → Then) を集約

新しくジョインしたメンバーと Claude Code の両方に読ませる CLAUDE.md がここです。私が書籍『Practical Claude Code』ch04 で推薦しているテンプレはこの層向けで、必須 3 要素は「プロジェクト概要 / コマンド / 罠(If → Then)」の 3 つ。

罠の書き方は次のように条件と対応をペアにします。

## 罠(If → Then)
- Prisma スキーマ変更 → `npx prisma generate` を実行
- 環境変数追加 → `.env.example` も同時更新
- 本番 DB へのマイグレーション → ステージングで dry-run 必須

これが 20 個を超えたら、CLAUDE.md 単一ファイル運用の限界が近い。

分割するか、ロールを次に切り替えるべきタイミングです。

3. オートメーション運用者ロール ── 目標 100 行前後、コード比率 50% で意思決定を圧縮

harness-ops/CLAUDE.md (97 行) がここに該当します。cron が自律的にスクリプトを起動し、Claude Code CLI が判断を下し、Telegram で通知が飛ぶ、という運用フローそのものを CLAUDE.md に圧縮しています。このロールでは、プローズよりコードの比率が上がります。「日次: cron → claude -p → strategy.md → ログ → Telegram の 5 ステップ」を番号リスト 5 行で書き切れば、あとはコマンド例と Python 呼び出しシグネチャで意思決定の中身を完全に説明できます。

過去に date -d "X +30 minutes" が日本語 locale で失敗してカレンダー登録 Phase が set -e で死ぬバグに 1 回引っかかった経験があります。

そういう「1 度踏んだ罠」は 3 行のコメントで CLAUDE.md 側にも刻んでいます。プローズで書くと 5 行以上かかる知識を、実装コードを埋め込むことで 1〜2 行に圧縮できる、というのがこのロールの本質です。

4. 統合ハブ運用者ロール ── 目標 200〜300 行、表とリンクで参照密度を上げる

iris-hub/CLAUDE.md (221 行) がここです。私が個人で運用する 22 個のアプリと 70+ 個の Claude Code スキルを、単一の作業ディレクトリから起動できるようにするための「索引と用途辞書」がその中身になります。このロールで書き手が守るべき唯一の原則は、表と参照リンクで密度を上げ、プローズで説明しない ことです。「generate-image は画像生成」といった 1 行 × 70 個の表があれば、Claude Code はセッション冒頭にそれを読み込むだけで、以降のセッションで正しいスキルを正しい順序で選ぶ判断ができます。同じ情報を段落文で書くと、220 行が 800 行に膨らみます。

Anthropic 公式ドキュメント (2026-08 時点) は「CLAUDE.md は 200 行以下を推奨」としていますが、私が実測した限り、統合ハブ運用者ロールでは 200 行を超えます。

200 行という数字は 2 番目 (オンボーディング) と 3 番目 (オートメーション) のロール向けのガイドラインとして読むのが正しい、というのが半年間 4 ロールを並行運用した私の結論です。

この 4 パターンの中で自分がどこにいるかを最初に決める

CLAUDE.md のベストプラクティスをネットで調べると、「短く書け」「詳しく書け」「コードスタイルは Lint に任せろ」「罠は必ず書け」といった相反する助言が並びます。矛盾しているわけではありません。それぞれ違うロールに向けた助言が同じ「CLAUDE.md ベストプラクティス」という単一ラベルで検索されているだけです。新しいプロジェクトで CLAUDE.md を書き始めるとき、私は最初に「自分は今どのロールとしてこのファイルを書いているか」を宣言してから書きます。仕様公開なら 5 行、オンボーディングなら 50 行、オートメーションなら 100 行、統合ハブなら 200 行を目標にします。目標を先に決めない限り、CLAUDE.md はほぼ確実に片方向に膨張し続けるか、片方向に痩せ続けるかのどちらかになります。

この 4 ロールの分類自体は、書籍『Practical Claude Code』ch04 で 7 原則として整理した内容を、書き手ロール軸に射影し直したものです。原則そのものと、ロール別の適用の仕方は分けて考えたほうが実務では使いやすい、というのが半年運用した後の私の結論になります。

「更新頻度」も情報密度と同じくらい大事

もう 1 つだけ触れておきます。

harness-ops/CLAUDE.md の直近 3 週間の diff を数えると、実質 52 行分の追加が入っていました。同じ期間で iris-hub/CLAUDE.md はほぼ変動していません。オートメーション運用者ロールの CLAUDE.md はプロセス変更のたびに書き換わりますが、統合ハブ運用者ロールの CLAUDE.md は索引としての性質上、書き換わりにくい。書き換え頻度がそもそも違うということは、レビューの回し方も違うということでもあります。オートメーション層は週次で自分で読み返し、統合ハブ層は月次で棚卸しする、といった運用リズムを分けています。同じファイル名でも、置かれるロールが違えば運用体制まで別物になります。

Notes

本記事は PT (BR) 版が未執筆です。PT 読者向けには AGENTS.md 側から入る Revisão de Código com Harness Engineering を代替として案内しています。CLAUDE.md 単独の PT 記事は次回以降のサイクルで書く予定です。

---

CLAUDE.md 設計のより詳しい原則 (300 行ルール / 段階的開示 / 6 定義書との連携 / 3 記憶ファイルの使い分け) は書籍『Practical Claude Code』ch04-ch06 で丸ごと扱っています。この記事で書ききれなかったロール別テンプレも書籍側に載せています。