モノレポのAGENTS.mdをネストする構成と書き方

モノレポでネストした AGENTS.md が意味すること

モノレポでネストした AGENTS.md を使う場合、リポジトリのルートに小さなファイルを 1 つ置き、各サービスディレクトリ内にもう 1 つずつファイルを置きます。ルートのファイルには、全体に適用される少数のルールと、ほかのファイルの配置場所を示すマップを記載します。各サービスのファイルには、そのディレクトリだけで使うコマンドと規約を記載します。エージェントが services/worker/queue.py を編集するときは、ルートのファイルと worker のファイルを読み取ります。編集しないフロントエンドの情報にコンテキストを使うことはありません。

インストールするものはありません。AGENTS.md は規約であり、upstream project も明確にそう説明しています。

AGENTS.md は標準的な Markdown にすぎません。見出しは自由に使用できます。エージェントは、提供されたテキストをそのまま解析します。

この手法を正しく学ぶ価値があるのは、そのためです。形式が途中で変わることはありません。問題になるのは配置と保守であり、どちらも担当するのはあなたです。

大きな root AGENTS.md 1 つでは、なぜ機能しなくなるのか？

Web アプリケーション、バックグラウンドワーカー、Terraform ディレクトリを含むリポジトリのルートに、600 行の AGENTS.md 1 つだけを置くと、4 つの問題が起きます。

管理者がいないため、内容が古くなります。 apps/web にあるテストスクリプトの名前を変更したエンジニアは、apps/web 配下のファイルを編集しています。ルートの AGENTS.md はその差分に含まれないため、レビュアーは不整合に気付きません。6 週間後には、存在しないビルド手順が記載されたままになり、変更を行った本人もそのことを忘れています。

タスクのたびにコンテキストを消費します。 これらのファイルは、エージェントが依頼内容を知る前のセッション開始時に読み込まれます。Claude Code のドキュメントには、具体的な目安として「各 CLAUDE.md ファイルは 200 行未満を目標にすること。長いファイルはより多くのコンテキストを消費し、指示への準拠度を下げる」とあります。Codex は、指示ファイルの合計サイズが 32 KiB（デフォルトの project_doc_max_bytes）に達すると、以降のファイルを結合しなくなります。4 つのサービスを説明するルートファイルでは、各タスクでそのうち 3 つ分の内容に予算を使うことになります。

指示同士が矛盾し始めます。 Web ディレクトリでは pnpm test が必要です。ワーカーでは pytest -q が必要です。1 つのファイルにまとめると、各ルールが正しいのは一部の状況だけになるため、エージェントはどのルールを適用すべきか推測しなければなりません。Claude Code のドキュメントでは、その結果を「2 つの指示が矛盾すると、Claude は任意に一方を選ぶことがある」と説明しています。ディレクトリ単位のファイルに分ければ、2 つのルールが同時にコンテキストへ入ることはないため、推測が不要になります。明確に書いたはずのルールが無視される場合は、文言を 4 回目に書き直すよりも、指示が反映されない理由を確認する方が有効です。

エージェントがコードから読み取れる事実で埋まります。 ディレクトリツリー、依存関係の一覧、各パッケージの概要などです。Claude Code の /doctor チェックは、まさにこれらを取り除くためにあります。このチェックは、「ディレクトリ構成、依存関係の一覧、アーキテクチャの概要など、Claude がコードベースから導出できる内容を削除」し、「落とし穴、理由、ツールのデフォルトと異なる規約」を残します。この一文は、ある行をファイルに記載すべきかどうかを判断する最良の基準です。

エージェントは root のファイルを読みますか。それとも最も近いファイルだけを読みますか。

ここは多くの人がモデルを誤解する部分です。そのため、言い換えではなく、上流の慣例を引用します。

各パッケージ内に別の AGENTS.md を配置します。エージェントはディレクトリツリー内で最も近いファイルを自動的に読み込むため、最も近いファイルが優先され、各サブプロジェクトで固有の指示を指定できます。

競合については、次のように説明されています。

編集対象ファイルに最も近い AGENTS.md が優先されます。明示的なユーザーのチャットプロンプトは、すべての指示より優先されます。

「優先される」と聞くと、「root のファイルは無視される」と考える人が多くいます。しかし、そうではありません。この慣例を実装するツールでは、リポジトリの root から作業ディレクトリまでのパス上にあるすべてのファイルを読み込み、それらを結合します。最も近いファイルが優先されるのは、同じ項目について異なる指示がある場合だけです。

