摘要

团队开始用 AI 编程工具后，最容易出问题的不是“AI 不会写代码”，而是每次都要重新解释项目结构、技术栈、测试命令和禁止改动区域。本文给出一份可直接复制的AGENTS.md / CLAUDE.md仓库说明书模板，让 AI 先读懂项目规则，再开始写代码。

正文

团队里一旦开始用 AI 编程工具，很多问题会很快暴露出来。

同一个项目里，A 同事让 AI 改接口，B 同事让 AI 补测试，C 同事让 AI 写文档。每个人问法不一样，AI 拿到的上下文也不一样。

结果就会出现这些情况：

• AI 不知道项目用的是pnpm，随手写了npm install；
• AI 不知道测试命令，改完代码没有提示跑测试；
• AI 不知道哪些目录不能碰，顺手改了老兼容逻辑；
• AI 不知道团队代码风格，把原本统一的写法改乱；
• AI 不知道.env、密钥、生产配置不能读取；
• AI 不知道接口返回结构有兼容要求，直接重命名字段；
• AI 不知道文档和代码要同步，改完实现却漏掉 README。

这类问题，本质不是某个 AI 工具“笨”。

很多时候是因为仓库没有给 AI 一份清楚的说明书。

现在越来越多 AI 编程工具开始支持仓库级上下文文件。GitHub 在 2026 年 6 月 18 日的更新中提到，Copilot code review 已支持仓库级AGENTS.md文件；Claude Code 文档也说明，每个 session 都是新的上下文窗口，可以通过CLAUDE.md提供持久化指令，并配合自动记忆跨会话保留项目知识。
来源：https://github.blog/changelog/2026-06-18-copilot-code-review-agents-md-support-and-ui-improvements/

所以，这篇文章不讲“怎么写神级提示词”。

我们只解决一个更实际的问题：

一个真实项目里，AGENTS.md / CLAUDE.md到底应该写什么，才能让 AI 少猜、少乱改、少返工？

一、先搞清楚：这类文件不是给人看的 README

很多人第一次写AGENTS.md或CLAUDE.md，会把它写成项目 README 的复制版。

比如：

这是一个后台管理系统。 使用 React、Node.js、MySQL。 请按照最佳实践编写代码。

这类说明不是完全没用，但对 AI 编程来说远远不够。

README 主要是给人快速理解项目的。

仓库级 AI 说明文件更像是给 AI 的“行为约束”。

它要告诉 AI：

这个项目怎么运行； 代码放在哪； 哪些目录负责什么； 哪些文件不要动； 改代码前要先确认什么； 改代码后要跑哪些命令； 哪些信息不能读取； 哪些场景必须人工 Review。

也就是说，它不是项目宣传页。

它是 AI 编程时的工作说明书。

二、AGENTS.md 和 CLAUDE.md 可以怎么分工

不同工具对文件名的支持不完全一样。

从当前公开文档看，GitHub Copilot code review 已支持仓库级AGENTS.md，Claude Code 则通过CLAUDE.md让 Claude 获得持久项目指令。
来源：https://github.blog/changelog/2026-06-18-copilot-code-review-agents-md-support-and-ui-improvements/

实际项目里，可以有两种做法。

做法 1：只维护一份通用 AGENTS.md

适合团队里使用多种 AI 编程工具，但不想维护太多文件。

AGENTS.md

内容写成通用规则，尽量避免绑定某个工具。

例如：

- 项目使用 pnpm，不要生成 npm install 命令。 - 修改 TypeScript 文件后，建议运行 pnpm test 和 pnpm typecheck。 - 不要读取 .env、secrets/、生产配置文件。 - 涉及 auth、payment、migration 的改动必须标记为高风险。

这种方式的优点是简单。

缺点是，如果某些工具只识别自己的专用文件，可能需要手动把内容复制过去。

做法 2：AGENTS.md 做通用规则，CLAUDE.md 做工具补充

