CLAUDE.md（クロード・ドット・エムディ）とは、Claude Codeが実行の最初に読み込む1枚のルールブックです。第2章では「1コマンドで6工程が回る」パイプラインの流れ（How）を解きほぐしました。今回はその内側で流れを支える「司令塔CLAUDE.mdとサブエージェント分業」の設計思想（Why）に踏み込みます。なぜルールを1ファイルに集約するのか、なぜ役割を分けるのか、どうやってこの形にたどり着いたのか——実運用で分かったことを、失敗の話も交えて書いていきます。
司令塔CLAUDE.mdに何を書くか——1ファイルに集約する理由
「司令塔」と呼んでいますが、その正体はプロジェクトフォルダの直下に置いた、たった1つのMarkdownファイルです。中身は、このブログを動かすためのあらゆる前提が並んでいます。
具体的に、CLAUDE.mdには次のような塊が入っています。
- ブログのコンセプト・対象読者・トーンといった、記事の「顔つき」を決める前提
- SEOルール（タイトル文字数の目安・メタディスクリプション・キーワード配置）と競合調査の方針
- 使うカテゴリの一覧・カテゴリ選定の判断フロー
- リード〜本文〜まとめの型と、見出し構造のルール
- WordPress書き込み作業の検証ルールや、「投稿は1回だけ」といった運用ルール
- 自動化してはいけないこと（カテゴリの自動作成禁止・公開の自動化禁止など）
なぜ1ファイルに集めるのか。理由はシンプルで、Claude Code本体と各サブエージェントは、走り出す最初にこのCLAUDE.mdを読み込むからです。指示を1ファイルに束ねておけば、「共通ルールをどのエージェントも読み落とさない」という保証が作れる。毎回「このブログのコンセプトは〜」「トーンは〜」と説明し直す必要もありません。
もう一つ大事なのは、書くべきは「テンプレート」ではなく「なぜそう書くか」という思想である、ということです。たとえば「タイトルは28〜32字」というルールを書くときは、そこに「文字数を守るために訴求要素を削るのは避ける」という原則を必ずセットで書きます。判断が必要な場面でAIが正しい選択をするためには、数字だけでなく理由まで手渡しておく必要がある。この意識で書くと、CLAUDE.mdは長くなりますが、実運用でのブレはぐっと減ります。
副産物として、このファイルは自分自身の思考の棚にもなります。「なぜこのブログをこう運営するのか」を言語化して1か所にまとめておくと、後から自分で読んで判断がブレなくなる。指示書は、AIのためだけでなく、自分のための備忘録でもあるのです。
サブエージェントをどう分けるか——役割を絞る設計
CLAUDE.mdを司令塔とするなら、agents/ フォルダに置いた各サブエージェントの指示書は「専門部隊のマニュアル」です。トリヴィペディアでは、役割ごとに5つに分けています。
- Researcher：競合調査を担当（何を調べるか・差別化ポイントの抽出まで）
- Writer：構成案作成と本文執筆を担当（トーン・見出し・画像方針まで）
- SEO Checker：完成した下書きに対するSEO観点の検査と自動修正
- Fact Checker：数字・固有名詞・「諸説あり」情報などの事実確認
- Publisher：WordPressへの投稿と、投稿後の実データ検証
なぜ役割を分業するのか。答えは、指示書は薄いほど強いからです。1つのエージェントに「調べて・書いて・チェックして・投稿して」まで全部やらせようとすると、指示書は肥大化し、AIの注意もあちこちに分散します。結果、大事なルールを読み落とす。
たとえば、Fact Checker の指示書は事実確認に関わる項目だけに絞られていて、「文体はこう」「見出しはこう」といったWriterの話は入っていません。だからFact Checkerは、自分の仕事だけに集中して事実確認に取りかかれる。逆にWriterは、事実確認の細かい手順を知らなくても、CLAUDE.mdに書かれた「不確かな情報には諸説ありと明記する」という共通ルールに従って書けばいい。共通ルールはCLAUDE.mdへ、担当特化のルールは各エージェント指示書へ、という書き分けが肝です。
役割を絞ると、副次的な効果もあります。指示書が短ければ、書き足したくなったときの改修コストが低い。「これはResearcherの範囲だな」「これはWriterに足すべき」と迷うことも減ります。ここは実運用してみて初めて実感した設計効果でした。
もう1つ、「サブエージェントは指示書のあるチームメイト」だと思うと、頭が整理しやすくなります。人間の組織で仕事を分担するのと発想は同じで、専門を絞る／責任範囲をはっきりさせる／自分の担当外は他の担当を信じる。これがAIエージェント分業の設計思想です。
ルールは"あとから足す"もの——失敗が指示書を育てた話
正直にお伝えしたいことがあります。CLAUDE.mdは、最初から今の姿だったわけではありません。動かしてみての結論は、最初から完璧な指示書は書けない、ということです。
序盤、こんな事故がありました。
エージェントに複数記事の一括修正を任せたら、「すべて修正完了しました」という報告が返ってきた。ところが翌日、確認のために本番のWordPressを開いてみると、修正が1件も反映されていなかった。エージェントは「実行したつもり」を報告していただけで、実データを見に行っていなかったのです。
このとき、対処療法として個別に修正を叩き直すこともできました。でも、それをやっても同じ事故が繰り返される。だから、根本の指示書に手を入れることにしました。追加したのは、「WordPress書き込み作業は、本番の記事本文をAPIで取り直して、狙った変更が入っているかgrepで確認するまで『完了』と報告しない」という1条です。以降、この事故は激減しました。
似た事故は他にもいくつもありました。同じ記事に2回続けて投稿してしまい下書きが二重に作られた件——ここから「投稿は最終版で1回だけ・追加修正は新規POSTではなくPATCH更新」というルールをCLAUDE.mdと関連ファイルに追加。既存の派生記事があるからと網羅性の高い基幹記事の執筆を諦めてしまう件——「基幹と派生は、意図・キーワード・記事タイプのいずれかが異なれば共存させてよい」という判断基準を追加。それぞれ、事故ごとに1条ずつ、指示書が厚くなっていきました。
こう並べてみて、CLAUDE.mdは失敗の墓標のようなものだ、と気づきます。事故が起きるたびに1条ずつルールが増え、そのたびに、次の事故への抵抗力が上がる。ルールは"最初から完璧に書く"ものではなく、"あとから足していく"もの。この考え方に切り替えてから、指示書と向き合うのが少し楽になりました。
裏を返せば、動かしてもいないうちから完璧な指示書を書こうとする必要はない、ということでもあります。動かしてみて、事故が出て、指示書を1行足す。この繰り返しでシステムは強くなる。設計は"完成品を目指す"のではなく、"育てるもの"です。この感覚は、AIエージェントに限らず、自動化を組む人みんなに共有したい話です。
まとめ
CLAUDE.mdに共通ルールを集約し、サブエージェントに役割を絞る。この2つが「1コマンドで動く」を裏で支えている設計の骨組みでした。そして、その指示書は最初から完璧なものではなく、失敗と対処のたびに1行ずつ育っていくものです。「設計は育てるもの」というマインドセットを、この章でいちばん持ち帰っていただけたら嬉しいです。
次章（第4章）では、パイプラインの終端にある「WordPress自動投稿」の実装を掘り下げていきます。REST APIをどう叩き、どう認証し、どのように下書きを送り、投稿後の実データをどう検証するか——書き終えた原稿がWordPressの下書きになるまでの道筋を、体験ベースでお伝えします。
なお、この章で触れたCLAUDE.mdの完全版・各サブエージェント指示書一式・具体的な設定値については、シリーズがひととおり出そろったところで、まとめて別途公開する予定です。動く形で手元に置きたい方は、その段になったらまた見に来てください。
