AI 时代的开发流程，
从需求到上线 全周期指南

怎么做

1. 需求开始前，先确认产品经理提供的 intent.md（业务意图、目标、验收标准）；没有就先补，再动手。
2. DRI 基于意图写 plan.md（可以让 Agent 帮你起草，你改）。
3. 计划必须包含：目标、非目标、可机器判定的验收标准、涉及哪些模块、有没有数据库变更。
4. 自己先过一遍"陌生人测试"：没参与讨论的人拿到这个 plan 能直接做吗？不能就补。
5. 用 Agent 的 Plan Mode 启动，让它先输出实现计划，你确认后再让它写代码。

# Feature: <名称>  关联需求：JIRA/工单号

## 目标
一句话。例：订单超时未支付自动取消并释放库存。

## 非目标
- 本次不做退款流程
- 本次不改消息推送模板

## 验收标准
- [ ] 订单超过 30 分钟未支付，状态变为 CANCELLED
- [ ] 取消后库存自动释放回可用库存
- [ ] 用户收到取消通知（短信+站内信）
- [ ] 重复取消不产生副作用（幂等）

## 涉及模块
- 修改：order-service / 定时任务 / 库存服务
- 新增：取消订单的领域事件

## 数据库变更
- 是否有 DDL：是/否
- 如有，回滚脚本：xxx.sql

## 风险
- 风险描述（例：并发取消导致超卖）→ 只登记风险，缓解方案写入 spec.md
- 回滚方式：feature flag / 回退代码重发

怎么做

1. 让 Agent 先列 2-3 个候选方案和各自的取舍，不要让它直接选一个就写。
2. 涉及订单、支付、库存、资金这些核心链路的改动，方案必须给资深工程师过一眼。
3. 重要决策写在 PR 描述里：为什么这么做、放弃了什么、什么条件下会推翻。
4. 明确告诉 Agent 不能动什么：不要改 legacy 模块、不要新增依赖、不要破坏现有接口契约。

每次新会话必须做的事

1. 在仓库根目录放 AGENTS.md（Agent 会自动读取），写清楚项目规范。
2. 用 Agent 的 Plan Mode 启动：先让它出计划，你确认后再动手。
3. 一次只让 Agent 做一个小改动——写完、跑测试、确认，再让它做下一个。
4. 独立任务（比如写接口 + 写测试）可以用 Subagents 并行，但最后你统一 review。
5. 关键决策写入项目记忆（omp 用 /memory retain；其他工具用其等价机制，如 CLAUDE.md 追加），下次会话不用重新说。

AGENTS.md 模板（本团队）

# 项目：XXX 服务
技术栈：Java 17 / Spring Boot / MySQL / Redis / Kafka

# 常用命令（与硬门禁清单 ① 本地开发五项一一对应）
- 格式：mvn spotless:apply
- 静态检查：mvn checkstyle:check pmd:check spotbugs:check
- 编译：mvn clean compile
- 单测（改动模块）：mvn test -Dtest=你改的类
- 全量测试：mvn test
提交前五项必须全绿（以本清单为准，与 CI 门禁保持同步）。

# 代码规范
- Controller 只做参数校验和路由，业务逻辑在 Service
- 数据库操作必须走 Mapper，不要在 Service 里拼 SQL
- 业务异常继承 BizException，错误码统一管理
- 交易链路接口必须加幂等设计

# 不能做的事
- 不要动 src/legacy/ 目录
- 不要引入新的第三方库（需要先问 Tech Lead）
- 不要在循环里调用 RPC 或数据库查询
- 所有对外接口必须写参数校验和异常处理

docs 目录：业务知识沉淀（人审受控）

每个项目根目录 docs/ 下放业务文档——Agent 懂代码结构，但不懂业务语义。

• 放什么：业务场景说明、状态机、交易规则、接口契约——这些是人审受控文档：只能随代码同 PR 由人更新，Agent 不得自行改写（Agent 是 docs 最重度的消费者，不能既当读者又当作者）
• 怎么更新：改业务逻辑必须先改 docs 再改代码，同一个 PR。不允许只改代码不改 docs
• 多久 review：每季度 DRI 过一遍 docs 是否过时，过期的比没有更危险。review 落痕：在 docs/REVIEW-LOG.md 追加一行（日期 / DRI / 结论），没记录 = 没做过

Skills 库（awesome-rules 仓）

高频操作沉淀成可复用的 Skill，存在 awesome-rules 仓，不用每次重新跟 Agent 描述。项目里引用即可。

• 怎么用：在 AGENTS.md 里引用需要的 Skill，Agent 按需加载，不用全塞进上下文
• 沉淀时机：同一个操作跟 Agent 描述过 3 次以上，就该写成 Skill 放进 awesome-rules
• 已有示例：查线上日志、写 SQL 排查、生成回滚脚本、PR 描述模板等

# 假设主仓库在 ~/repo/order-service

# 1. 为任务 A 建一个独立 worktree（新目录 + 新分支）
git worktree add ../order-A feature/order-cancel

# 2. 为任务 B 再建一个
git worktree add ../order-B feature/order-refund

