从个人到团队：AGENTS.md的协作与演进
团队踩坑史
个人用AGENTS.md，门槛其实不高。你自己定的规矩，自己遵守，没那么多破事。但到了团队里，情况就复杂了。
我经历过这么一件事：团队里两个人都用AI编程工具，一个用的是Claude Code，一个用的是Cursor。两人各自的AGENTS.md写得不一样，导致AI生成出来的代码风格完全不同。一个用单引号，一个用双引号；一个用箭头函数，一个用function声明。Code Review的时候那叫一个酸爽，Diff里全是格式差异。
从那之后我就意识到：团队里AGENTS.md必须统一，而且要有配套的协作流程。
团队级AGENTS.md的设计
首先是模板设计。你需要为整个团队设计一个基础模板，所有项目都基于这个模板来写。
# AGENTS.md - 团队标准模板## 项目信息
- 项目名称：
- 项目描述：
- 技术栈：
- 负责人：## 开发环境### 环境要求
- Node.js 版本：
- 包管理器：（pnpm/npm/yarn）
- 数据库版本：### 基础命令
```bash
# 安装依赖
pnpm install# 开发模式
pnpm dev# 构建
pnpm build# 测试
pnpm test
团队代码规范
通用规范
- 使用 TypeScript 严格模式
- 使用 ESLint + Prettier
- 提交前必须通过 lint 和 test
Git 规范
- 分支命名：feature/xxx, bugfix/xxx
- 提交信息格式：type: message
- PR 必须通过 CI 检查
Code Review 规范
- 至少一人 review 通过才能合并
- 关注逻辑而非格式（格式由工具保证）
- 拒绝过大的 PR（超过 500 行需拆分）
团队约定
AI 使用约定
- 禁止直接提交 AI 生成的代码，必须 review
- 涉及安全的代码必须人工编写
- 重要逻辑需要添加注释说明
文档约定
- API 文档使用 Swagger/OpenAPI
- 组件文档使用 Storybook
- README 保持最新状态
这个模板是团队所有项目的起点。每个项目可以基于这个模板进行扩展，添加项目特定的内容。## AGENTS.md在Code Review中的角色Code Review是团队协作中最关键的环节。AGENTS.md在这个环节里可以发挥很大作用。首先，Reviewer应该检查AI生成的代码是否符合AGENTS.md里的规范。如果AGENTS.md里写着"禁止使用any类型"，那就要检查AI生成的代码里有没有any。如果有，直接打回。其次，Reviewer可以把AI做得不好的地方记录下来，反馈给代码作者，让作者更新AGENTS.md。这样下次AI就能避免同样的问题。最后，团队可以定期（比如每两周）组织一次AGENTS.md的集体审查。大家坐在一起，看看这段时间有没有积累什么新的经验，AGENTS.md需不需要更新。```markdown
## Code Review 检查清单（基于 AGENTS.md）### 代码规范
- [ ] 是否使用 TypeScript 严格模式
- [ ] 是否有 ESLint 错误
- [ ] 代码格式是否正确### 功能完整性
- [ ] 是否有对应的测试
- [ ] 测试是否通过
- [ ] 边界条件是否覆盖### 安全审查
- [ ] 是否有硬编码的密钥
- [ ] 是否有 SQL 注入风险
- [ ] 权限控制是否正确
CI/CD 集成
把AGENTS.md和CI/CD流程结合起来，可以确保规范被强制执行。
# .github/workflows/ci.yml
name: CIon: [push, pull_request]jobs:lint:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- uses: actions/setup-node@v3with:node-version: '18'- run: npm ci- run: npm run lint- run: npm run typecheck- run: npm test# 检查 AGENTS.md 是否存在agents-md-check:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- name: Check AGENTS.md existsrun: |if [ ! -f AGENTS.md ]; thenecho "Error: AGENTS.md is missing"exit 1fi
这样一来，每次push或者PR，都会自动检查AGENTS.md是否存在。如果不存在，CI就会失败，强制要求添加。
项目模板化
团队通常会有多个项目，每个项目都写一个AGENTS.md很麻烦。我的做法是：创建一个项目模板，里面自带AGENTS.md。
如果你用Yeoman或者类似的脚手架工具，可以把AGENTS.md模板化：
// .yo-rc.json
{"generator-frontend": {"files": ["package.json","tsconfig.json","AGENTS.md", // 自动包含"src/**/*"]}
}
这样新建项目的时候，AGENTS.md就会自动包含进去，省得每次都手动复制粘贴。
多语言/多项目场景
如果你的团队同时维护多种技术栈的项目，建议为每种技术栈准备一个模板。
templates/
├── frontend-react/ # React 前端模板
│ └── AGENTS.md
├── frontend-vue/ # Vue 前端模板
│ └── AGENTS.md
├── backend-node/ # Node.js 后端模板
│ └── AGENTS.md
├── backend-java/ # Java 后端模板
│ └── AGENTS.md
└── ...
这样选择技术栈的时候，直接把对应的AGENTS.md复制过去就行了。
文档维护
AGENTS.md不是写完就扔一边的静态文件，它需要持续维护。我的建议是：
把AGENTS.md的更新纳入团队的常规工作。每周的周报里，可以加上一条"AGENTS.md更新记录"，让大家养成习惯。
# AGENTS.md 更新日志## 2026-03-13
- 添加：React 18 严格模式配置
- 更新：测试命令改为 pnpm test
- 修正：删除过时的 Node.js 版本要求## 2026-03-06
- 添加：前端组件测试规范
- 添加：API 文档要求## 2026-02-27
- 初始版本（团队模板）
另外，可以用一些工具来检查AGENTS.md的健康度。比如检查是否有死链接、是否有过时的内容、是否和其他文档保持一致。
团队协作的最佳实践
最后总结一下团队使用AGENTS.md的最佳实践：
第一，统一的团队模板。所有项目基于同一个模板，确保基本规范一致。
第二，明确的职责分工。谁负责维护AGENTS.md，谁负责审核更新，都要定清楚。
第三，定期的集体审查。两周一次或者一个月一次，大家一起reviewAGENTS.md，交流经验。
第四，CI/CD强制集成。把AGENTS.md的检查加入到CI流程里，确保规范被强制执行。
第五，版本控制和历史记录。每次更新都提交，保持可追溯性。
小结
AGENTS.md从个人用到团队用，关键在于统一和协作。一个人的经验可以写成AGENTS.md，一个团队的经验同样可以。关键是把这个机制建立起来，让AGENTS.md成为团队和AI协作的桥梁。
到这里，7篇系列文章就全部写完了。从认识AGENTS.md开始，到核心结构、前端实战、后端实战、测试重构、高级技巧，再到团队协作，算是把这个话题比较全面地覆盖了一遍。
如果你之前没用过AGENTS.md，建议从最简单的版本开始，先让AI能读取你的项目规范，然后再逐步完善。用起来比什么都重要。
感谢阅读，我们江湖再见。