Codex はこの仕組みを明確に説明しています。「Codex は root から順にファイルを連結し、空行で区切ります。現在のディレクトリに近いファイルほど、先に読み込まれた指示を上書きします」。Claude Code も同じパスをたどります。セッション開始時に、「作業ディレクトリとその上位ディレクトリにあるすべての AGENTS.md と .claude/AGENTS.md」を読み込みます。また、読み込みモデルについても、「検出されたすべてのファイルは、互いに上書きするのではなく、コンテキストに連結される」と明記しています。作業ディレクトリより下位のディレクトリは異なります。Claude Code は、そのサブディレクトリにある AGENTS.md を、「Read ツールでその場所のファイルを開いたとき」にオンデマンドで読み込みます。

ここから、実務上の重要な点が 2 つ導かれます。root のファイルはリポジトリ内のすべてのセッションに付加されるため、そこに書く各行は、週に 100 回読むコストが発生するものとして扱います。一方、ディレクトリごとのファイルは、エージェントが別の場所で作業している間はコストになりません。そのため、詳細な指示はそこに置くのが適しています。

この動作は、2026 年 10 月 12 日に Codex と Claude Code のドキュメントで確認しました。ツールによって実装は多少異なり、変更されることもあります。そのため、チームで使用するエージェントの読み込み規則を確認してください。

リポジトリに3つのサービスを配置する例

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

ルートのファイルは意図的に短くします。参照先を示し、すべてのディレクトリに適用されるルールだけを記載します。

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

ディレクトリごとのファイルに詳細を記載します。内容は、そのディレクトリに必要な分だけ長くできます。

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

worker のファイルも同じ構成ですが、内容は異なります。インストールコマンド、pytest -q、consumer を冪等に保つ必要がある理由、テストを通過させる前に実行する必要があるマイグレーションを記載します。infra のファイルには、agent による破壊的な操作を防ぐルールを記載します。terraform apply は絶対に実行しないでください。terraform plan だけを実行して終了し、すでに設定済みの state backend の名前も記載します。これにより、agent が新しい state backend を初期化しようとするのを防げます。

これらのファイルのどれにも、各サービスの用途の説明はありません。これは人間向けの情報です。Upstream も同じ線引きを示しており、「README.md files are for humans: quick starts, project descriptions, and contribution guidelines」とし、AGENTS.md には「the extra, sometimes detailed context coding agents need: build steps, tests, and conventions」を記載すると説明しています。AGENTS.md と人間向け README の使い分けでは、この境界を文ごとに説明しています。また、コードの構成理由を記録する DESIGN.mdでは、コマンドではなく設計上の判断を説明する3つ目のファイルを扱います。

コードが変更されたとき、誰がファイルを更新するのか

ルールは1つだけです。root ファイルに記載します。あるディレクトリ内のコードを変更した人は、同じコミットで、そのディレクトリの AGENTS.md も更新します。

これは文化的な理由ではなく、機械的な理由で機能します。ディレクトリごとのファイルはコードと同じ差分に含まれるため、pull request のレビュー担当者は両方を同時に確認できます。root ファイルは全員のものです。そのため、実質的には誰のものでもなく、誰かがすでに確認している差分に含まれることもありません。

pull request のチェックでこのルールを適用します。変更された各ファイルについて、上位にある最も近い AGENTS.md を検出し、そのファイルが変更されていなければ報告します。

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

ドキュメントを変更せずに API クライアントを作り直したブランチでは、出力は次のようになります。

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

失敗ではなく警告にします。厳格なゲートにすると、CI を成功させるために空行を追加するだけの対応を促します。ロボットを満たすためだけに編集されたファイルは、ファイルが存在しない場合よりも価値がありません。警告があれば、レビュー担当者は確認すべき質問を投げかけられます。実際に機能するのは、その点です。

古くなった AGENTS.md を見つけるには

今日すぐ実行できる確認方法が2つあります。セッション中に現れる兆候も1つあります。

各ファイルの更新時期を、そのファイルが説明するコードの更新時期と比較します。 %cs はコミット日時を YYYY-MM-DD として出力します。

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done

apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

ドキュメントの日付がコードの日付より6か月遅れていても、そのファイルが誤っているとは限りません。最初に読むべきファイルが分かるだけです。1秒で終わる確認から得る情報としては、それで十分です。

現在存在しないパスを探します。 ドキュメントが劣化する具体的な形の1つは、削除済みのコードについて説明し続けることです。これらのファイル内のパスはすべてバッククォートで囲まれているため、簡単に抽出して確認できます。

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

この結果は読み取るだけにし、CI に組み込まないでください。src/**/*.ts のような glob や、引用した URL も検出されます。どちらにもスラッシュが含まれていますが、ディスク上のファイルではありません。

セッション中に現れる兆候。 エージェントがそのファイルを読み、ファイルの指示どおりに src/api/client.ts を開こうとすると、ツールは次を返します。

No such file or directory

