私のリポジトリのCLAUDE.mdは、1行しかありません。中身は @AGENTS.md だけ、ファイルサイズにして11バイトです。それでも複数のAIエージェントを日常的に回す運用が成立しています。CLAUDE.mdの書き方について私がたどり着いた結論は2つで、「指示書はAGENTS.mdに1本化してCLAUDE.mdは参照だけにする」「破られては困るルールは指示書に書き込まず、コードに逃がす」です。この記事では、その構成に至った理由と実際のレイアウトを解説します。
対象読者は、Claude Codeを使い始めてCLAUDE.mdに何を書けばいいか迷っている人、そしてCLAUDE.mdが肥大化して「書いたのに守られない」状態に悩み始めた人です。SNS運用の自動化システムを複数エージェントで動かしている実際のリポジトリ構成を例にします。
CLAUDE.mdは何をするファイルか
まず前提の整理から。CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込む指示ファイルです。プロジェクトのルートに置けばそのリポジトリでの作業すべてに効き、ホームディレクトリ側（~/.claude/CLAUDE.md）に置けば自分の全プロジェクトに効きます。ビルドコマンド、コーディング規約、やってほしくないこと。毎回プロンプトで伝えていた内容を、ここに書いておくと省略できます。
もう1つ重要な仕様が、@パス によるインポートです。CLAUDE.mdの中に @AGENTS.md のように書くと、そのファイルの内容が指示として読み込まれます。これは私の両リポジトリで実際に使っている挙動です。CLAUDE.mdを運用の起点に置く考え方自体は、Anthropic公式のベストプラクティス記事でも扱われています。
ここまでは公式情報どおりです。問題は、この便利なファイルが運用の中でどう崩れていくかです。
指示書は増殖する
私の環境では、同じリポジトリをClaude Codeだけが触るわけではありません。定時実行のRoutine、Claude Desktop、そしてCodex。エージェントごとに指示ファイルの置き場が違うと、同じルールを複数の場所に書くことになります。
これをやると何が起きるか。指示書がドリフトします。 片方だけ更新して、もう片方が古いまま。どちらが正か分からなくなった指示書は、書いてあっても信用されなくなり、結局チャットで毎回補足する運用に逆戻りします。
この問題への業界側の回答が、AGENTS.mdという共通フォーマットです。「READMEのエージェント版」として、ツールを問わずコーディングエージェントが読む前提の指示ファイルを1つ置く、というオープンな規約で、対応エージェントの一覧も公開されています。
AGENTS.md - A simple, open format for guiding coding agentsAGENTS.md is a simple, open format for guiding coding agents, used by over 60k open-source projects. Think of it as a README for agents.agents.md
そこで私のリポジトリでは、指示の本体をAGENTS.mdに置き、CLAUDE.mdは次の1行だけにしました。
@AGENTS.md
Claude CodeはCLAUDE.md経由でAGENTS.mdを読み、AGENTS.mdを直接読むエージェントはそのまま読む。どのエージェントから見ても正が1つになり、更新箇所も1つになります。私はこの構成を2つのリポジトリ（自動化システム本体と、コンテンツ管理リポジトリ）で運用していますが、正が1つなので指示の二重管理がそもそも発生しません。
何を書くか: 実際のAGENTS.mdの中身
1本化したAGENTS.mdの本体には何を書くべきか。私の自動化システム側のAGENTS.mdは約13KBで、見出しを要約するとこうなります。
- 目的と投稿軸（このシステムは何のために動いているか）
- 自動運用の原則（レビューの通し方、失敗時の隔離ルール）
- 公開文のポリシー（文体、書いてはいけない表現）
- データ境界（どのDBをどのツールで読み書きするか）
- 公開回数の制限（1日あたりの上限）
- 憲法層と可変層（後述）
- Gitと検証（ブランチ規約、完了前チェック）
- 公開前レビューのチェックリスト
共通するのは、「判断に迷ったとき何を正とするか」を決めるための情報だという点です。コマンド、規約、境界、優先順位。逆に、手順の詳細は書いていません。手順はスキルや個別のドキュメントに分離し、AGENTS.mdからはファイル名で参照します。指示書は法律で、手順書はマニュアル。この分離をしないと、AGENTS.mdは際限なく伸びます。
書き方のスタイルとして効いていると感じるのは次の3点です。
- 禁止事項は理由ではなく境界で書く。「なるべく〜しない」ではなく「
mainへ直接pushしない」「facts.mdに無い自社情報を書かない」のように、守れたか判定できる形にする - 参照で薄く保つ。詳細仕様は「
docs/notion-schema.md記載の固定IDを使う」のように参照先だけ書く - エージェントに触らせたくないファイルを明示する。私の場合は「憲法層」として専用の節でリストを宣言しています
書けば書くほど、守られなくなる
ここが今日一番伝えたい話です。エージェントの想定外の動きを見つけるたびに指示書へ禁止事項を1行足していく運用は、自然にやりがちですが、続けるとある性質にぶつかります。指示書は書けば書くほど、1行あたりの重みが下がる。
指示ファイルは毎セッション、モデルのコンテキストに載ります。長くなるほど個々のルールは埋もれ、私の体感では、長いセッションの終盤ほど細かい指示から順に効かなくなっていきます。これはモデルの欠陥というより、散文で書かれたルールというものの性質です。人間のチームでも、100条ある社内規程を全部覚えて仕事をする人はいません。
つまりCLAUDE.md／AGENTS.mdの設計問題は「何を書くか」ではなく、**「何を書かないで済むようにするか」**でした。ここで発想を変えて、ルールを2種類に分けました。
- 破られても直せるルール: 文体、構成の好み、命名。散文で指示書に書く
- 破られては困るルール: 本番への公開、
mainへの直接push、機密ファイルへのアクセス。指示書に書くのをやめて、コードで強制する
強制はコードに逃がす
「破られては困るルール」の逃がし先は、Claude Codeでは主に2つあります。
1つ目はsettings.jsonの権限設定です。ツールごと・コマンドごとに許可/拒否を宣言でき、そもそも実行させない選択ができます。
2つ目がhooksです。ツール実行の前後に任意のスクリプトを差し込める仕組みで、私のリポジトリでは2つ使っています。
- PreToolUse: Bashコマンドを実行前にガードスクリプトへ通し、禁止パターン（
mainへの直接push、デプロイやSecrets変更、環境変数ファイルの表示など）に一致したらブロックする - Stop: エージェントが作業を終えるタイミングで
npm run checkを強制実行し、検証を通さずに終われないようにする
この構成のポイントは、ガードの内容をAGENTS.mdに書き写さないことです。指示書には「hooksが強制する」という事実と憲法層の一覧だけを書き、パターンの実体はスクリプト側に持たせます。ルールが増えても指示書は伸びません。hooksの実装詳細は別記事にまとめてあります。
Claude Codeのhooksで自動運用に禁止ラインを引く｜Bashガード実装記録Claude Codeのhooksで、エージェントに破らせたくない操作をコードとして強制する実装記録。PreToolUseフックの設定、Bashコマンドを検査するガードスクリプト、exit code 2でブロックする仕組み、正規表現ルールの設計と限界まで、実運用中の構成をそのまま解説します。www.tentspace.net
さらにもう1段、憲法層と可変層という分離を入れています。AGENTS.md自体、hooks、権限設定、レビュー基準は「憲法層」で、エージェントは変更を提案できてもマージは人間だけが行う。一方でスキルの手順や文体ガイドは「可変層」で、根拠付きならエージェント自身が改善PRを出せる。指示書の中に「この指示書を誰が変えられるか」を書いておくと、自動運用でも指示書が勝手に書き換えられる事故を構造的に防げます。
運用してみて分かった目安
この構成で複数エージェントの運用を回してきた実感を、チェックリストとしてまとめます。
- CLAUDE.mdは参照1行。指示の本体はAGENTS.mdへ。複数エージェントを使う予定がなくても、標準フォーマット側に寄せておいて損はありません
- AGENTS.mdに書くのは判断基準と境界。手順の詳細はスキルやdocsへ分離し、参照で繋ぐ
- 「絶対に守らせたい」と感じたら、それは書く場所が違うサイン。settings.jsonの権限かhooksへ
- 禁止事項は判定可能な形で書く。「気をつける」系の指示は書いても機能しません
- 指示書の変更権限を指示書に書く。自動運用するなら憲法層/可変層の分離はセットで
CLAUDE.mdの書き方を調べると「充実させましょう」という方向の情報が多いのですが、私の結論は逆でした。指示書は薄く、正は1つ、強制はコード。エージェントが増えるほど、この3つが効いてきます。