适合团队里 Claude Code 使用频率高，同时也使用 Copilot、Codex、Cursor 等工具。

推荐结构：

. ├── AGENTS.md ├── CLAUDE.md ├── package.json ├── src/ ├── tests/ └── docs/

其中：

AGENTS.md：写所有 AI 工具都该遵守的仓库级规则。 CLAUDE.md：写 Claude Code 专用补充，比如常用任务、项目记忆、偏好输出格式。

为了避免两份文件冲突，可以让CLAUDE.md引用AGENTS.md：

# CLAUDE.md 请优先遵守本仓库根目录的 AGENTS.md。 本文件只补充 Claude Code 使用时的额外说明： - 回答前先给出修改计划； - 大范围改动前询问确认； - 生成代码后列出建议运行的命令； - 不确定业务规则时标记为“待确认”。

这样，通用规则不会到处复制，工具专用规则也有地方放。

三、一份能用的仓库说明书，至少要有 8 个模块

我建议AGENTS.md至少包含下面 8 个部分。

下面给一份可以直接复制的模板。

四、可直接复制：通用 AGENTS.md 模板

新建文件：

AGENTS.md

写入下面内容：

# AGENTS.md 本文件用于给 AI 编程工具提供仓库级说明。 所有 AI 生成、修改、审查代码的任务，都应优先遵守本文件。 --- ## 1. Project Overview 这是一个示例 Web 项目，包含前端页面、后端 API、数据库访问和基础测试。 主要目标： - 保持接口兼容； - 保持类型安全； - 保持测试可运行； - 避免无关重构； - 避免读取敏感配置和生产数据。 如果任务描述和本文件冲突，请先询问开发者，不要自行猜测。 --- ## 2. Tech Stack - Runtime: Node.js 20 - Package Manager: pnpm - Language: TypeScript - Frontend: React - Backend: Node.js / Express - Database: PostgreSQL - Test: Vitest - Lint: ESLint - Format: Prettier 不要生成 `npm install` 或 `yarn add` 命令。 本项目统一使用 `pnpm`。 --- ## 3. Repository Structure ```text . ├── src/ │ ├── api/ # 后端 API 路由 │ ├── services/ # 业务逻辑 │ ├── repositories/ # 数据库访问 │ ├── components/ # 前端组件 │ ├── utils/ # 通用工具函数 │ └── types/ # 类型定义 ├── tests/ # 单元测试和集成测试 ├── docs/ # 项目文档 ├── scripts/ # 开发辅助脚本 └── migrations/ # 数据库迁移文件

新增文件时，请优先放入已有目录。
不要随意创建新的顶层目录，除非任务明确要求。

4. Development Commands

常用命令：

pnpminstallpnpmdevpnpmtestpnpmlintpnpmtypecheckpnpmbuild

修改代码后，请根据改动范围建议运行命令：

• 修改 TypeScript 代码：pnpm typecheck
• 修改业务逻辑：pnpm test
• 修改前端组件：pnpm test和pnpm build
• 修改依赖或配置：pnpm lint、pnpm typecheck、pnpm build
• 修改数据库相关代码：说明迁移风险，并建议在测试库验证

不要声称已经运行命令，除非你确实能看到命令输出。

5. Coding Rules

通用代码规则：

• 优先做最小改动；
• 不做无关重构；
• 不修改与任务无关的文件；
• 不改变公开 API 返回结构，除非任务明确要求；
• 不删除旧兼容逻辑，除非已确认没有调用方依赖；
• 不引入新的第三方依赖，除非先解释原因；
• 生成新函数时要补充必要类型；
• 复杂逻辑需要加简短注释，但不要写废话注释；
• 如果存在不确定业务规则，请标记为“待确认”。

6. Files and Areas Requiring Extra Care

以下文件或目录属于高风险区域：

src/api/auth/ src/services/payment/ src/services/order/ src/repositories/ migrations/ .github/workflows/ docker-compose.yml package.json pnpm-lock.yaml .env .env.* secrets/

涉及这些区域时，请：