そのため、エージェントは妥当な対応として独自の fetch ラッパーを作成します。これが、古くなったファイルによる実際のコストです。エージェントはドキュメントを無視しているのではありません。ドキュメントに従った結果、3か月前に削除されたパスへ到達し、すでに存在するコードを再構築してしまいます。エージェントに機能する最小限の変更を徹底させる Ponytail のようなスキルを使えば、この再構築の傾向は減らせます。ただし、ファイルが誤った場所を指している場合、そのヘルパーを見つけることはできません。

Claude Code は AGENTS.md ファイルを読み込みますか？

はい。Claude Code v2.1.277 以降で読み込みます。ネストした構成は正確なルールに依存するため、この点が重要です。2026年10月12日にドキュメントを確認しました。そこには「Claude Code は AGENTS.md をプロジェクトの指示として読み込むため、他のコーディングエージェント用に設定済みのリポジトリでも、CLAUDE.md、import、設定を追加せずに動作します」とあります。既定の Project instructions の値である claude-md-or-agents-md は、「作業ディレクトリまたはその上位に CLAUDE.md または CLAUDE.local.md がない場合に、AGENTS.md ファイルを読み込む」という意味です。ネストしたファイルも対象です。Claude は、サブディレクトリに独自の CLAUDE.md がない場合、そのサブディレクトリで Read tool によってファイルを開いたときに AGENTS.md を読み込みます。

このため、各 AGENTS.md の横に CLAUDE.md を置くという従来のアドバイスは問題になります。作業ディレクトリまたはその上位に AGENTS.md と CLAUDE.md または CLAUDE.local.md がある場合、ドキュメントでは「CLAUDE.md ファイルのみを読み込む」と説明されています。ルートに Claude 専用の行を1つだけ記載したコンパニオンファイルを置くと、パス上にあるすべての AGENTS.md が隠れます。個人用の CLAUDE.local.md でも同じです。1つ残したい場合は /config を入力し、Project instructions を claude-md-and-agents-md に設定します。これにより両方が読み込まれ、各ディレクトリの CLAUDE.md が先に、その後に AGENTS.md が読み込まれます。

動作を確認するには、claude --version を実行し、v2.1.277 以降であることを確認します。対話セッションでは、Claude Code が no CLAUDE.md found; AGENTS.md loaded: のような行と、その後にパスを表示します。/memory にはファイルが一覧表示されます。

Claude が AGENTS.md を直接読み込めない場合は、import 形式が適しています。たとえば、古いバージョンを使用している場合、組み込みの読み込みプラグインが無効になっているセッション、または Project instructions を claude-md に設定した CLAUDE.md を使用するプロジェクトが該当します。services/worker/CLAUDE.md に次の内容を記述します。

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

ツール固有の追加設定が不要な場合は、シンボリックリンク形式が適しています。

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln は成功時に何も表示しないため、apps/web/CLAUDE.md -> AGENTS.md で一覧を確認します。その後、セッションを開始して /context を実行すると、読み込まれたファイルが Memory files の下に表示されます。Windows ではシンボリックリンクの作成に Administrator 権限または Developer Mode が必要です。そのため、Windows では代わりに @AGENTS.md import を使用します。Claude Code が AGENTS.md を自動的に読み込む前にどちらかの回避策を設定していた場合も、そのまま残して構いません。ドキュメントによると、import を残しても「Claude が AGENTS.md を2回読み込むことはありません」。シンボリックリンクされた CLAUDE.md も1回だけ読み込まれます。

これに関連する注意点が1つあります。/compact の後、プロジェクトルートの CLAUDE.md はディスクから再読み込みされますが、サブディレクトリ内のネストしたファイルは再注入されません。Claude Code は、エージェントがそのディレクトリ内のファイルを次に扱うとき、必要に応じて再読み込みします。ドキュメントではこの動作を CLAUDE.md ファイルについて説明していますが、直接読み込まれた AGENTS.md について compaction 時の動作は個別に説明していません。そのため、どちらの名前のネストしたファイルも同じように動作すると考えてください。長いセッションの途中でディレクトリごとのルールが適用されなくなったように見える場合、通常はこれが原因です。そのディレクトリ内のファイルを1つ読み込むと、ルールが再び読み込まれます。

エージェントメモリや skill との違いは何ですか？

これらの仕組みは似て見えますが、失敗する理由は大きく異なります。どの仕組みを使うべきか、正確に判断することが重要です。

AGENTS.md はユーザーが作成し、git にコミットして、pull request でレビューします。リポジトリを clone する全員に対して同一です。エージェントメモリはエージェントが作成し、リポジトリの外部に保存され、1 台のマシン内でのみ利用されます。Claude Code のドキュメントでも同じ区別が示されています。CLAUDE.md にはユーザーが記述する「Instructions and rules」が含まれ、自動メモリには Claude が記述する「Learnings and patterns」が含まれます。メモリディレクトリはマシン間で共有されません。判断基準は簡単です。新しい clone を使う同僚にも真である必要がある事実は、メモリに保存できません。セッション間でエージェントメモリを保持する方法では、この仕組みの一側面を説明しています。

