10人团队AI协作30天完整复盘：AGENTS.md配置+5分支Git+Agent角色矩阵（附脚本）

0. 读者速览

• 适用人群：技术负责人、架构师、DevOps、全栈工程师
• 核心产出：AGENTS.md模板、Git Hook脚本、GitHub Actions配置、Agent角色定义
• 阅读时长：约15分钟
• 可复现性：所有代码/配置可直接复制

1. 背景与痛点

2026年Q1，10人团队混用Claude Code和Codex，同一项目多人并行开发，导致：

• 代码风格不统一
• 提交信息混乱
• 合并冲突频繁（日均8-12次）
• PR从提交到合入平均4小时
• 加班严重

根因：没有统一的AI协作规范、没有标准化的Git工作流、AI角色未分工。

2. 解决方案总览

模块	技术选型/标准	状态
统一配置	AGENTS.md（Agentic AI Foundation标准）	✅ 已落地
项目文档	AGENTS.md + ROADMAP.md + README.md	✅ 已落地
Git工作流	5分支 + Conventional Commits + 强制PR	✅ 已落地
CI/CD	GitHub Actions（lint+test+build+deploy）	✅ 已落地
AI角色分工	产品/架构/开发/测试 Agent矩阵	✅ 已落地
工具集成	MCP Server（GitHub/飞书/群晖）	✅ 已落地

3. 详细实施步骤

3.1 统一配置：AGENTS.md

在项目根目录创建AGENTS.md，以下为可直接复用的模板：

# 团队AI协作规范

## 项目背景
- 产品：AI客服系统
- 技术栈：Python 3.11 + FastAPI / React 18 + TypeScript / PostgreSQL 15
- 代码风格：Black（Python）/ Prettier（TypeScript）
- 提交规范：Conventional Commits

## 当前任务
详见 `ROADMAP.md`

## 约束条件
- 所有API变更必须更新OpenAPI文档
- 数据库迁移必须写回滚脚本
- 敏感信息走环境变量，禁止硬编码

## Agent角色定义
- 产品经理Agent：负责PRD编写、需求拆解
- 架构师Agent：负责技术方案设计、模块拆分
- 开发工程师Agent：负责代码生成、单元测试
- 测试工程师Agent：负责测试用例生成、回归测试

配置其他AI工具指向AGENTS.md：

• Codex：在~/.codex/AGENTS.md中写入"以项目根目录AGENTS.md为准"
• Gemini CLI：类似配置

3.2 三文档体系

文档	读者	内容	更新频率
AGENTS.md	AI	项目背景、技术栈、规范、角色	基建变更时
ROADMAP.md	AI	进度、下一步、卡点	每周
README.md	人	产品说明、部署指南	功能发布时

ROADMAP.md模板：

# 项目进度

## 已完成 ✅
- [x] 基础框架搭建（2026-06-01）

## 进行中 🔄
- [ ] 知识库管理功能（预计6月15日）

## 卡点 ⚠️
- 向量检索延迟偏高，需优化索引

## 下一步
- 6月12日前完成性能压测

3.3 Git工作流：5分支模型

feature/xxx ──→ dev ──→ release/vX.X ──→ main
      ↑            ↑            ↑
   bugfix/xxx ─────┘            │
                                │
                           tag vX.X

分支保护规则（以GitHub为例）：

