SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 更新于 2026-10-28

单体仓库如何设计嵌套 AGENTS.md 文件

根目录 AGENTS.md 容易过时并浪费上下文。本文给出按服务拆分的嵌套布局,涵盖 200 行建议、32 KiB 限制及规则冲突问题。

单体仓库中的嵌套 AGENTS.md 含义

单体仓库中的嵌套 AGENTS.md,指的是在仓库根目录放置一个简短文件,并在每个服务目录中再放置一个文件。根目录文件包含适用于整个仓库的少量规则,以及其他文件所在位置的索引。每个服务目录中的文件只包含该目录适用的命令和约定。代理编辑 services/worker/queue.py 时,会先读取根目录文件和 worker 文件,不会将任何上下文用于它不会修改的前端。

无需安装任何内容。AGENTS.md 是一种约定,上游项目对此有明确说明:

AGENTS.md 只是标准 Markdown 文件。标题可以任意使用;代理只会解析您提供的文本。

因此,值得认真掌握这项技术。该格式不会悄然发生变化。真正容易出问题的是文件位置和维护方式,而这两项都需要由您负责。

为什么一个大型根目录 AGENTS.md 会逐渐失效?

一个包含 Web 应用、后台 worker 和 Terraform 目录的代码仓库,如果只在根目录放置一个 600 行的 AGENTS.md,会出现四类问题。

它会逐渐过时,因为没有明确的维护者。 在 apps/web 中重命名测试脚本的工程师,修改的是 apps/web 下的文件。根目录中的 AGENTS.md 不在这次 diff 中,因此没有审阅者会发现不一致。六周后,该文件仍在描述一个已经不存在的构建步骤,而造成问题的人也早已忘记了这次修改。

每项任务都会消耗上下文。 这些文件会在会话开始时加载,此时 agent 还不知道你要提出什么请求。Claude Code 的文档给出了一个具体标准:“每个 CLAUDE.md 文件最好少于 200 行。文件越长,消耗的上下文越多,遵循程度越低。”当合并后的指令文件总大小达到 32 KiB(默认值为 project_doc_max_bytes)时,Codex 会停止继续合并指令文件。根目录文件如果记录了四个服务的规则,那么每项任务都会为其中三个无关服务消耗上下文额度。

指令会开始互相矛盾。 Web 目录需要 pnpm test。worker 需要 pytest -q。把这些规则写进同一个文件后,每条规则只在部分情况下正确,因此 agent 必须猜测当前适用哪条规则。Claude Code 的文档描述了这一结果:“如果两条指令互相矛盾,Claude 可能会任意选择其中一条。”拆分文件并不会让其他规则完全脱离上下文。Claude Code 会拼接所有已加载的指令文件,而不是让一个文件替换另一个文件。因此根目录文件始终存在;当 agent 打开了 apps/web 和 services/worker 中的文件后,这两个目录的文件也会同时出现在上下文中。目录级文件的作用,是将每条规则绑定到它所管理的目录。在文件顶部写明目录名称,例如下面示例中的 # apps/web。这样,即使同时加载多个文件,每条命令仍会明确说明适用范围。当一条你确信已经写得很清楚的规则仍然被跳过时,先分析指令未生效的原因,比第四次重写措辞更有效。

它会塞入 agent 可以直接从代码中读取的信息。 例如目录树、依赖列表,以及每个 package 功能的摘要。Claude Code 的 /doctor 检查正是为了删除这类内容。它会“删除 Claude 可以从代码库推导出的内容,例如目录布局、依赖列表和架构概览”,并保留“工具默认值之外的陷阱、原因和约定”。这是我所知道的判断某一行是否应该保留在文件中的最佳标准。

Agent 会读取 root 文件,还是只读取最近的文件?

这里最容易被误解,因此值得直接引用上游约定,而不是转述:

在每个 package 中都放置一个 AGENTS.md。Agent 会自动读取目录树中最近的文件,因此最近的文件优先,每个子项目都可以提供针对性的说明。

关于冲突:

距离被编辑文件最近的 AGENTS.md 生效;用户在聊天中明确提供的提示优先级最高。

“优先”一词容易让人以为“root 文件会被忽略”。事实并非如此。在实现这一约定的工具中,root 到工作目录路径上的每个文件都会被读取,并拼接在一起。只有当两个文件针对同一主题给出不同说明时,最近的文件才优先。

Codex 明确说明了这一机制:“Codex 会从 root 开始拼接文件,并使用空行连接。距离当前目录越近的文件,越能覆盖之前的说明。”Claude Code 也会遍历相同的路径。会话开始时,它会读取“工作目录及其上级目录中的每个 AGENTS.md 和 .claude/AGENTS.md”,其文档也明确说明了加载模型:“所有发现的文件都会拼接到上下文中,而不是互相覆盖。”工作目录下方的目录行为不同:Claude Code 会按需加载子目录中的 AGENTS.md,也就是“当 Claude 使用 Read 工具打开该目录中的文件时”。

