Monorepo 如何設計巢狀 AGENTS.md
了解如何以根目錄與服務專屬的巢狀 AGENTS.md 管理 Monorepo,避免過時規則、衝突指示與無效的 context;Codex 預設上限為 32 KiB。
在 Monorepo 中巢狀 AGENTS.md 的含義
在 Monorepo 中,巢狀 AGENTS.md 代表在儲存庫根目錄放置一個小型檔案,並在每個服務目錄內各放置一個檔案。根目錄檔案包含適用於全域的少數規則,以及指向其他檔案位置的對應表。每個服務檔案則僅包含該目錄專屬的指令與慣例。當代理程式編輯 services/worker/queue.py 時,它會讀取根目錄檔案與該工作目錄的檔案,完全不會耗費任何與前端相關的上下文,因為它永遠不會觸及前端。
此機制無需安裝任何軟體。AGENTS.md 是一種慣例,上游專案對此說明得非常清楚:
AGENTS.md 僅是標準的 Markdown 檔案。您可以使用任何標題;代理程式會直接解析您提供的文字。
這正是此技術值得深入學習的原因。其格式不會隨意變更。真正會出問題的是檔案的放置與維護,而這些皆屬於您的職責。
為什麼一份大型根目錄 AGENTS.md 會失效?
在同時包含 Web 應用程式、背景 worker 與 Terraform 目錄的 repository 根目錄放置一份 600 行的 AGENTS.md,會產生 4 個問題。
它會逐漸過時,因為沒有人負責維護。 在 apps/web 中重新命名測試 script 的工程師,實際上是在編輯 apps/web 下的檔案。根目錄的 AGENTS.md 不在該次 diff 中,因此 reviewer 不會看到不一致之處。6 週後,該檔案仍描述已不存在的建置步驟,而造成問題的人早已忘記當時的修改。
每項工作都會消耗 context。 這些檔案會在工作階段開始時載入,早於 agent 知道你要提出的要求。Claude Code 的文件提供了明確數字:「每個 CLAUDE.md 檔案的目標應少於 200 行。檔案越長,消耗的 context 越多,遵循程度也越低。」當指令檔案的合計大小達到 32 KiB(預設值 project_doc_max_bytes)時,Codex 會停止合併更多指令檔案。根目錄檔案若記錄 4 個服務,每項工作都會把 context 預算花在其中 3 個服務上。
指令會開始互相矛盾。 Web 目錄需要 pnpm test。worker 需要 pytest -q。將這些內容寫在同一份檔案中時,每項規則只在部分情況下正確,因此 agent 必須猜測目前適用哪一項。Claude Code 的文件說明了結果:「如果兩項指令互相矛盾,Claude 可能會任意選擇其中一項。」拆分檔案也不會讓其他規則排除在 context 外。Claude Code 會串接所有已載入的指令檔案,而不是讓其中一份取代另一份。因此根目錄檔案始終存在;當 agent 開啟 apps/web 與 services/worker 中的檔案後,兩個目錄檔案也會同時存在於 context 中。目錄層級檔案的作用,是將每項規則繫結到其所管理的目錄。請在檔案頂端標示目錄名稱,就像下方範例對 # apps/web 所做的一樣。即使同時載入多份檔案,每項指令仍會說明其適用位置。如果你確定已清楚寫出規則,卻仍然被跳過,先釐清指令始終未生效的原因,會比第 4 次重寫措辭更有效。
它會塞滿 agent 可直接從程式碼讀取的資訊。 例如目錄樹、相依套件清單,以及各套件功能的摘要。Claude Code 的 /doctor 檢查正是為了移除這些內容。它會「刪除 Claude 可從 codebase 推導出的內容,例如目錄配置、相依套件清單與架構概觀」,並保留「工具預設值不同的陷阱、理由與慣例」。這句話是我所知道判斷某行內容是否應該放進檔案的最佳標準。
代理程式會讀取 root 檔案,還是只讀取最近的檔案?
這是多數人最容易誤解模型的地方,因此值得引用上游慣例,而不是自行改寫:
在每個套件中再放置一個 AGENTS.md。代理程式會自動讀取目錄樹中最近的檔案,因此最近的檔案優先,每個子專案都能提供量身打造的指示。
關於衝突:
距離遭編輯檔案最近的 AGENTS.md 優先;明確的使用者聊天提示則優先於所有內容。
對許多人而言,「優先」看起來像是「忽略 root 檔案」。實際上並非如此。在實作此慣例的工具中,會讀取從 repository root 到工作目錄路徑上的每個檔案,並將內容合併。只有在兩個檔案對同一主題提出不同要求時,最近的檔案才會優先。
Codex 明確說明其機制:「Codex 會從 root 開始串接檔案,並以空白行分隔。距離目前目錄較近的檔案會覆寫較早的指示。」Claude Code 也會沿著相同路徑處理。工作階段開始時,它會讀取「工作目錄及其上層目錄中的每個 AGENTS.md 和 .claude/AGENTS.md」,其文件也清楚說明載入模型:「所有找到的檔案都會串接到 context 中,而不是彼此覆寫。」工作目錄以下的目錄則有所不同:Claude Code 會在需要時載入子目錄的 AGENTS.md,也就是「當 Claude 使用 Read tool 開啟該處的檔案時」。
這會帶來兩項實務上的影響。root 檔案會成為 repository 中每個工作階段的前綴,因此其中每一行都應視為每週要重複支付一百次的成本。目錄層級檔案只有在代理程式開啟該目錄中的檔案後才會產生成本,因此詳細內容適合放在該處。
這項行為已於 27 October 2026 對照 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、消費者必須保持冪等性的原因,以及測試通過前必須執行的遷移。infra 檔案則用來撰寫防止 agent 造成損害的規則。絕對不要執行 terraform apply。執行 terraform plan 後就停止,並指出已設定的狀態後端,避免 agent 嘗試初始化新的狀態後端。
請注意,這些檔案都沒有包含各服務用途的說明。這部分應由人員負責。上游專案也劃分了相同界線,指出「README.md 檔案供人員使用:快速入門、專案說明及貢獻指南」,而 AGENTS.md 則包含「程式碼 agent 所需的額外且有時相當詳細的內容:建置步驟、測試及慣例。」AGENTS.md 與面向人員的 README 之間的區分逐句說明這條界線,而記錄程式碼設計原因的 DESIGN.md則涵蓋第三個檔案;該檔案說明決策,而不是指令。
當程式碼變更時,由誰負責更新檔案?
規則只有一條,且必須寫在根目錄檔案中:任何變更目錄內程式碼的人,都必須在同一次 commit 中更新該目錄的 AGENTS.md。
這項規則是基於技術層面的考量,而非文化因素。該目錄下的檔案與程式碼位於同一個 diff 中,因此 Pull Request 的審核者能同時檢視兩者。根目錄檔案屬於所有人,這意味著它不屬於任何人,且永遠不會出現在審核者正在閱讀的 diff 中。
請在 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 client 但未更新文件的分支上,輸出結果如下:
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")"
doneapps/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 秒的檢查而言,這樣就已經足夠。
尋找已不存在的路徑。 文件最常見的腐化方式,是持續描述已刪除的程式碼。這些檔案中的每個路徑都寫在反引號內,因此很容易擷取並測試。
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,因為兩者都包含斜線,而且都不是磁碟上的檔案。在 Claude Code v2.1.283 或更新版本中,/doctor prompt-audit 會替你執行類似的檢查:它會尋找「指向不存在檔案或命令的參照」,以及彼此矛盾的檔案;預設涵蓋你的 AGENTS.md 檔案,而且除非你要求套用它提出的修改,否則不會變更任何內容。
工作階段中的徵兆。 代理程式讀取檔案後,因檔案指示而嘗試開啟 src/api/client.ts,但工具回傳:
No such file or directory因此它採取合理做法,自行撰寫 fetch wrapper。這就是過時檔案的實際成本。代理程式並沒有忽略你的文件,而是遵循文件內容,抵達 3 個月前已刪除的路徑,接著重新建立你已經擁有的程式碼。使用 Ponytail 會要求代理程式只進行能解決問題的最小修改 之類的 skill,可以降低這種重建傾向,但它無法找到檔案指向錯誤位置的 helper。
Claude Code 會讀取 AGENTS.md 檔案嗎?
會。從 Claude Code v2.1.277 開始支援,而且確切規則很重要,因為巢狀檔案的配置取決於此。根據 2026 年 10 月 27 日查閱的文件:「Claude Code 可將 AGENTS.md 讀取為專案指示,因此已針對其他 coding agents 設定的 repository,無須新增 CLAUDE.md、import 或設定即可運作。」預設的 Project instructions 值 claude-md-or-agents-md 會讀取「當工作目錄及其上層沒有 CLAUDE.md 或 CLAUDE.local.md 時的 AGENTS.md 檔案」。巢狀檔案也適用:只要「該子目錄本身沒有三個 CLAUDE.md 檔案中的任何一個」,Claude 就會「在使用 Read tool 開啟該處檔案時」讀取子目錄的 AGENTS.md。這三個檔案是 CLAUDE.md、.claude/CLAUDE.md 和 CLAUDE.local.md,因此只要在 apps/web 放置個人 CLAUDE.local.md,就足以阻止載入 apps/web/AGENTS.md。
這使得過去將 CLAUDE.md 放在每個 AGENTS.md 旁邊的建議變成陷阱。如果工作目錄及其上層有 AGENTS.md,以及 CLAUDE.md 或 CLAUDE.local.md,文件表示 Claude 只會讀取「你的 CLAUDE.md 檔案」。.claude/CLAUDE.md 也以相同方式計算。根目錄的一個附屬檔案若只包含一行 Claude 專用設定,就會隱藏路徑上的所有 AGENTS.md;個人 CLAUDE.local.md 也會產生相同效果。若要保留其中一個,請輸入 /config,並將 Project instructions 設為 claude-md-and-agents-md;此設定會同時讀取兩者,先讀取各目錄的 CLAUDE.md,再讀取其 AGENTS.md。
單靠版本號碼無法確認設定已生效。你需要 v2.1.277 或更新版本,但在 v2.1.281 之前,某些工作階段(例如使用 Amazon Bedrock 或停用 telemetry 的工作階段)只會讀取 CLAUDE.md 檔案;此外,從 v2.1.276 或更早版本升級後的第一個工作階段,在某些情況下也會略過 AGENTS.md:文件表示「Claude 會從你的下一個工作階段開始讀取 AGENTS.md」。因此請檢查工作階段本身。在互動式工作階段中,Claude Code 會列印類似 no CLAUDE.md found; AGENTS.md loaded: 的行,後面接著路徑;目前版本的 /memory 會列出該檔案。在 v2.1.280 之前,/memory 和 /context 不會列出 Claude 直接讀取的 AGENTS.md,因此這些版本應直接詢問 Claude 其專案指示內容。
當 Claude 無法直接讀取 AGENTS.md 時,import 形式仍然適用:包括舊版本、在 Amazon Bedrock 或停用 telemetry 時使用 v2.1.281 之前版本的工作階段、停用內建讀取 plugin 的工作階段,或保留 CLAUDE.md 且將 Project instructions 設為 claude-md 的專案。請將以下內容放入 services/worker/CLAUDE.md:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.當不需要加入任何工具專用設定時,symlink 形式較適合。
git ls-files '*AGENTS.md' | while read -r f; do
ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.mdln 成功時不會輸出任何內容,因此請檢查清單:apps/web/CLAUDE.md -> AGENTS.md。接著啟動工作階段並執行 /context,載入的檔案會出現在 Memory files 下。在 Windows 上建立 symlink 需要 Administrator 權限或 Developer Mode;此外,除非啟用 core.symlinks,否則 Git 會將已提交的 symlink 以純文字檔案取出,導致該 clone 以一行 CLAUDE.md 取代你的指示。如果 repository 的使用者包含 Windows 使用者,請改用 @AGENTS.md import。如果你在 Claude Code 自行讀取 AGENTS.md 之前就設定了任一替代方案,可以保留該設定:文件表示保留 import「不會讓 Claude 重複讀取 AGENTS.md」,而 symlink 形式的 CLAUDE.md 也只會讀取一次。
還有一個相關陷阱。在 /compact 之後,專案根目錄的 CLAUDE.md 會從磁碟重新讀取,但子目錄中的巢狀檔案不會重新注入。Claude Code 會按需重新載入它們,也就是 agent 下次處理該目錄中的檔案時才會載入。文件對 CLAUDE.md 檔案明確說明了這點,但沒有另外描述直接讀取 AGENTS.md 時的 compaction,因此預期這兩種名稱的巢狀檔案都會採用相同方式。如果每個目錄的規則在長時間工作階段中途似乎停止套用,通常就是這個原因;讀取該目錄中的任何檔案即可重新載入規則。
讓其他 agents 使用 AGENTS.md 的設定
Codex 原生讀取 AGENTS.md。它會在每一層先檢查 AGENTS.override.md,讓單一目錄可以在不修改共用檔案的情況下使用本地覆寫。合併內容達到 32 KiB(預設的 project_doc_max_bytes)後就會停止,因此這也是根目錄檔案應保持精簡的原因之一。
Aider 透過 .aider.conf.yml 使用該檔案,並加入 read: AGENTS.md 這一行。
Gemini CLI 透過 .gemini/settings.json 使用該檔案,並搭配 { "context": { "fileName": "AGENTS.md" } }。
Upstream 文件提供了向後相容的重新命名方式,適用於仍使用較早單數名稱的 repository:mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md。
在非常大型的 monorepo 中,Claude Code 的 claudeMdExcludes 設定可依路徑或 glob 略過祖先檔案;當其他團隊的目錄位於你的目錄上層時,這項設定很有用。其模式同樣適用於 Claude Code 讀取的 AGENTS.md 檔案。
這與代理記憶體(agent memory)或技能(skill)有何不同?
這些機制看起來很相似,但失效的方式完全不同,因此必須精確區分您當下需要的是哪一種。
AGENTS.md 由您編寫、提交至 git、通過 pull request 審核,且對於所有複製儲存庫的人來說都是一樣的。代理記憶體則由代理程式自行寫入、儲存於儲存庫之外,且僅限於單一機器。Claude Code 的文件劃分了相同的界線:CLAUDE.md 存放您編寫的「指令與規則」,自動記憶體存放 Claude 自行學習的「經驗與模式」,且記憶體目錄不會在不同機器間共享。判斷標準很簡單:如果某個事實對於剛複製儲存庫的同事來說必須成立,它就不能存放在記憶體中。代理記憶體如何在工作階段間持久化 涵蓋了這部分內容。
技能(skill)是第三種機制。AGENTS.md 是每個工作階段都會載入的上下文;而技能則是僅在需要時才載入的程序。Claude Code 文件提供了一個實用的規則:「如果條目是多步驟程序,或僅與程式碼庫的某個部分有關,請將其移至技能或路徑範圍內的規則。」該句的後半部分正是巢狀 AGENTS.md 所解決的問題。前半部分則是 代理技能 的用途;當多個儲存庫需要相同的程序時,請 跨儲存庫共享技能,而不是將相同的段落複製貼上到十個不同的 AGENTS.md 檔案中。
上游文件指出:「撰寫本文時,主要的 OpenAI 儲存庫擁有 88 個 AGENTS.md 檔案」。這個數字就是最好的證明。大型儲存庫不需要更大的檔案,而是需要更多的小型檔案,每個檔案都放置在它所描述的程式碼旁邊,並由最後修改該程式碼的人負責維護。
FAQ
巢狀的 AGENTS.md 會取代根目錄檔案,還是附加在其上?
會附加在其上。上游文件所說的「以最接近的檔案為優先」,描述的是發生衝突時的處理方式,而不是載入哪些檔案。Codex「會從根目錄往下串接檔案,並以空白行連接」,Claude Code 則會從工作目錄向上搜尋,串接找到的每個檔案,而不是互相取代。只有在兩個檔案對同一主題提供不同指示時,才由最接近的檔案優先處理。在根目錄集中撰寫共用規則,不要在每個目錄重複這些規則。
根目錄的 AGENTS.md 應該多大?
應小到讓你不介意它被貼在該 repository 中每個請求的前面,因為實際上就是如此。Claude Code 文件建議每個檔案控制在 200 行以下,並警告較長的檔案會「降低遵循程度」。Codex 預設會在合併的指示檔案總大小達到 32 KiB 時停止。如果根目錄檔案記錄了四個服務,對任何單一工作而言,其中大部分都是無用內容。將詳細資訊移到各目錄的檔案中,並在根目錄留下索引。
如何避免這些檔案內容過時?
在根目錄檔案中加入一項規則:凡是在某個目錄修改程式碼的人,都必須在同一個 commit 更新該目錄的 AGENTS.md。將檔案放在程式碼旁邊,規則才容易持續生效,因為這樣變更會出現在人員原本就會檢視的同一個 pull request diff 中。加入 CI 警告,將每個變更路徑對應到其上方最近的 AGENTS.md;並定期比較每個檔案上的 git log -1 --format=%cs 與在其所記錄目錄上執行相同 command 的結果。
Claude Code 會讀取 AGENTS.md 檔案嗎?
會,從 v2.1.277 開始。根據 2026 年 10 月 27 日查閱的文件,當工作目錄或其上層沒有 CLAUDE.md 或 CLAUDE.local.md 時,Claude Code 預設會讀取 AGENTS.md;當它使用 Read tool 開啟子目錄中的檔案,且該子目錄沒有自己的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 時,會讀取該子目錄的 AGENTS.md。不要在每個 AGENTS.md 旁邊都加入 CLAUDE.md:只要工作目錄或其上層有一個,Claude 就會讀取「只有你的 CLAUDE.md 檔案」。如果也需要 CLAUDE.md,請在 /config 中將 Project instructions 設為 claude-md-and-agents-md,或在其第一行加入 @AGENTS.md。在工作階段中執行 /memory,確認 AGENTS.md 路徑出現在清單中。
只在某些情況下適用的規則應該放在哪裡?
不要放在 AGENTS.md。該檔案會在每個工作階段載入,因此其中每一行都會與你實際輸入的請求競爭注意力。偶爾才需要、且包含多個步驟的程序,應放在 skill 中,並在需要時載入。只適用於某個目錄的規則,應放在該目錄的 AGENTS.md 中。代理程式可以直接從程式碼讀取的資訊,例如目錄樹或相依性清單,兩者都不應放入。