摘要团队开始用 AI 编程工具后最容易出问题的不是“AI 不会写代码”而是每次都要重新解释项目结构、技术栈、测试命令和禁止改动区域。本文给出一份可直接复制的AGENTS.md / CLAUDE.md仓库说明书模板让 AI 先读懂项目规则再开始写代码。正文团队里一旦开始用 AI 编程工具很多问题会很快暴露出来。同一个项目里A 同事让 AI 改接口B 同事让 AI 补测试C 同事让 AI 写文档。每个人问法不一样AI 拿到的上下文也不一样。结果就会出现这些情况AI 不知道项目用的是pnpm随手写了npm installAI 不知道测试命令改完代码没有提示跑测试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.mdClaude 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 的改动必须标记为高风险。这种方式的优点是简单。缺点是如果某些工具只识别自己的专用文件可能需要手动把内容复制过去。做法 2AGENTS.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 个部分。模块作用常见遗漏项目概览让 AI 知道项目是干什么的只写技术栈不写业务边界技术栈避免 AI 给错命令和依赖npm / pnpm / yarn 混用目录职责让 AI 知道代码放哪AI 新建错误目录开发命令改完后知道跑什么漏跑测试和类型检查代码规范保持团队风格一致AI 改出另一种写法禁止改动区域防止误改核心逻辑兼容层、迁移脚本被乱动安全边界防止读取密钥和隐私.env、Token、日志泄露Review 要求让 AI 改完能自查只说完成不列风险下面给一份可以直接复制的模板。四、可直接复制通用 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/涉及这些区域时请先说明为什么需要修改列出可能影响的调用方给出测试建议给出回滚方式不要直接读取.env、密钥文件或生产配置。7. Security and Privacy Rules禁止读取、输出、复制或要求用户提供.env.env.*secrets/私钥文件数据库密码生产 TokenCookieJWT 原文用户手机号、邮箱、身份证号等隐私数据未脱敏生产日志如果排查问题需要日志请要求提供脱敏后的最小日志片段。日志中不要打印密码TokenCookieAuthorization 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.mdAI 至少应该先意识到- 这是接口字段变更 - 可能影响前端、后端、数据库、测试和文档 - 是否修改数据库迁移需要确认 - 是否允许新增依赖需要确认 - 手机号属于隐私字段日志不能明文打印 - 接口返回结构是否兼容需要确认 - 修改后应该运行 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(encodingutf-8)exceptUnicodeDecodeError:returnpath.read_text(encodingutf-8-sig)defmain()-None:rootPath.cwd()failedFalseprint(# AI repository instruction check)print()forfilenameinREQUIRED_FILES:pathroot/filenameifnotpath.exists():print(f[ERROR] Missing required file:{filename})failedTruecontinuecontentread_text(path)print(f[OK] Found{filename})forsectioninREQUIRED_SECTIONS:ifsectionnotincontent:print(f[WARN]{filename}may miss section:{section})forfilenameinOPTIONAL_FILES:pathroot/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 编程工具的输出就会少很多“猜出来的东西”。