# 3. 两个终端分别进去，各启动一个 Agent
cd ../order-A && omp
cd ../order-B && omp

# 4. 各自开发、各自提 PR
# 5. 任务完成后清理 worktree
git worktree remove ../order-A
git worktree remove ../order-B

三步写代码：计划 → 写 → 自查

1. 先出计划（plan.md）：工程师审计划，消除模糊后再动手。先改文档返工更轻。
2. AI 写代码：按计划一步步写，每步跑测试。
3. AI 自查：写完自动跑测试 + 构建，全部通过才算完成。不通过自己改，最多 5 轮。

陌生人 Reviewer 闭环（核心场景）

参考 Peter Steinberger（OpenClaw 之父）的做法：主 Agent 写完代码后，唤起一个全新空白上下文的子 Agent 当 Reviewer，双方来回辩论：

1. 主 Agent 写完代码，唤起空白 Reviewer："帮我把刚才改的代码全盘过一遍"
2. Reviewer 挑出问题回传给主 Agent
3. 主 Agent 辩解或认错修改，改完再提交给 Reviewer
4. 来回拉扯最多 10 个回合；第 10 回合仍未收敛即升级人裁决，双方意见全文留入 PR 描述，不无限辩论

跑与不跑按各项目 AGENTS.md 定义的人审范围执行：定义为核心链路的必须跑，之外可选。成本预期：核心链路 PR 预留 1-2 小时，排进发布节奏。

怎么做

1. 让 Agent 写代码的同时把单测一起写了——不要留到最后补。
2. 本地必须跑通：lint + 单测全绿，再提 PR。
3. CI 红灯不要 skip——让 Agent 看日志、改到绿为止，最多 5 轮。
4. 交易链路的改动，必须补边界 case：空值、并发、幂等、异常路径。
5. 改完测试跑全量，不要只跑你改的那个文件。

AI 写的测试，信多少？

Evals 评测闭环（核心场景）

光靠单测不够——核心链路要维护一个 20-50 个真实任务的评测集，每次代码变更或 Agent 配置变更都自动跑一遍，通过率掉了就禁止合并。

• 同等待遇（目标态，3 个月内接线）：代码变更和 Agent 配置变更（CLAUDE.md / Skills / Hooks 改动）一视同仁都要跑 Evals——当前 CI 仅代码变更触发，配置变更触发排在 3 个月路线
• 持续回归：不是提测前才跑，每次 PR 自动跑
• 掉分禁合并：通过率比基线低就红，不许强合。基线三条纪律：① 初始基线 = 评测集首次全量跑通率，记录在仓（如 evals/baseline.json）；② 基线只升不降，下调需 PR + Tech Lead approve 并留痕；③ 新用例合入时基线重算为 min(当前通过率, 旧基线)，新用例不得放松旧约束
• 线上 bug 转 Evals：每次线上修复后，补一个评测用例进集子里，下次自动检测
• 用例退役：连续 6 个月未捕获差异且业务已下线的用例，评测集 owner 可 PR 退役并留痕（防止集子只增不减变成新屎山）

发布流程（务必照做）

1. develop → dev：PR 合并到 develop 后 Codeup 自动部署 dev，你自己验证。
2. 切 release：从 develop 切 release/x.x.x，只修 bug，不加新功能。bug fix 一律在 release 分支上直接提交（保持 uat 验证对象 = 发布对象），由该 PR 的 DRI 负责随 release → develop 回合带回 develop——不允许只存在于 release 的提交。
3. uat 验证：通知运维部署 release 到 uat，测试和产品验收。
4. 合 main：uat 通过后，提 PR 把 release 合到 main，打版本标签。
5. prod 发布：通知运维部署 main 到生产，发布后盯 30 分钟监控。
6. 回 develop：发布确认没问题后，单独再提一个 PR 把 release 合回 develop，不要用 git flow release finish（它会一步合 main+develop，把未验证代码带进 develop）。

紧急回滚怎么做

哪些路径必须资深 review

1. prod 发布后，自己盯 30 分钟。判定基准（占位，按实际监控能力校准）：错误率 > 发布前 1 小时基线的 2 倍、核心接口 P99 超基线 30%、订单量低于上周同期 70%，任一命中即触发回滚评估。监控入口：【dashboard 地址/命令待填】。
2. 触发权：观察期内 DRI 有权直接呼叫运维回滚，不需要再审批。发现问题先关流量/回滚，再定位原因。
3. 踩过的坑（比如某个配置项容易漏、某个边界 case 没想到）写入项目记忆（omp 用 /memory retain；其他工具用等价机制）记下来。
4. 定期让 Agent 扫描热点路径，提性能优化 PR（这是后面的事，先把手头流程走顺）。

翻车复盘三步闭环

线上出问题后，光写复盘文档不够——要确保 Agent 下次不再犯同样的错：

1. 写复盘文档：存档，讲清楚什么问题、根因、影响
2. AGENTS.md 加一条"别再犯"：把教训写进项目规则，Agent 下次自动遵守
3. Evals 加一个用例：下次自动回归，再犯直接红

三步走完才算复盘结束。只写文档不加规则和评测 = 下次还会犯。