1. 先说明为什么需要修改；
2. 列出可能影响的调用方；
3. 给出测试建议；
4. 给出回滚方式；
5. 不要直接读取.env、密钥文件或生产配置。

7. Security and Privacy Rules

禁止读取、输出、复制或要求用户提供：

• .env
• .env.*
• secrets/
• 私钥文件
• 数据库密码
• 生产 Token
• Cookie
• JWT 原文
• 用户手机号、邮箱、身份证号等隐私数据
• 未脱敏生产日志

如果排查问题需要日志，请要求提供脱敏后的最小日志片段。

日志中不要打印：

• 密码
• Token
• Cookie
• Authorization header
• 支付签名
• 完整用户隐私字段

8. Review Output Format

完成代码修改后，请输出：

## 修改摘要 - 改了什么： - 为什么改： ## 影响文件 - 文件 1： - 文件 2： ## 风险点 - 权限 / 数据 / 接口 / 配置 / 兼容性影响： ## 建议运行的命令 - pnpm test - pnpm typecheck ## 待确认 - 哪些业务规则需要开发者确认： ## 回滚建议 - 如果有问题，如何快速撤回：

如果只是分析任务，不要直接改代码。
如果任务范围过大，请先拆分计划并等待确认。

这份模板不是为了显得专业。 它的作用很直接：减少 AI 自由发挥。 --- ## 五、再给 Claude Code 准备一份 CLAUDE.md 如果团队里经常用 Claude Code，可以再新建： ```text CLAUDE.md

写成这样：

# CLAUDE.md 请优先遵守根目录的 AGENTS.md。 本文件用于补充 Claude Code 使用偏好。 --- ## 1. Working Style - 修改代码前，先输出简短计划； - 涉及 3 个以上文件时，先列出影响范围； - 涉及 auth、payment、order、migration、CI/CD 时，先标记为高风险； - 不确定业务规则时，不要猜，标记为“待确认”； - 如果用户只要求分析，不要直接修改文件。 --- ## 2. Preferred Response Format 完成任务后，请按以下格式输出： ```text 完成情况： - 改动文件： - 验证建议： - 风险提醒： - 待确认： -

3. Common Project Knowledge

• 本项目使用 pnpm；
• 不使用 npm / yarn；
• 后端业务逻辑主要在src/services/；
• 数据访问主要在src/repositories/；
• 新测试优先放在tests/；
• 不要随意修改数据库迁移文件；
• 不要读取.env或生产配置。

4. Do Not Do

• 不要把大范围格式化和业务修改混在同一个任务；
• 不要顺手升级依赖；
• 不要修改锁文件，除非任务明确要求；
• 不要生成没有测试建议的业务改动；
• 不要声称已经运行测试，除非有真实输出。

Claude Code 官方文档提到，`CLAUDE.md` 是给 Claude 提供持久上下文的指令文件，而自动记忆会基于用户修正和偏好累积学习。这里的重点是：不要把所有细节都塞进聊天窗口，仓库里应该有一份稳定可复用的项目规则。 来源：https://code.claude.com/docs/en/memory --- ## 六、用一个真实任务看看区别 假设你给 AI 一个任务： ```text 帮我给用户注册接口增加手机号字段。

如果没有仓库说明文件，AI 可能会这样做：

1. 直接修改 User 类型； 2. 改注册接口； 3. 改数据库字段； 4. 顺手改前端表单； 5. 新增一个 phone-validator 包； 6. 没有补测试； 7. 没有说明旧用户数据怎么办。

看起来很勤快，实际风险很高。

如果仓库里有AGENTS.md，AI 至少应该先意识到：

- 这是接口字段变更； - 可能影响前端、后端、数据库、测试和文档； - 是否修改数据库迁移需要确认； - 是否允许新增依赖需要确认； - 手机号属于隐私字段，日志不能明文打印； - 接口返回结构是否兼容需要确认； - 修改后应该运行 typecheck 和测试。

更理想的输出应该是：