这会带来两个实际影响。root 文件是仓库中每个会话的前缀,因此其中的每一行都相当于每周要为一百次会话付费。目录级文件只有在 Agent 打开该目录中的文件后才会产生开销,因此详细说明适合放在那里。

我们已于 27 October 2026 对照 Codex 和 Claude Code 文档核实了这一行为。不同工具的实现略有差异,而且规则也会变化,因此应确认团队所使用 Agent 的加载规则。

包含 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 文件用于编写防止代理执行破坏性操作的规则。绝不要运行 terraform apply。只运行 terraform plan,然后停止,并写明已配置的状态后端,避免代理尝试初始化新的状态后端。

请注意,这些文件中都没有包含每个服务用途的说明。这部分内容应由人类维护。上游项目也作出了相同区分,说明“README.md 文件面向人类:快速入门、项目说明和贡献指南”,而 AGENTS.md 包含“编码代理所需的额外信息,有时还包括详细上下文:构建步骤、测试和约定”。AGENTS.md 与面向人类的 README 之间的划分逐句说明了这一边界;记录代码设计原因的 DESIGN.md介绍了第 3 个文件,即用于解释设计决策而非记录命令的文件。

代码发生变化时,谁来更新文件?

只需要一条规则,并将其写入根目录文件:谁修改了某个目录中的代码,谁就必须在同一个提交中更新该目录的 AGENTS.md。

这条规则依靠的是机械机制,而不是团队文化。目录级文件会与代码出现在同一个差异中,因此拉取请求的审阅者可以同时看到两者。根目录文件属于所有人,也就意味着没有人真正负责;而且它通常不会出现在任何人正在查看的差异中。

在拉取请求上增加检查来落实这条规则。该检查会查找每个已修改文件上方最近的 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?

您今天可以执行两项检查,还可以在会话中观察到一种症状。

比较每个文件的时间与其所描述代码的时间。 %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

文档日期比代码日期早六个月,并不能证明文件内容有误。它只能告诉您应先查看哪个文件,而这正是一项只需一秒即可完成的检查所需要提供的信息。

查找已经不存在的路径。 文档会以一种非常具体的方式逐渐失效:它继续描述已经删除的代码。这些文件中的每个路径都写在反引号中,因此很容易提取并进行测试。

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 文件,并且在您要求它应用所建议的修改之前不会更改任何内容。

会话中的症状。 agent 读取该文件,因为文件要求它这样做,于是尝试打开 src/api/client.ts,工具返回:

No such file or directory

于是它采取合理的做法,编写自己的 fetch 包装器。这就是过时文件的实际代价。agent 并没有忽略您的文档。它遵循文档,访问一个三个月前已删除的路径,然后重新构建您已经拥有的代码。像 Ponytail 这样的技能会让 agent 遵循能正常工作的最小改动 可以减少这种重建倾向,但如果文件将 agent 指向错误位置,它仍然无法找到那个辅助工具。

Claude Code 会读取 AGENTS.md 文件吗?

会。从 Claude Code v2.1.277 开始支持,而且确切规则很重要,因为嵌套布局取决于此。根据 2026 年 10 月 27 日查阅的文档:“Claude Code 可以将 AGENTS.md 作为项目说明,因此已经为其他编码代理设置好的仓库无需添加 CLAUDE.md、导入方式或设置即可工作。”默认的 Project instructions 值 claude-md-or-agents-md 会读取“当工作目录或其上方没有 CLAUDE.md 或 CLAUDE.local.md 时的项目 AGENTS.md 文件”。嵌套文件也适用:当 Claude 使用 Read 工具打开子目录中的文件时,会读取该子目录的 AGENTS.md,前提是“该子目录本身没有这三个 CLAUDE.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 上的会话或禁用遥测的会话)只会读取 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 时,导入方式仍然适用:旧版本;在 Amazon Bedrock 上或禁用遥测时的 v2.1.281 之前会话;禁用了读取该文件的内置插件的会话;或者使用 CLAUDE.md,并将 Project instructions 设置为 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 上创建符号链接需要管理员权限或开发者模式;如果未启用 core.symlinks,Git 会将已提交的符号链接检出为普通文本文件,导致该克隆中只剩一行 CLAUDE.md,而不是你的说明。如果任何克隆仓库并进行开发的人员使用 Windows,请使用 @AGENTS.md 导入方式。如果你在 Claude Code 自行读取 AGENTS.md 之前已经设置了任一变通方案,可以保留它:文档称保留导入“不会让 Claude 重复读取 AGENTS.md”,而符号链接形式的 CLAUDE.md 也只会读取一次。

