/init で終わらせない CLAUDE.md の設計 — blog-agents の62行を解体する

/init を叩いたら CLAUDE.md が生成された。「これで準備完了」と思って使い始めた。でも数日後、また同じ指摘を Claude に打ち込んでいた。「日本語で答えて」「テストを先に実行して」。

そのとき私は気づいた。CLAUDE.md を一度書いて終わりにしていた、と。

この記事では、私が実際に運用している blog-agents の CLAUDE.md（62行）を題材に、/init 後に何を判断し、何を別ファイルに送ったかを書く。設計の判断軸を持てば、CLAUDE.md は「書いたドキュメント」から「育つ仕組み」に変わる。

/init が作るもの、作れないもの

公式ドキュメントには次のように書かれている。

> Run /init to generate a starting CLAUDE.md automatically. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers.

読んで字のごとく、/init は「コードベースから読める情報」を書いてくれる。ビルドコマンド、テスト手順、ディレクトリ構造。これは確かに便利だ。

ただし限界がある。/init はコードを読むが、人の意図は読まない。

  • なぜこのディレクトリ構成にしたのか
  • どのエージェントが何の役割を持つのか
  • どのチャンネルに進捗を報告するのか
  • 文体は誰に向けた何調なのか

こういった「プロジェクトの暗黙ルール」「運用設計」「組織的な決まり」は、自分で追記するしかない。/init はスタートラインを引くツールであって、ゴールを決めてくれるツールではない。

なお、環境変数 CLAUDE_CODE_NEW_INIT=1 を設定すると対話型の新フローになる。CLAUDE.md / スキル / フックのどれを作るかを選び、サブエージェントがコードベースを探索し、不足を質問した上でプロポーザルを出してから書く。こちらも基本は同じで、暗黙ルールの記述は自分の仕事だ。

CLAUDE.md のヒエラルキーを把握する

CLAUDE.md には4つのスコープがある。どこに書くかで影響範囲が変わる。

スコープファイルの場所適用範囲
Managed Policy/Library/Application Support/ClaudeCode/CLAUDE.md（macOS）等組織全体
User~/.claude/CLAUDE.md個人の全プロジェクト
Project./CLAUDE.md または ./.claude/CLAUDE.mdチーム共有
Local./CLAUDE.local.md個人のプロジェクト内設定（.gitignore 推奨）

ロード順序は Managed → User → Project → Local で、すべてが連結されてコンテキストウィンドウに入る。

実務でよくある失敗は「全部 Project の CLAUDE.md に書く」パターン。個人の癖（一人称の使い方、コメントアウトの習慣など）を Project に書いてしまうと、チームメンバーの Claude にも適用されてノイズになる。「自分だけに効かせたいルール」は Local に分離する意識を持つといい。

CLAUDE.md を書くときに公式が示す3つの原則

公式ドキュメントを読むと、設計上の制約が明確に示されている。

まず行数の上限だ。CLAUDE.md はセッション開始時に毎回フルロードされ、トークンを消費する。公式には "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." とある。200行を超えると指示の追従率（adherence）が下がる。長く書けば書くほど Claude がよく動くわけではない。

次に具体性。「コードを整形する」ではなく「2スペースインデントを使う」。「変更をテストする」ではなく「コミット前に npm test を実行する」。抽象的な指示は Claude が解釈を選ぶ余地を残す。余地を残すと結果がブレる。

もうひとつは矛盾を作らないこと。公式には "if two rules contradict each other, Claude may pick one arbitrarily." とある。ネストされた CLAUDE.md や .claude/rules/ も含めて、矛盾する指示があると Claude が任意に一方を選ぶ。定期的な見直しを怠ると、増えた指示が互いに打ち消し合う。

blog-agents の62行を解体する

このブログを動かしている blog-agents の CLAUDE.md は62行だ（200行制限の約31%）。意図的に薄く保っている。全体の構造は次のようになっている。


## ブログ概要
（URL、テーマ、ターゲット、文体）

## ディレクトリ構造
（受信箱・リサーチ・下書き・公開済み・ナレッジのパス）

## アーキテクチャ
### サブエージェント（テーブル）
### スキル（テーブル）
### パイプラインフロー（ASCII diagram）

## Discord
（チャンネルIDと使い方）

## WordPress投稿
（REST API URL、認証情報の在処、投稿ステータス）

## 品質基準
（文字数、見出し、AI臭、盗作）

62行でこれだけの情報を持てている理由は、いくつかの設計判断にある。

テーブルで密度を上げる

