AGENTS.md 与 HUMAN.md：编码代理指南

AGENTS.md 是什么

AGENTS.md 是位于代码仓库根目录中的普通 Markdown 文件，用于告诉编码代理如何处理该项目。官方网站将其描述为“供代理使用的 README：为提供上下文和说明设立的专用、固定位置，帮助 AI 编码代理处理项目”。该格式由 Linux Foundation 旗下的 Agentic AI Foundation 维护。截至 2026 年 7 月，已有 20 多个代理会读取它，包括 Codex、Cursor、Jules、Devin 和 GitHub Copilot。

这一约定的存在有实际原因。团队新成员会阅读 README，猜测构建命令；猜错后，再向其他人询问。代理无法提问。它会在使用 pnpm test 的项目中猜测并运行 npm test，读取失败信息，然后尝试其他命令。每消耗一个 token，都需要付费。将正确命令写下来，可以一次性消除这一类失败。

没有必填字段。官方网站对此有明确说明：“AGENTS.md 只是标准 Markdown。您可以使用任意标题；代理只会解析您提供的文本。”这就是全部规范。它的价值不在格式，而在于文件位于每个工具都会查找的路径中。

文件放在哪里，以及哪个文件优先

将第一个文件放在仓库根目录。在 monorepo 中，可以在每个子项目内继续添加文件。规则很简单：“agents 会自动读取目录树中距离当前目录最近的文件，因此最近的文件优先。”两个文件发生冲突时，以正在编辑的文件所在层级为准；而您在聊天中输入的内容会覆盖这两个文件。

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

嵌套布局值得采用，因为只有这样才能表达某条规则在一个目录中成立、在下一级目录中不成立。例如，“每个 endpoint 都要验证输入”应放在 endpoint 旁边。若放在根目录文件中，它会在每个无关任务中加载，却没有任何作用。如果根目录文件已经为每个服务增加了一个小节，拆分为嵌套布局就是解决方案；其中会说明哪些规则应下移，哪些规则应保留在顶层。

AGENTS.md 中应包含的内容

记录代理无法通过阅读代码自行确定的信息。先写出确切的构建、测试和 lint 命令，格式应能直接粘贴到终端中执行。还要添加运行单个测试的命令，因为只知道如何运行完整测试套件的代理，可能会把完整测试套件运行 40 次。说明不同于工具默认值的约定，因为代理已经了解默认行为，只需要知道你的偏离规则。如果有提交消息格式和拉取请求规则，也应一并写明。

内容应具体到可以检查。例如，“使用 2 个空格缩进”是可执行的指令，因为可以确认是否遵守。 “正确格式化代码”则不是，因为无法验证其中的具体要求。位置说明也一样：“API 处理程序位于 src/api/handlers/”比“保持文件组织有序”更有效。

负面规则同样值得占用篇幅。“绝不编辑 dist/ 下的文件，这些文件由 npm run build 生成”可以阻止一种具体错误。由于规则说明了原因，代理也能推断出未明确写出的等效情况。范围规则也应放在这里，因为如果让代理自行判断，它可能会重写超出请求范围的内容：一个被广泛复制的技能只坚持采用能够奏效的最小改动。

哪些内容不应写入其中

绝不要将机密写入这些文件。这些文件会提交到 git，在每次会话开始时加载到上下文中，并在每次请求时发送给模型提供商。将 API 密钥写入 AGENTS.md，就意味着该密钥会出现在您的仓库历史记录和第三方日志中。应指向机密所在位置，而不是直接粘贴机密：“数据库密码位于 .env 中，该文件已加入 gitignore；读取前请先询问。”更广泛的规范见让凭据不落入代理可访问范围。

省略代理通过查看即可推导出的内容。粘贴目录列表、复制依赖项列表，或编写一份只是重复目录名称的架构概览：这些内容在写完一周后就会过时，但此后每次会话都会占用上下文。保留陷阱及其原因。删除清单。原因值得单独说明，因为如果代理看不出某种不寻常结构存在的原因，就会悄悄将其重构掉；在此文件旁放置 DESIGN.md就是这种情况。

CLAUDE.md 是同一理念在 Claude Code 中的实现

Claude Code 会读取 CLAUDE.md，但不会自行读取 AGENTS.md。项目文件位于 ./CLAUDE.md 或 ./.claude/CLAUDE.md，所有项目通用的个人偏好放在 ~/.claude/CLAUDE.md，组织可以在 Linux 上将机器级文件推送到 /etc/claude-code/CLAUDE.md。发现的文件会按照从文件系统根目录到工作目录的顺序串联，因此距离启动会话位置最近的文件最后读取。您在该目录中启动的每个会话都会加载相同的文件栈，因此可以在一台机器上并行运行两个会话，这些会话还可以在运行期间相互交接工作。

如果代码仓库中已经有 AGENTS.md，请不要维护第二份副本。导入现有文件，然后只添加 Claude 特有的内容：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

如果没有其他内容需要添加，可以使用符号链接：

ln -s AGENTS.md CLAUDE.md

