团队最佳实践

从个人到团队：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: CI

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          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-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check AGENTS.md exists
        run: |
          if [ ! -f AGENTS.md ]; then
            echo "Error: AGENTS.md is missing"
            exit 1
          fi

这样一来，每次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能读取你的项目规范，然后再逐步完善。用起来比什么都重要。

感谢阅读，我们江湖再见。

---