skill は 3 つ目の仕組みです。AGENTS.md は毎回のセッションで読み込まれるコンテキストです。一方、skill は必要になったときに読み込まれる手順です。Claude Code のドキュメントには、実用的な判断基準があります。「項目が複数の手順からなる場合、またはコードベースの一部にしか関係しない場合は、skill またはパス単位のルールに移してください」。この文の後半が、ネストした AGENTS.md で解決できる内容です。前半が エージェントの skill の用途です。同じ手順を複数のリポジトリで使う場合は、同じ段落を 10 個の AGENTS.md に貼り付けるのではなく、リポジトリ間で skill を共有するべきです。

Upstream には、「執筆時点で、OpenAI のメインリポジトリには AGENTS.md ファイルが 88 個あります」と記載されています。この数字が主張全体を示しています。大規模なリポジトリに必要なのは、より大きなファイルではありません。必要なのは、より多くの小さなファイルです。それぞれが説明対象のコードの隣に置かれ、そのコードを最後に変更した担当者が管理します。

FAQ

入れ子にした AGENTS.md はルートのファイルを置き換えますか、それとも追加されますか？

追加されます。Upstream の「最も近いファイルが優先される」という説明は、競合時の動作を示したものであり、読み込まれる内容を示したものではありません。Codex はルートから下方向へファイルを連結し、空行で区切ります。Claude Code も、上位ディレクトリから作業ディレクトリまでたどって見つけたすべてのファイルを連結し、上書きはしません。同じ対象について異なる指示がある場合に限り、最も近いファイルの内容が優先されます。共有ルールはルートに一度だけ書き、各ディレクトリで繰り返さないでください。

ルートの AGENTS.md はどの程度の大きさにすべきですか？

そのリポジトリで行うすべてのリクエストの先頭に貼り付けられても気にならない程度に小さくしてください。実際にそのように処理されるためです。Claude Code のドキュメントでは、1 ファイルあたり 200 行未満を目標にすることを推奨し、長いファイルは「遵守率を下げる」と警告しています。Codex は、結合後のサイズがデフォルトで 32 KiB に達すると命令ファイルのマージを停止します。ルートファイルで4つのサービスを説明している場合、1つのタスクにとって大半は不要な情報です。詳細はディレクトリごとのファイルへ移し、ルートには構成を示す案内だけを残してください。

これらのファイルが古くならないようにするにはどうすればよいですか？

ルートファイルに、次のルールを1つ追加してください。あるディレクトリのコードを変更した人は、同じコミットでそのディレクトリの AGENTS.md も更新します。コードの隣にファイルを置くと、このルールを守りやすくなります。変更が、人間がすでに確認している同じ pull request の差分に含まれるためです。変更された各パスを、その上位にある最も近い AGENTS.md に対応付ける CI 警告を追加してください。また、各ファイルの git log -1 --format=%cs と、そのファイルが説明するディレクトリで同じコマンドを実行した結果を、定期的に比較してください。

Claude Code は AGENTS.md ファイルを読み込みますか？

はい。v2.1.277 以降が対象です。2026年10月12日時点のドキュメントで確認したところ、作業ディレクトリまたはその上位に CLAUDE.md も CLAUDE.local.md もない場合、Claude Code はデフォルトで AGENTS.md を読み込みます。また、Read tool でサブディレクトリ内のファイルを開くと、そのサブディレクトリの AGENTS.md を読み込みます。各 AGENTS.md の横に CLAUDE.md を追加しないでください。作業ディレクトリと同じ階層か上位に1つあれば、Claude は「Your CLAUDE.md files only」を読み込みます。CLAUDE.md も必要な場合は、/config の Project instructions を claude-md-and-agents-md に設定するか、先頭行に @AGENTS.md を記述してください。セッションで /memory を実行し、一覧に AGENTS.md のパスが表示されることを確認します。

ときどきしか必要にならないルールはどこに置けばよいですか？

AGENTS.md には置かないでください。このファイルはすべてのセッションで読み込まれるため、記述した各行が、実際に入力したリクエストと注意を奪い合うことになります。複数の手順から成り、ときどき必要になる処理は、必要なときに読み込まれる skill に置きます。1つのディレクトリにだけ適用されるルールは、そのディレクトリの AGENTS.md に置きます。ディレクトリツリーや依存関係の一覧のように、エージェントがコードから直接読み取れる情報は、どちらにも置きません。