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小时，只做这三件事：
- 创建AGENTS.md（10分钟）：只写技术栈 + 代码规范
- 启用5分支模型（30分钟）：保护main和dev，强制PR
- 定义3个Agent角色（1小时）：产品经理、开发、测试
7. 总结
本方案已在真实10人团队验证30天，核心产出：
- 一套可复制的AI协作规范（AGENTS.md）
- 一个标准化的Git工作流（5分支 + Conventional Commits）
- 一套AI角色分工矩阵（4个Agent）
- 自动化CI/CD + MCP集成
所有配置、脚本、模板均已在上文提供，可直接复制使用。
如果你照着做了一遍，欢迎在评论区留下你的问题或改进建议。我会持续更新这份方案，并在本文附上最新版配置仓库链接。
关于作者：joe45，二十年技术老兵，独立开发者。专注AI协作与团队效能，所有方案均来自亲身实践。