还有一个相关陷阱。在 /compact 之后,项目根目录中的 CLAUDE.md 会从磁盘重新读取,但子目录中的嵌套文件不会重新注入。Claude Code 会按需重新加载这些文件,即代理下次处理该目录中的文件时才会加载。文档明确说明了 CLAUDE.md 文件的这一点,但没有单独描述直接读取的 AGENTS.md 在压缩上下文时的行为,因此应预期这两种名称的嵌套文件都遵循这一规则。如果每个目录的规则在长会话中途似乎停止生效,通常就是这个原因;读取该目录中的任意文件即可重新加载规则。

将其他代理指向 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" } }。

上游文档说明,对于仍使用旧单数名称的仓库,可以进行向后兼容的重命名: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,并在拉取请求中审核。任何克隆该仓库的人看到的内容都相同。agent memory 由 agent 编写,存储在仓库之外,并且只对一台机器有效。Claude Code 文档也作了相同区分:CLAUDE.md 保存由你编写的“Instructions and rules”,自动记忆保存由 Claude 编写的“Learnings and patterns”,而 memory 目录不会在不同机器之间共享。判断方法很简单:如果某个事实必须对刚完成克隆的同事也成立,就不能将它放入 memory。agent memory 如何在会话之间持久化介绍了这部分内容。

skill 是第三种机制。AGENTS.md 是每个会话都会加载的上下文;skill 是需要时才加载的操作流程。Claude Code 文档给出了一个实用规则:“如果某个条目是多步骤操作流程,或者只与代码库的一部分有关,就应将其移到 skill 或路径范围规则中。”这句话的后半部分正是嵌套 AGENTS.md 要解决的问题。前半部分则是 agent skills 的用途。如果同一个操作流程需要用于多个仓库,应当 在多个仓库之间共享 skill,而不是将相同段落复制到十个不同的 AGENTS.md 文件中。

上游说明:“截至本文撰写时,OpenAI 主仓库中有 88 个 AGENTS.md 文件。”这个数字本身就说明了问题。大型仓库不需要更大的文件,而需要更多小文件。每个文件都应放在所描述代码的旁边,并由最近修改该代码的人负责维护。

FAQ

嵌套的 AGENTS.md 会替换根目录文件,还是会追加到其中?

它会追加到其中。上游文档所说的“最近的文件优先”描述的是发生冲突时的处理方式,而不是加载方式。Codex“从根目录向下拼接文件,并用空行连接”,Claude Code 则会从工作目录向上遍历,拼接找到的每个文件,而不是覆盖这些文件。只有当两个文件针对同一主题给出不同指令时,最近的文件才会生效。将共享规则只写在根目录文件中,不要在每个目录中重复这些规则。

根目录的 AGENTS.md 应该有多大?

应小到即使每次在该仓库中发起请求时都将它粘贴到请求开头,你也不会介意,因为实际情况就是如此。Claude Code 文档建议每个文件控制在 200 行以内,并警告较长的文件会“降低遵循度”。Codex 默认在合并后的指令文件总大小达到 32 KiB 时停止继续合并。如果根目录文件记录了四个服务,那么其中大部分内容对任何单个任务都是无用负担。将详细内容下移到各目录的文件中,并在根目录文件中保留索引。

如何避免这些文件逐渐过时?

在根目录文件中加入一条规则:任何修改某目录中代码的人,都必须在同一次提交中更新该目录的 AGENTS.md。将文件放在代码旁边能让这条规则真正执行,因为这样修改会出现在人们本来就会查看的同一个 pull request 差异中。添加 CI 警告,将每个变更路径映射到其上方最近的 AGENTS.md,并定期对每个文件运行 git log -1 --format=%cs,再将输出与在该文件所记录目录上运行同一命令的输出进行比较。

Claude Code 会读取 AGENTS.md 文件吗?

会,从 v2.1.277 开始。根据 2026 年 10 月 27 日核对的文档,如果工作目录中或其上方没有 CLAUDE.md 或 CLAUDE.local.md,Claude Code 默认会读取 AGENTS.md;当它使用 Read 工具打开某个子目录中的文件,且该子目录本身没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时,它会读取该子目录的 AGENTS.md。不要在每个 AGENTS.md 旁边都添加 CLAUDE.md:只要在工作目录中或其上方有一个,Claude 就只会读取“Your CLAUDE.md files”。如果还需要 CLAUDE.md,请在 /config 中将 Project instructions 设置为 claude-md-and-agents-md,或在其第一行写入 @AGENTS.md。在会话中运行 /memory,确认列表中出现 AGENTS.md 路径。

只在某些时候适用的规则应该放在哪里?

不要放在 AGENTS.md 中。该文件会在每个会话中加载,因此其中的每一行都会与实际输入的请求争夺注意力。偶尔才需要的多步骤流程应放在 skill 中,由系统按需加载。只适用于某个目录的规则应放在该目录的 AGENTS.md 中。智能体可以直接从代码中读取的事实,例如目录树或依赖项列表,不应放在这两类文件中。

这篇文章对您有帮助吗?