跳到正文
一AllOne
关注

工作流

项目说明文件（AGENTS.md / CLAUDE.md）怎么写

给编程 Agent 写一份项目说明文件，相当于给新同事一份入职手册。这篇讲清楚这类文件是什么、应该写什么不该写什么、怎么让一份文件同时服务多个工具，并附一份可以直接改的模板。

发布于 2026-10-22 · 最后核实：2026-10-22 · 文中价格与额度以各官网为准

每次开一个新会话，编程 Agent 对你的项目都是一无所知的：不知道用哪个命令跑测试，不知道你们约定的代码风格，不知道哪个目录绝对不能碰。于是你只好在每次对话开头重复一遍——或者忘了说，然后看着它犯同样的错。

项目说明文件就是为了解决这个问题。它是放在仓库里的一份 Markdown 文件，Agent 每次开始工作前会自动读取。不同工具对它的叫法不同：

  • AGENTS.md：一个开放格式，官网 agents.md 把它定位为「写给 Agent 的 README」。Codex、Cursor、GitHub Copilot 的编程 Agent、OpenCode、Windsurf（即 Devin Desktop）等许多工具都支持读取它。
  • CLAUDE.md：Claude Code 的项目说明文件。按 Claude Code 文档的说明，它也可以读取仓库里的 AGENTS.md。
  • 还有一些工具有自己的规则文件或目录，比如 Cursor 的 .cursor/rules、Copilot 的 .github/copilot-instructions.md。

结论先说：用 AGENTS.md 作为唯一的「主文件」，写清楚命令、结构、风格和边界；控制在一两百行以内；需要特定工具的文件时，让它引用或指向主文件，而不是复制一份。

它和 README 有什么区别

README 是写给人看的：项目介绍、快速上手、贡献指南。AGENTS.md 是写给 Agent 看的：那些对人类贡献者来说太琐碎、但 Agent 必须知道才能干好活的细节。agents.md 官网的说明是，这样分开能让 README 保持简洁，同时给 Agent 一个固定、可预期的地方去找指令。

一个好的判断标准：这条信息是「新同事第一天入职时你会口头叮嘱的」吗？ 是，就写进去。

应该写什么

GitHub 分析了 2500 多个仓库里的 Agent 说明文件，发现效果最好的文件都覆盖了六个方面。这可以直接当作你的目录：

  1. 命令：安装依赖、启动开发服务器、构建、测试、代码检查的完整命令，带上参数。放在文件最前面，Agent 会反复用到。
  2. 测试：用什么测试框架、测试文件放在哪、怎么只跑一个测试、提交前必须通过什么。
  3. 项目结构：关键目录各放什么。不需要逐个文件介绍，几行就够。
  4. 代码风格：和默认习惯不同的约定。GitHub 的建议是：一段真实的代码示例，胜过三段文字描述。
  5. Git 工作流：分支命名、提交信息格式、提交前要做什么。
  6. 边界：哪些东西不能碰。GitHub 发现「绝不提交密钥」是最常见也最有用的一条约束。

还要写具体：说「React 18 + TypeScript + Vite + Tailwind CSS」，而不是「一个 React 项目」。

不该写什么

Claude Code 的官方最佳实践给了一个很好用的筛选问题：「删掉这一行，Agent 会不会因此犯错？」不会，就删掉。 文件越长，每一条被遵守的概率越低——Claude Code 文档建议每个文件控制在 200 行以内，太长的文件会占用更多上下文、降低遵守程度。

以下内容不建议写进去：

  • Agent 读代码就能自己弄明白的东西；
  • 语言的通用规范（它本来就知道）；
  • 大段 API 文档（放一个链接即可）；
  • 经常变化的信息；
  • 「写干净的代码」这类正确但没有用的话；
  • 逐个文件的说明。

一份可以直接改的模板

# AGENTS.md

## 项目概述
个人博客 + 工具导航站。内容是 Markdown 文件，构建时生成静态页面。

## 常用命令
- 安装依赖：`pnpm install`
- 本地开发：`pnpm dev`
- 构建：`pnpm build`（提交前必须通过）
- 类型检查：`pnpm typecheck`
- 测试：`pnpm test`；只跑一个文件：`pnpm test path/to/file`

