Claude Codeを複数のプロジェクトで使っていると、プロジェクトごとのルールをどこに書くかで迷います。
CLAUDE.mdを置く方法は以前からありました。ですが、Claude CodeだけでなくCodexや他のエージェントでも共有したいルールまで、Claude Code専用ファイルに詰め込むのは少し違います。
Claude Code v2.1.277で、CLAUDE.mdがないプロジェクトではAGENTS.mdをプロジェクト指示として読むようになりました。今回は、この変更を実際のプロジェクト運用にどう使うかをまとめます。
AGENTS.mdはCLAUDE.mdの代わりに使えます
公式リリースノートの説明はシンプルです。プロジェクトにCLAUDE.mdがない場合、Claude CodeはAGENTS.mdを読みます。設定変更は/configの「Project instructions」から行えます。
ここで大事なのは、両方を同じ目的で置くことではありません。私は、エージェント全体で共有する作業ルールをAGENTS.mdに置き、Claude Codeだけの細かい補足が必要な時だけCLAUDE.mdを置く、という分け方がよいと思います。
最初にAGENTS.mdへ書くもの
最初から何でも書くと、指示ファイルが長くなって読みにくくなります。まずは次のような、エージェントが変わっても意味が変わらないルールから始めます。
- プロジェクトの目的と主要なディレクトリ
- テスト・ビルド・検証に使うコマンド
- 秘密情報を置いている場所と、読んではいけない場所
- 勝手に公開・削除・デプロイしてはいけない操作
- 作業終了時に残すログや引き継ぎ資料
たとえば、こんな入口にします。
# AGENTS.md
## このリポジトリ
- Chrome拡張と公開サイトを管理する
- 詳細な運用ルールは docs/loop/ を正本とする
## 作業前
1. README.mdを読む
2. docs/loop/STATE.mdで現在地を確認する
3. tools/secrets/は読まない
## 検証
- 拡張を変更したら npm test
- 公開URLはHTTPステータスと本文を確認する
この形なら、Claude Code以外のエージェントにも「何を確認してから作業するか」が伝わります。コマンドだけでなく、やってはいけないことまで書くのがポイントです。
Claude Codeだけの設定はCLAUDE.mdへ分ける
一方で、Claude Codeのスキルやスラッシュコマンド、Claude固有の作業パターンまでAGENTS.mdに入れると、他のエージェントには不要な情報が増えます。
Claude Codeでだけ使う作業手順があるなら、CLAUDE.mdへ分けます。共有ルールと製品固有のルールを分けておくと、別のエージェントを試す時に設定ファイルを作り直さずに済みます。
ただし、CLAUDE.mdが存在するとAGENTS.mdの代替読み込みは起きません。両方を置く場合は、どちらにも同じ指示を書いて二重管理しないように注意してください。
読み込みを確認してみましょう
では、空のテスト用ディレクトリで確認してみましょう。まずCLAUDE.mdを置かず、AGENTS.mdだけを作ります。
mkdir agents-md-check
cd agents-md-check
Set-Content AGENTS.md "このプロジェクトの合言葉は AGENTS_OK です"
claude
Claude Codeを起動したら、「プロジェクトの合言葉は何ですか」と聞きます。AGENTS_OKが返れば、プロジェクト指示として読み込まれています。
この確認は、指示ファイルの名前を変えた時にも便利です。読み込まれたと思い込まず、エージェント自身に短い確認質問をしてみてください。
複数エージェントで共有する時の注意です
AGENTS.mdに書けば、すべてのエージェントが同じ動きをするわけではありません。どの場所まで探索するか、同名ファイルが複数ある時にどうするか、細かい読み込み仕様は製品ごとに違います。
また、指示ファイルに秘密情報を書いてはいけません。APIキーやパスワードを直接書かず、環境変数や秘密管理の仕組みに渡してください。
私は、指示ファイルには「秘密情報の値」ではなく「秘密情報を読まない」という境界だけを書くようにしています。これ、意外と使えます。
まとめ
Claude Code v2.1.277では、CLAUDE.mdがないプロジェクトでAGENTS.mdをプロジェクト指示として使えるようになりました。
- エージェント共通のルールは
AGENTS.mdへ置く - Claude Code固有の補足は必要な時だけ
CLAUDE.mdへ置く - 両方を置くなら、同じ内容を二重管理しない
- 秘密情報の値や、勝手に実行してほしくない操作を書かない
複数のAIエージェントを使い分けるなら、最初に共有ルールの置き場所を決めておくと後が楽です。設定ファイルを毎回ゼロから作り直すより、共通部分を一枚にまとめておく方が安全ですね。
公式リリースノート: Claude Code v2.1.277
コメント