命令成功时不会输出任何内容。在下一次会话中运行 /context，确认 CLAUDE.md 出现在 Memory files 下。如果该文件不在列表中，说明它从未加载，因此其中的内容没有生效。若要生成初稿而不是手动编写，请运行 /init：该命令会读取代码库并生成一个起始文件；如果 CLAUDE.md 已存在，它会提出改进建议，而不会覆盖原文件。

每个文件应控制在约 200 行以内。文件过长会占用更多上下文窗口，遵循程度也会下降。如果您想了解还有哪些内容会占用这部分空间，请参阅代理的上下文窗口实际包含哪些内容，其中有详细说明。

有一点需要特别强调。AGENTS.md 是指导文件，不是权限系统。其内容会作为普通上下文提供给模型，因此模型通常会读取并遵循，但它不会阻止与该文件相矛盾的操作。当您编写的规则被悄悄跳过且无法判断原因时，请先了解指令被丢弃的原因，再第三次重写措辞。对于每次都必须遵守的规则，例如“绝不推送到 main”，请使用 hook 或权限设置，因为它们以代码方式运行，不依赖模型自行决定是否遵守。

为您生成这些文件的工具

GitHub 趋势榜上 2026 年 7 月 30 日的两个项目，展示了这一约定的发展方向。

agent0ai/dox（截至 2026 年 7 月有 1,368 个 star）是一个用于维护 AGENTS.md 文件树的框架。它不发布软件包，也不需要运行时。将其 AGENTS.md 的内容复制到您自己的根目录 AGENTS.md 中，即可完成安装。对于已经存在的项目，您可以这样告诉代理：

Initialize DOX tree for this project now.

随后，代理会创建子目录中的 AGENTS.md 文件及其索引，在编辑任何内容前遍历这棵文件树，并在变更完成后更新受影响的文档。它背后的判断是：代理在工作过程中顺带维护的文档会保持准确，而由人工手动更新的文档则不会。

HUMAN.md：将同一思路用于您本人

Intuition-Lab/personal-model（截至 2026 年 7 月获得 1,260 个 star）将这一模式应用于个人，而不是代码仓库。该项目将您的 HUMAN.md 定义为系统的输出，而不是您手动编写的文件：“记录当前真正重要的事项、您通常如何做决策，以及您的注意力正转向哪里的一份动态模型。”它可在 macOS 13 或更高版本本地运行。获得 macOS 授权后，它会记录活动，并通过 MCP（模型上下文协议）将结果提供给代理。简要安装步骤如下：

uv tool install personal-model
persome onboard
persome model open --after 30

要获得大部分收益，您不需要这些功能。手写的 HUMAN.md 大约只有 20 行，包括您的角色、时区、实际使用的技术栈、已经做出且不希望重新讨论的决策，以及您希望获得多少解释。它可以减少反复说明的需要，其作用与项目文件相同，只是应用在更上一层。

需要注意一点。HUMAN.md 是个人资料，因此本质上包含敏感信息。不要将它放入公共代码仓库。将它放在 ~/.claude/CLAUDE.md 中，或放在项目根目录下被 git 忽略的 CLAUDE.local.md 中；该文件会与已提交的文件一起加载，并按相同方式处理。

可复制的起始模板

模板有意保持简短。删除不适用的部分，不要添加无法持续维护的内容。

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

先写下来，再直接在文件中修正。当你在聊天中对同一处内容进行了第2次相同的修正，就应将其添加为一行。这个规则可以让文件保持实用，也能避免文件不断膨胀，最终变成没人阅读、机器也无法读取的文档。文件稳定后，将其随代码仓库一起保存。当代理在你的笔记本之外运行时，这一点尤其重要：在自己的服务器上运行编码代理介绍了相关配置。

FAQ

AGENTS.md 与 CLAUDE.md 是同一个文件吗？

它们是同一种思路，只是文件名不同。Claude Code 会读取 CLAUDE.md，除非将两者关联，否则会忽略 AGENTS.md。保留一个文件作为唯一事实来源，并将另一个文件链接到它。可以在 CLAUDE.md 顶部添加一行 @AGENTS.md，也可以使用 ln -s AGENTS.md CLAUDE.md。分别维护两份完整副本后，它们通常会在一个月内出现不一致。

编写 AGENTS.md 能保证代理遵守其中的内容吗？

不能。文件内容会作为上下文传递给模型，因此模型会读取并通常遵守这些内容，但不会阻止违反这些内容的操作。模糊的指令最不可靠。如果两个文件提供相反的指导，代理只能任意选择其中一个。对于必须始终生效的规则，应使用 hook 或权限规则。无论模型如何决定，这些规则都会由客户端强制执行。

是否应将 AGENTS.md 提交到 git？

应当提交项目相关的内容，例如构建命令、目录结构和约定。该文件的作用就在于此：团队成员的代理启动时可以获得与你的代理相同的上下文。个人信息或特定于某台机器的内容应放在单独的 gitignore 文件中，凭据不应放入这两类文件中的任何一个。

HUMAN.md 是什么？我需要创建它吗？

HUMAN.md 是面向个人的机器可读配置文件，而不是项目配置文件。它记录你的角色、约束条件以及已经确定的决策，避免每次会话重新讨论这些内容。开始使用不需要任何工具：在用户级指令文件中手写 20 行内容，就能获得大部分价值。应将其视为个人数据，不要将它放入要推送的任何代码仓库中。