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，读取失败信息，然后尝试其他命令。每个尝试都会消耗令牌。将正确命令写下来，可以一次性消除整类错误。

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

文件放置位置和优先级

将第一个文件放在仓库根目录。在单体仓库中，您可以在每个子项目内添加更多文件。规则很简单：“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；读取前请先询问。”更广泛的规范请参阅避免让代理接触凭据。

代理通过查看即可推断出的内容，不要写入。粘贴目录列表、复制依赖项列表、重复列出文件夹名称的架构概览：这些内容在写入后一周就可能过时，同时还会在每次会话中占用上下文。保留陷阱及其原因。删除清单。

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 出现在记忆文件下方。如果该文件不在列表中，说明它从未加载，其中的内容也未生效。要生成初稿而不是手动编写文件，请运行 /init：它会读取代码库并生成起始文件；如果 CLAUDE.md 已存在，则会建议改进内容，而不是覆盖文件。

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

有一点需要特别强调。AGENTS.md 是指导信息，不是权限系统。其内容会作为普通上下文传入，因此模型会读取并通常遵循它，但它不会阻止违反该指导的操作。对于必须始终满足的规则（例如“绝不推送到 main”），应使用 hook 或权限设置，因为它们以代码形式运行，不依赖模型自行决定是否遵守。

自动为您写入这些文件的工具

GitHub 趋势榜上 30 July 2026 的两个项目展示了这一约定的发展方向。

agent0ai/dox（截至 July 2026 获得 1,368 个 stars）是一个用于维护 AGENTS.md 文件树的框架。它不提供 package，也不需要 runtime。您只需将其 AGENTS.md 的内容复制到自己的根目录 AGENTS.md 中，即可完成安装。对于已经存在的项目，您可以这样告诉 agent：

Initialize DOX tree for this project now.

随后，agent 会创建子级 AGENTS.md 文件及其索引，在编辑任何内容前遍历该文件树，并在变更完成后更新受影响的文档。其核心假设是：agent 在工作过程中顺带维护的文档会保持准确，而由人员手动更新的文档则不会。

HUMAN.md：将同一方法应用于您本人

Intuition-Lab/personal-model（截至2026年7月获得1,260个 stars）将这一模式应用于个人，而不是代码仓库。该项目将您的 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 中，或放在项目根目录下被 gitignore 忽略的 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.

先写下来，然后直接在原处修正。添加一行的信号是：您在聊天中对同一处内容进行了两次相同的修正。这条规则可以让文件保持实用，也能避免文件不断膨胀成无人阅读的文档，包括机器在内。内容稳定后，它会随仓库一起保存；当 agent 在您的笔记本以外的位置运行时，这一点尤其重要：在您自己的服务器上运行 coding agent 介绍了相关设置。

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 吗？

应该，凡是项目相关且长期有效的内容都应提交，例如构建命令、目录结构和约定。该文件的作用就是让团队成员的代理从相同的上下文开始工作。个人内容或特定于某台计算机的内容应放在单独的 gitignored 文件中，凭据不应放在这两类文件中。

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

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