• main、dev：禁止直接push，要求PR、至少1人Review、状态检查通过
• release/*：发布前保护

提交信息规范（Conventional Commits）：

# 格式：<type>(<scope>): <subject>
feat(api): 新增对话接口
fix(model): 修复显存泄漏
docs(readme): 更新部署说明
refactor(utils): 重构日志模块
test(core): 增加单元测试
chore(deps): 升级依赖版本

Git Hook脚本（.git/hooks/commit-msg）：

#!/bin/sh
# 检查提交信息是否符合 Conventional Commits
commit_regex='^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,50}'
if ! grep -qE "$commit_regex" "$1"; then
    echo "错误：提交信息不符合 Conventional Commits 规范"
    echo "示例：feat(api): 新增对话接口"
    exit 1
fi

安装：chmod +x .git/hooks/commit-msg

3.4 CI/CD自动化（GitHub Actions）

创建.github/workflows/ci.yml：

name: CI
on:
  pull_request:
    branches: [dev, main]
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 设置Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: 安装依赖
        run: pip install -r requirements.txt
      - name: Lint
        run: flake8 src/
      - name: 单元测试
        run: pytest tests/

  build:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - name: 构建镜像
        run: docker build -t ai-cs:latest .
      - name: 推送镜像
        run: docker push your-registry/ai-cs:latest

3.5 Agent角色分工与提示词

在AGENTS.md中定义角色，然后在Claude Code/Codex中通过@角色名调用。

示例：架构师Agent提示词

## Agent: 架构师
你负责技术方案设计。当用户说"设计一个用户认证模块"时，输出：
1. 接口定义（REST或GraphQL）
2. 数据库表结构（SQL DDL）
3. 安全注意事项（JWT、刷新令牌、防暴力破解）
4. 潜在风险（会话管理、日志泄露）

并行任务示例：

# 终端1：Claude Code - 角色开发
@开发工程师 实现健康检查接口 GET /health

# 终端2：Claude Code - 角色架构
@架构师 设计数据库索引优化方案

# 终端3：Codex - 角色测试
@测试工程师 为现有API生成集成测试用例

3.6 MCP集成（可选）

安装MCP server：npm install -g @modelcontextprotocol/server-github

配置Claude Code的MCP：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your_token"
      }
    }
  }
}

4. 效果数据

指标	实施前	实施后（30天）
每日代码冲突次数	8-12次	0-1次
PR合入平均时间	4小时	20分钟
单功能开发周期	5天	1.5天
人均周加班	8小时	0.5小时
AI代码采纳率	20%	80%

5. 常见问题

Q：AGENTS.md 创建了，但Codex不读怎么办？

A：要求Codex版本≥1.2.0。在项目根目录执行 codex config set project_agents enable。

Q：多人同时用feature分支，合入dev时冲突怎么办？

A：按5分支模型，每天至少pull一次dev，功能完成后立即提PR，不要长期持有分支。使用git rebase dev减少合并提交。

Q：我们的项目不是Web应用，这个方案通用吗？

A：通用。AGENTS.md和Git工作流与业务无关，角色矩阵可替换为你团队的岗位（如嵌入式、游戏、数据等）。

Q：AI生成的代码质量参差不齐，如何保证？

A：1）在AGENTS.md中明确代码规范；2）强制PR和Code Review；3）CI自动跑Lint和测试；4）用测试Agent生成用例覆盖边界。

Q：如何让新人快速上手这套流程？

A：将AGENTS.md、ROADMAP.md、README.md作为入职必读。新人clone仓库后，AI自动读取配置，可立即开始任务。

6. 快速启动（最小可行版）

如果你只有2小时，只做这三件事：

1. 创建AGENTS.md（10分钟）：只写技术栈 + 代码规范
2. 启用5分支模型（30分钟）：保护main和dev，强制PR
3. 定义3个Agent角色（1小时）：产品经理、开发、测试

7. 总结

本方案已在真实10人团队验证30天，核心产出：

• 一套可复制的AI协作规范（AGENTS.md）
• 一个标准化的Git工作流（5分支 + Conventional Commits）
• 一套AI角色分工矩阵（4个Agent）
• 自动化CI/CD + MCP集成

所有配置、脚本、模板均已在上文提供，可直接复制使用。

如果你照着做了一遍，欢迎在评论区留下你的问题或改进建议。我会持续更新这份方案，并在本文附上最新版配置仓库链接。

---

关于作者：joe45，二十年技术老兵，独立开发者。专注AI协作与团队效能，所有方案均来自亲身实践。