## 修改计划 1. 确认手机号字段是否必填； 2. 确认是否需要数据库迁移； 3. 检查注册接口请求体 schema； 4. 更新 User 类型； 5. 补充参数校验； 6. 补充测试用例； 7. 确认日志不打印手机号明文； 8. 更新接口文档。 待确认： - 手机号是否必填？ - 旧用户没有手机号时如何处理？ - 是否允许使用现有校验函数，不新增依赖？

这才是仓库说明文件的价值。

它不是让 AI 一次写得更长，而是让 AI 先知道哪些地方不能乱来。

七、可以加一个脚本检查说明文件是否缺失

团队项目里，最怕的是有人新建仓库却忘了放AGENTS.md。

下面给一个很简单的 Python 脚本，用于检查当前仓库是否包含基础 AI 说明文件，并检查是否写了几个关键模块。

新建文件：

check_ai_repo_instructions.py

代码如下：

#!/usr/bin/env python3frompathlibimportPath REQUIRED_FILES=["AGENTS.md",]OPTIONAL_FILES=["CLAUDE.md",]REQUIRED_SECTIONS=["Project Overview","Tech Stack","Repository Structure","Development Commands","Coding Rules","Security and Privacy Rules","Review Output Format",]defread_text(path:Path)->str:try:returnpath.read_text(encoding="utf-8")exceptUnicodeDecodeError:returnpath.read_text(encoding="utf-8-sig")defmain()->None:root=Path.cwd()failed=Falseprint("# AI repository instruction check")print()forfilenameinREQUIRED_FILES:path=root/filenameifnotpath.exists():print(f"[ERROR] Missing required file:{filename}")failed=Truecontinuecontent=read_text(path)print(f"[OK] Found{filename}")forsectioninREQUIRED_SECTIONS:ifsectionnotincontent:print(f"[WARN]{filename}may miss section:{section}")forfilenameinOPTIONAL_FILES:path=root/filenameifpath.exists():print(f"[OK] Found optional file:{filename}")else:print(f"[INFO] Optional file not found:{filename}")iffailed:raiseSystemExit(1)print()print("Check finished.")if__name__=="__main__":main()

运行：

python check_ai_repo_instructions.py

如果仓库里有AGENTS.md，会看到类似输出：

# AI repository instruction check [OK] Found AGENTS.md [OK] Found optional file: CLAUDE.md Check finished.

如果缺失：

# AI repository instruction check [ERROR] Missing required file: AGENTS.md [INFO] Optional file not found: CLAUDE.md

这个脚本不复杂，但适合放进团队初始化检查、PR 检查或项目模板里。

八、还可以把它接入 PR 模板

只写文件还不够，最好让它进入团队流程。

例如.github/pull_request_template.md可以加一段：

## AI Assisted Development Checklist 如果本次 PR 使用了 AI 编程工具，请确认： - [ ] 已遵守 AGENTS.md / CLAUDE.md - [ ] AI 没有读取 `.env`、密钥、生产配置或未脱敏日志 - [ ] 改动范围和任务目标一致 - [ ] 高风险文件已单独 Review - [ ] 已运行必要测试或说明未运行原因 - [ ] 涉及接口、数据库、权限、支付、订单时已补充风险说明

这样做的好处是：

不是靠每个人记住规则， 而是把规则放进仓库和 PR 流程里。

研究层面也开始关注仓库级说明文件对 AI coding agents 的影响。2026 年 1 月的一篇预印本研究分析了 10 个仓库和 124 个 PR，发现存在AGENTS.md与更低的中位运行时间和更少的输出 token 消耗相关，同时任务完成行为保持相近。这个结果不能简单理解成“写了 AGENTS.md 就一定更强”，但至少说明仓库级说明文件正在成为 AI 编程工作流里值得重视的一层配置。
来源：https://arxiv.org/abs/2601.20404

九、AGENTS.md 不要写成这几种样子

1. 太空

不推荐：