6つのサブエージェントを各1行、6つのスキルを各1行で説明している。説明文よりテーブルの方がトークン効率が高く、Claude も構造を読み取りやすい。「Researcher エージェントはテーマのリサーチを担当し、research/ ディレクトリに結果を出力します」と書くより、テーブルの1行の方が伝わる情報量は同じで文字数は半分以下だ。

具体的な値をそのまま書く

数値・パス・環境変数名はあいまいにしない。

  • 「文字数: 2,000〜4,000字」（数値範囲で指定）
  • 「投稿ステータス: "publish"（公開）」（JSON の値そのまま）
  • 「config.env の WP_USER, WP_APP_PASSWORD」（環境変数名を明示）

「適切な文字数で書く」「公開設定で投稿する」という書き方だと、Claude が「適切」と「公開」を自分で解釈する。具体的な値を書けば解釈の余地がなくなる。

詳細は別ファイルに委譲する

CLAUDE.md はポインタの集合として機能させている。

  • 各サブエージェントの詳細プロンプトは .claude/agents/.md に
  • 各スキルの詳細は .claude/skills//SKILL.md に
  • ナレッジの蓄積は knowledge/ に

CLAUDE.md にすべてを書こうとすると200行制限を超えるし、更新のたびに CLAUDE.md を開くことになる。役割ごとに別ファイルに分けておけば、「Researcher エージェントを改善する」ときは researcher.md だけを触ればいい。CLAUDE.md 自体はほとんど変わらない。

スキル設計の詳細については、別記事（スキル設計編） でまとめている。

フローを ASCII diagram で可視化する

パイプラインフローをテキストで書くのではなく、以下のような形で示している。

テーマ → Researcher → Auditor(リサーチレビュー) → Writer → Tone Checker → Plagiarism → Auditor(最終レビュー)
                                                                                              ├─ NG → Writer(リライト)
                                                                                              └─ OK → WordPress投稿 → published/

「Researcher が終わったら Auditor がレビューし、その後 Writer が...」と文章で書くより、後段のエージェントが引き継ぎやすい。視覚的な構造は、文章では伝わらない「分岐の存在」を一目で示せる。フックとの責務分離については Hooks 実例記事 も参照してほしい。

育てるサイクルと knowledge/ との連携

設計したら終わりではない。CLAUDE.md は使いながら育てるものだ。

公式は追記すべきタイミングをこう示している。

> - Claude makes the same mistake a second time > - A code review catches something Claude should have known > - You type the same correction or clarification into chat that you typed last session > - A new teammate would need the same context

「2回目に同じ説明をした」と感じた瞬間が、追記のサインだ。その説明を CLAUDE.md（またはエージェントの設定ファイル）に書けば、3回目はない。

ただし、すべてを CLAUDE.md に書き込もうとすると肥大化する。blog-agents では、エージェント別の学習を knowledge/ ディレクトリで管理している。

  • knowledge/writer-lessons/avoid-patterns.md（AI臭のあるパターンの蓄積）
  • knowledge/tone-checker-lessons/patterns.md
  • knowledge/auditor-lessons/patterns.md

CLAUDE.md には「knowledge/ に各エージェントの学習ファイルがある」という一行だけ書き、詳細はそちらに委譲する。CLAUDE.md のサイズを維持しながら、エージェントの精度を継続的に上げられる。blog-agents の実際の運用体験については こちらの記事 に書いた。

規模が大きくなったら .claude/rules/ で分割する

200行を超えそうなプロジェクトでは、.claude/rules/ ディレクトリを使ってルールを分割できる。各ファイルに paths frontmatter を設定すると、適用範囲をファイルパターンで限定できる。

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation

このルールは src/api/**/*.ts ファイルを Claude が読むときだけコンテキストに追加される。常時ロードされる CLAUDE.md と違って、コンテキスト効率がいい。

blog-agents では .claude/rules/ を使っていない。規模的に不要だからだ。ただし大規模モノレポや、バックエンド・フロントエンド・インフラが混在するリポジトリでは、CLAUDE.md を200行以内に収めるためにこの分割を使うことになる。

まとめ

/init は出発点だ。自動生成された CLAUDE.md には、コードから読める情報しかない。プロジェクトの意図、運用設計、チームの約束事は自分で書く。

blog-agents の62行が示しているのは「何を書くか」ではなく「何を書かないか」の判断だ。詳細は別ファイルに委譲し、CLAUDE.md はポインタとして薄く保つ。「2回目に同じ説明をした」と気づいたときに1行追記する。その繰り返しで CLAUDE.md は育つ。

あなたの CLAUDE.md は、昨日より1行賢くなっているか。

参考リンク

コメント

タイトルとURLをコピーしました