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

怎么做

1. 需求开始前，先确认 intent.md（业务意图、目标、验收标准）就位；没有就先补，再动手。真相源字段切分：工单系统管状态（要不要做、优先级、排期、验收流转），intent.md 管内容（唯一内容真相源，随代码进版本库）。双向一行链接：工单描述里只放 intent.md 的仓库路径，intent.md 头部保留工单号——重叠字段为零，漂移无处发生。PM 经工单需求模板提供内容（字段与 intent 章节一一对应），格式转换由 DRI / Agent 代劳。
2. 顺序铁律：intent.md（Plan）→ spec.md（Design）→ plan.md（动手编码前）。实现计划必须知道"改哪些模块、有没有 DDL、风险在哪"——这些是设计决策的输出，所以在 spec 定稿之后写，模板见 Build 章节。不允许在 spec 之前凭预测填模块清单和数据库变更。
3. 自己先过一遍"陌生人测试"：没参与讨论的人拿到 intent + spec 能直接做吗？不能就补。
4. 用 Agent 的 Plan Mode 启动，让它先输出实现计划，你确认后再让它写代码。

怎么做

1. 让 Agent 先列 2-3 个候选方案和各自的取舍，不要让它直接选一个就写。
2. 涉及订单、支付、库存、资金这些核心链路的改动，方案必须给资深工程师过一眼。
3. 重要决策写在 MR 描述里：为什么这么做、放弃了什么、什么条件下会推翻。
4. 明确告诉 Agent 不能动什么：不要改 legacy 模块、不要新增依赖、不要破坏现有接口契约。
5. spec.md 评审通过后，DRI 基于 spec 写 plan.md（实现步骤、模块改动清单、DDL 及回滚、验收标准到测试的映射）——模块与 DB 声明是对 spec 的转抄，不是预测。模板见 Build 章节。

每次新会话必须做的事

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 懂代码结构，但不懂业务语义。

• 放什么：业务场景说明、状态机、交易规则、接口契约——这些是人审受控文档：只能随代码同 MR 由人更新，Agent 不得自行改写（Agent 是 docs 最重度的消费者，不能既当读者又当作者）
• 怎么更新：改业务逻辑必须先改 docs 再改代码，同一个 MR。不允许只改代码不改 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 排查、生成回滚脚本、MR 描述模板等

# 假设主仓库在 ~/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. 各自开发、各自提 MR
# 5. 任务完成后清理 worktree
git worktree remove ../order-A
git worktree remove ../order-B

plan.md 模板（动手编码前写，基于 spec.md 转抄）

plan.md 在 spec.md 评审通过后、编码前撰写。评审 plan = 校验 DRI 是否读懂 spec。

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

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

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

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

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

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

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

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

1. 先出计划（plan.md）：工程师审计划，消除模糊后再动手。先改文档返工更轻。审的时候核对：模块清单与 DB 变更是否与 spec.md 一致（转抄而非预测）——不一致要么改 spec 走设计评审，要么改 plan，不许两边各说各话。
2. AI 写代码：按计划一步步写，每步跑测试。
3. AI 自查：写完自动跑测试 + 构建，全部通过才算完成。不通过自己改，最多 5 轮。

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

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

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

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

怎么做

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

AI 写的测试，信多少？

Evals 评测闭环（核心场景）

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

现状（v2.3.1 纠偏，2026-10 盘点）：gtsp-wop-service 的单测层变异门禁已上线（PIT：3233 变异体、击杀率 89-92%、pre-push 阈值 89）——"用变异证明用例有效"的纪律已在单测层运转；但 agent 任务级 Evals 评测集尚未建立，本节为设计目标，起步需先摸底用例来源（历史 bug 回放是最便宜的第一批）。

• 同等待遇（3 个月内接线，排期第一优先）：代码变更和 Agent 配置变更（AGENTS.md / review-scope.yml / Skills / Hooks 改动）一视同仁都要跑 Evals——当前 CI 仅代码变更触发。接线前，review-scope.yml 的 TL 闸门是配置治理的唯一防线，这也是把接线排第一的原因
• 持续回归：不是提测前才跑，每次 MR 自动跑
• 掉分禁合并：通过率比基线低就红，不许强合。基线三条纪律：① 初始基线 = 评测集首次全量跑通率，记录在仓（如 evals/baseline.json）；② 基线只升不降，下调需 MR + Tech Lead approve 并留痕；③ 新用例合入时基线重算为 min(当前通过率, 旧基线)，新用例不得放松旧约束
• 用例上岗纪律：一个用例必须先证明自己能抓差异，才能参与基线——从未抓到过差异的评测集配上"掉分禁合并"，等于用随机数挡合并：拦不住真 bug，却会拦住真功能。两条路径任选：① 回放历史 bug（线上事故转的用例天然合格）；② mutation 变异测试——对被测代码做人工变异（改边界、删幂等检查），用例必须变红。从未变红的新用例挂「观察」状态：不进基线、不触发禁合并。已有集子的仓先做一轮变异体检（一天工作量），抓不到差异的标「观察」；集子还没建的仓（现状 = 多数），首批用例从历史 bug 回放起步、天然走路径①
• 线上 bug 转 Evals：每次线上修复后，补一个评测用例进集子里，下次自动检测
• 用例退役：连续 6 个月未捕获差异且业务已下线的用例，评测集 owner 可提 MR 退役并留痕（防止集子只增不减变成新屎山）

发布流程（务必照做）

1. 提 MR → master：feature 开发完成后提 MR 合到 master。MR 只作为载体——人审 + CI 构建，不合并（Codeup 分支保护锁定合并：prod 验证通过前谁都不能点合并）。
2. MR → dev：MR 流水线自动构建，部署 MR 源分支到 dev，你自己验证。
3. uat 验证：单特性——通知测试部署该 MR 的构建产物到 uat；多特性同时上线——从 master 切 release/x.x.x，把要一起上线的 feature 分支合入，测试部署 release。release 只修 bug，不加新功能；bug fix 一律在 release 分支上直接提交（保持 uat 验证对象 = 发布对象），随 release → master 的 MR 合回主干——不允许只存在于 release 的提交。
4. prod 发布：uat 通过后，运维把同一构建产物发到生产，发布后盯 30 分钟监控。
5. 合并收尾（最后一步）：prod 验证通过后——单特性点合并该 MR；多特性提 release → master 的 MR 合入、打版本标签、删 release 分支，本批各 feature 的 MR 标注"已随 release/x.x.x 合入"后关闭，不留挂起的僵尸 MR。合并前 master 不动，保证 master 永远等于线上。
6. 同步 feature：master 前进后，通知未上线的 feature 分支 git rebase master——所有分支都从 master 切出，主干动了自己要跟上。

紧急回滚怎么做

哪些路径必须资深 review

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

翻车复盘三步闭环

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

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

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