请遵循最佳实践。 请写高质量代码。 请注意安全。

这些话太泛了，AI 很难执行。

更好的写法是：

修改 TypeScript 业务逻辑后，请建议运行 pnpm typecheck 和 pnpm test。 涉及 auth、payment、migration 的变更必须标记为高风险。 不要读取 .env、secrets/、生产配置文件。

2. 太长

也不推荐把几十页团队规范都塞进去。

AI 不是不能读长文档，但太长会稀释重点。

更好的做法是：

AGENTS.md 写高优先级规则； docs/engineering.md 写详细规范； 在 AGENTS.md 里引用关键文档路径。

例如：

详细 API 规范见：`docs/api-style-guide.md` 详细数据库规范见：`docs/database-guide.md` AI 只需要优先遵守本文件列出的高风险规则。

3. 规则互相冲突

比如同时写：

优先最小改动。 可以自由重构不合理代码。

这会让 AI 不知道到底按哪个来。

更好的写法是：

默认优先最小改动。 只有当任务明确要求重构时，才可以提出重构计划。 重构前必须列出影响范围并等待确认。

4. 没有禁止项

很多团队只告诉 AI “该做什么”，却没告诉它“不要做什么”。

实际项目里，禁止项往往更重要。

至少应该写清楚：

不要读哪些文件； 不要改哪些目录； 不要新增哪些依赖； 不要改变哪些接口； 不要打印哪些日志； 不要声称运行过哪些命令。

十、什么时候需要更新这份文件

AGENTS.md / CLAUDE.md不是一次写完就不动。

下面这些情况都应该更新：

• 项目从 npm 换成 pnpm；
• 测试框架变了；
• 新增了高风险模块；
• API 返回规范调整了；
• 数据库迁移流程变了；
• CI/CD 命令变了；
• 团队发现 AI 经常犯同一种错；
• 某类文件不应该再让 AI 修改；
• 新增了安全或隐私要求；
• 项目拆分成 monorepo。

建议每隔一段时间，在团队 Review 里问一句：

最近 AI 有没有反复犯同一个项目规则错误？ 如果有，把规则写进 AGENTS.md。

这比每次在聊天里重复提醒更稳定。

十一、这类文件的边界：它不能替你做最终审查

即使有AGENTS.md / CLAUDE.md，也不要把 AI 输出当成可直接合并。

它只能减少这些问题：

• AI 不知道项目用什么命令；
• AI 不知道文件放哪里；
• AI 不知道哪些目录高风险；
• AI 不知道输出格式；
• AI 不知道要提醒测试；
• AI 不知道安全边界。

它不能保证：

• 业务逻辑一定正确；
• 权限判断一定安全；
• 数据库迁移一定没风险；
• 并发场景一定覆盖；
• 支付、订单、退款流程一定可靠；
• AI code review 能发现所有漏洞。

尤其是安全问题，不能只靠 AI review。关于 Copilot code review 安全能力的研究也提醒，AI 审查可能更擅长指出低严重度问题，而对 SQL 注入、XSS、不安全反序列化等关键漏洞的检测并不可靠。这个结论不代表工具没有价值，但说明安全审计、专用扫描和人工 Review 仍然不能省。
来源：https://arxiv.org/abs/2509.13650

十二、最后总结

AI 编程工具越来越像一个“能动手的协作者”。

但协作者要想稳定工作，不能每次都重新猜项目规则。

AGENTS.md / CLAUDE.md的价值，就是把仓库里的关键规则固定下来：

项目是什么； 用什么技术栈； 目录怎么分工； 怎么跑测试； 哪些文件不能碰； 哪些信息不能读； 改完后怎么汇报； 什么情况必须人工确认。

我更建议团队先从一份简单的AGENTS.md开始。

不要追求一步到位。

先写清楚：

技术栈； 目录职责； 开发命令； 安全边界； 高风险文件； Review 输出格式。

只要这几项写清楚，AI 编程工具的输出就会少很多“猜出来的东西”。