## 项目结构
- `src/app/`：页面
- `src/components/`：通用组件，新组件放这里
- `content/posts/`：文章 Markdown，frontmatter 格式见现有文件
- `content/tools.json`：工具数据，修改后运行 `pnpm validate`

## 代码风格
- TypeScript 严格模式，不用 `any`
- 组件用函数式写法，参考 `src/components/ToolCard.tsx`
- 样式只用 Tailwind 类名，不写单独的 CSS 文件

## Git 约定
- 提交信息用中文，一句话说明改了什么
- 一个任务一次提交

## 边界
- ✅ 直接做：改 `src/` 和 `content/` 下的文件，运行上面列出的命令
- ⚠️ 先问我：新增依赖、修改构建配置、改 `tools.json` 的字段结构
- 🚫 绝不做：读取或输出 `.env`；提交密钥；删除或跳过已有测试；执行 `git push`

## 容易踩的坑
- 图片必须放在 `public/images/`，否则构建后路径失效
- 文章日期格式必须是 `YYYY-MM-DD`

把模板里的内容全部换成你项目的真实情况。命令一定要亲自跑一遍确认能用，写错的命令比不写更糟。

让一份文件服务多个工具

你可能会同时用好几个 Agent 工具。最忌讳的做法是为每个工具各写一份内容相同的文件——过不了多久它们就会互相矛盾。

通用的做法：

  1. AGENTS.md 作为唯一的主文件，所有共享的内容都写在这里。
  2. 需要工具专属文件时，让它指向主文件，而不是复制内容。常见的方式有：
    • 在工具专属文件里用该工具支持的引用语法导入 AGENTS.md（Claude Code 支持在 CLAUDE.md 里用 @路径 导入其他文件）；
    • 或者建一个符号链接，让工具专属文件名指向 AGENTS.md（agents.md 官网的 FAQ 就给了用 ln -s 做兼容的例子）。
  3. 工具专属文件里只放仅对这个工具有意义的设置。

各工具具体读哪些文件名、读取顺序如何，会随版本调整，以你所用工具的官方文档为准。一个可靠的验证方法是：开一个新会话，直接问它「你加载了哪些项目说明文件？列出其中的测试命令」。

大项目：用嵌套文件

如果仓库里有好几个子项目（比如前端、后端、文档分开放），可以在各子目录里再放一份 AGENTS.md。agents.md 官网的约定是：Agent 读取离正在编辑的文件最近的那一份，越近的优先级越高；用户在对话里的明确指令则高于所有文件。Codex 的文档也描述了类似的机制：从项目根目录往下逐级合并，越靠近当前目录的文件越晚加入、优先级越高。

根目录的文件写全局通用的规则，子目录的文件只写这个子项目特有的部分。

把它当代码来维护

  • 提交进仓库，和代码一起做版本管理。
  • Agent 犯错时，先怀疑说明文件：是没写？写得有歧义？还是被淹没在太长的内容里？Claude Code 文档的建议是，如果 Agent 反复违反某条规则，多半是文件太长、这条被淹没了；如果它总在问文件里已经回答过的问题，多半是措辞有歧义。
  • 少用强调。确实总被忽略的某一条，可以加上「重要」之类的标记；但如果每条都标重要，就等于都不重要。
  • 定期修剪。项目变了，删掉过时的规则。
  • 让 Agent 帮你起草。大多数工具都能根据现有代码生成一份初稿，你在此基础上删改即可——但一定要删改，自动生成的初稿往往偏长。

常见的坑

  1. 写成了项目介绍。 大段讲项目愿景，却没有一条能执行的命令。
  2. 写得太长。 什么都想写进去，结果最重要的边界规则被淹没了。
  3. 命令是错的或过时的。 Agent 会照着执行，然后在错误的方向上越走越远。
  4. 多个工具各一份、内容不一致。 坚持「一个主文件」原则。
  5. 以为写了就一定会被遵守。 说明文件是建议性的。真正不能违反的规则（比如禁止修改某个目录），要配合工具的权限设置或自动化检查来保证。
  6. 把密钥写进说明文件。 说明文件会提交进仓库，密钥只能放在环境变量里。

写好一份项目说明文件只需要半小时，之后的每一次会话都在受益。而且它不绑定任何一个工具——今天用这个 Agent，明天换另一个，这份文件照样有效。

参考资料

← 返回教程列表