【ITニュース解説】One Repo, Two Rulebooks: Nested AGENTS.md for Codex, Subfolder CLAUDE.md for Claude Code

システムエンジニアを目指す初心者の皆さんが、AIを活用した開発ツールを効果的に使うための重要な知識を解説する。CodexやClaude CodeのようなAIエージェントはコード生成や修正を助けるが、モノレポ（複数のプロジェクトを一つのリポジトリで管理する環境）では、AIが意図しないファイルを編集したり、プロジェクトの固有ルールを無視したりする問題が起こることがある。これは、AIがどのルールを、いつ、どのように読み込むかという仕組みがエージェントによって異なるために発生する。

この問題を解決するためには、各プロジェクトやサービスごとに専用のルールブックを用意し、AIエージェントがそれらを正しく読み込むように設定することが不可欠だ。具体的には、リポジトリのルートディレクトリに全体に適用される共通ルールを置き、各アプリケーションやサービスのディレクトリにはそれぞれの固有ルールを記述したファイルを作成する。例えば、以下のような構成が考えられる。

acme/
  AGENTS.md  # リポジトリ全体の共通ルール
  CLAUDE.md  # @AGENTS.md （CLAUDE向けにAGENTS.mdをインポート）
  apps/web/
    AGENTS.md  # フロントエンド固有のルール
    CLAUDE.md  # @AGENTS.md
  services/api/
    AGENTS.md  # バックエンド固有のルール
    CLAUDE.md  # @AGENTS.md

AGENTS.mdはCodexを含む多くのAIツールで使われるルールファイル形式で、実際の指示内容が記述される。CLAUDE.mdはClaude Codeが読み込むファイルだが、@AGENTS.mdという記述を持つことが多い。これは、CLAUDE.mdがAGENTS.mdの内容をインポートすることで、CodexとClaude Codeの両方が同じルールセットを参照できるようにするための工夫だ。ルールファイルには、「コミットメッセージはパッケージ名で始める」「秘密情報をコミットしない」といった共通ルールや、「テストはVitestを使う」「自動生成されたコードは編集しない」といった各パッケージ固有のルールが記述される。AIが処理できるルールファイルの合計サイズには上限があるため、各ファイルは簡潔に保つべきだ。

次に、各AIエージェントがこれらのルールファイルをどのように読み込むかを見ていこう。

Codexの場合、ルールファイルはAGENTS.mdが使われる。読み込み順序は、まずユーザーのホームディレクトリにあるグローバル設定ファイルが読み込まれる。次に、プロジェクトのルートディレクトリから、ユーザーがCodexを起動した現在のディレクトリまでのすべてのディレクトリが順に探索され、各ディレクトリでAGENTS.md（または一時的な上書き用のAGENTS.override.md）が読み込まれる。ここで重要なのは、Codexをどのディレクトリで起動するかによって、読み込まれるルールセットが変わるという点だ。例えば、フロントエンドの作業をする場合は、apps/webディレクトリに移動してからCodexを起動する（codex --cd apps/web）。これにより、ルートとapps/webのAGENTS.mdが読み込まれ、バックエンドのルールは含まれない。後から読み込まれたルールは、以前のルールと競合した場合には優先される。AGENTS.override.mdは、一時的なルール変更が必要な場合に、そのディレクトリの通常のAGENTS.mdを完全に置き換える形で機能する。

一方、Claude Codeの場合、ルールファイルは主にCLAUDE.mdが使われるが、特定のバージョンからはAGENTS.mdも読み込める。Claude Codeのルール読み込みには二つのタイミングがある。一つはAIエージェントの起動時で、作業ディレクトリとその上位ディレクトリにあるCLAUDE.mdが読み込まれる。もう一つは、Claude Codeがサブディレクトリ内のファイルを触る際に、そのサブディレクトリのCLAUDE.mdを「オンデマンド」で読み込むという点だ。この仕組みにより、モノレポのルートでClaude Codeを起動しても、後からフロントエンドのファイルを触ったときにフロントエンド固有のルールが自動的に読み込まれる。先述の@AGENTS.mdという記述は、CLAUDE.mdがAGENTS.mdの内容をインポートするために使われ、これによりCodexとClaude Codeで共通のルールセットを利用できるようになる。ただし、Codexが使うAGENTS.override.mdはClaude Codeでは読み込まれないため、両方のAIエージェントに共通で適用したい一時的なルール変更がある場合は、共有のAGENTS.mdを直接編集する必要がある。

AIエージェントが意図したルールを正しく読み込んでいるかを確認することも非常に重要だ。Codexの場合、codex debug prompt-inputコマンドを実行すると、AIモデルに渡されるプロンプト入力（ルールブックの内容を含む）をJSON形式で確認できる。Claude Codeの場合、セッション中に/contextコマンドを実行すると、起動時に読み込まれたルールファイルの一覧（Memory files）が表示される。オンデマンドで読み込まれたサブフォルダのCLAUDE.mdは、そのサブフォルダ内のファイルをAIが触ると読み込まれる。

AIエージェントに与えるルールブックは、あくまで「ガイダンス」であり、AIが常にその指示に強制的に従うわけではないという点を理解しておく必要がある。例えば、「src/generated/ディレクトリ内のファイルを編集してはならない」というルールをAGENTS.mdに記述しても、AIが誤ってそのファイルを編集しようとすることがある。このような場合は、ルールブックでの説明に加えて、より強力なメカニズムで特定の操作をブロックする必要がある。Claude Codeでは、.claude/settings.jsonファイルにpermissions設定を追加し、denyルールを使って特定のディレクトリへの編集操作を禁止できる（例："deny": ["Edit(./**/generated/**/*)"]）。これにより、AIがsrc/generated/以下のファイルを編集しようとするのを物理的に阻止できる。Codexにも同様に、セッションの承認ポリシーや書き込み可能なルートを設定する機能がある。

筆者が開発するHermes IDEというツールは、このようなAIエージェントをサイドバイサイドで実行できる開発環境を提供している。これは、CodexやClaude Codeに加えて他のAIコーディングツールを一つのリポジトリ内で連携させながら利用することを可能にする。Hermes IDEは、プロジェクト新規作成時にAGENTS.mdファイルを自動で生成したり、Gitのワークツリー機能を利用して、コミットされていない個人用のルールファイルを各開発タスクの環境にコピーしたりする機能も備えている。

このように、AIエージェントを活用した開発では、ルールブックを適切に配置し、AIエージェントの読み込み挙動を理解し、必要に応じて強力なアクセス制限を設定することが、効率的で安全な開発を進める上で非常に重要だ。新しいルールを追加したり、AIエージェントのバージョンをアップグレードしたりする際には、必ずこれらのルールが正しく機能しているかを確認する習慣を身につけるべきだ。AIエージェントの能力を最大限に引き出しつつ、開発プロセスを安定させるために、これらの知識はシステムエンジニアを目指す皆さんにとって不可欠なものとなる。