AI 协作工作流

约 1808 字大约 6 分钟

AI WORKFLOW · FROM PROMPT TO PROOF

“让 AI 写一个功能”不是工作流，只是一次请求。可重复的工作流必须包含：正确的上下文、明确的边界、最小的改动、可执行的验收。这一页给出一套可以直接照做的六步循环。

一、六步循环

① 定位边界  →  ② 组装上下文  →  ③ 先要计划
                                      │
                                      ▼
⑥ 记录决策  ←  ⑤ 审查与验收  ←  ④ 小步实现

步骤	你要做的事	产出
① 定位边界	判断属于哪个域、是否需要新模块	一个明确的落点
② 组装上下文	只给相关规范、实体、控制器、测试	一份可复用的上下文包
③ 先要计划	让 AI 输出文件清单与改动理由	可审查的计划
④ 小步实现	一次只改一个关注点	可编译、可回滚的 diff
⑤ 审查与验收	跑编译、单测、架构测试	通过或明确的失败原因
⑥ 记录决策	更新 README / AGENTS / 事件登记	下一次可复用的知识

二、上下文包：少而准，比多更重要

不要把所有文档一股脑塞给模型。一个有效的上下文包通常只有五类文件：

tg-context/
├── 01-task.md              这次要改什么、不改什么
├── 02-rules.md             AGENTS.md 中与本任务相关的硬约束
├── 03-module.md            目标模块 README（职责、表前缀、已有能力）
├── 04-templates/           同域 entity / controller / service 各一份
└── 05-contracts/           相关 *-api 接口、事件契约、DTO

取文件的顺序

docs/README.md —— 确认阅读路径；
AGENTS.md —— 找与本次任务相关的硬性规则；
目标模块 README —— 确认职责与已有实现；
同域实体、Controller、Service —— 让生成结果“像这个仓库”；
相关 *-api 契约 —— 确认跨模块调用方式；
现有测试 —— 确认验收标准。

不该放进上下文的东西

与任务无关的几十个 Controller；
生产配置、密钥、真实用户数据；
已经废弃的旧版本代码；
没有边界的“整个仓库压缩包”。

上下文不是越多越好

上下文越长，模型越容易抓住错误的重心。把“相关”控制在 5～8 个文件，比塞进 50 个文件更有效。

三、先要计划，不要先要代码

计划提示词模板

你是 TG-boot 的开发助手。请先只输出计划，不要写代码。

任务：{一句话描述需求}

约束：
- 跨模块只能使用 *-api 契约或 MQ 事件；
- 实体继承 BaseEntity，业务主键使用 *Code；
- 状态字段遵循 *StatusCode / *ProcessCode 约定；
- 不新增跨域 *-biz 依赖；
- 不修改与任务无关的文件。

请输出：
1. 归属模块与理由；
2. 需要新增/修改的文件清单；
3. 每个文件改什么、为什么；
4. 是否需要新契约或新事件；
5. 验收命令与预期结果；
6. 你不确定、需要我确认的点。

审查计划的四个问题

它是否把代码放进了错误的域？
它是否发明了框架里不存在的机制？
它是否遗漏了契约、事件登记或幂等？
它是否把“顺手重构”混进了本次任务？

只要有一个答案是“是”，先改计划，不要进入实现。

四、实现：一次只做一件事

推荐把实现拆成可独立验证的小步：

只加实体与 Mapper，编译；
只加 Service 与单元测试，跑测试；
只加 Controller 与接口文档，启动验证；
只加事件契约与消费者，跑集成测试；
只加 runner 装配，跑架构测试。

每一步都保持可编译、可回滚。不要一次性生成二十个文件，再祈祷它们能一起工作。

实现提示词模板

按已确认的计划实施第 {N} 步。

只允许修改这些文件：
- {file1}
- {file2}

必须遵守：
- {从 AGENTS.md 摘录的 3～5 条硬约束}

输出要求：
- 先给出 diff 摘要；
- 再给出完整文件内容；
- 最后列出你实际执行过的验收命令。

如果发现计划与仓库现状冲突，停止并说明，不要自行扩大改动范围。

五、把 AGENTS.md 当成“可执行规范”

TG-boot 的 AGENTS.md 不是写给人类看的欢迎页，而是给 AI 的硬约束清单。典型规则包括：

规则	错误示例	正确做法
实体继承 `BaseEntity`	自己写 `createTime`	继承统一基类
双主键	对外暴露 `id`	对外使用 `xxxCode`
布尔状态	`status = "YES"`	`"1"` / `"0"`，null 视为否
流程状态	把“审核中”塞进 `*StatusCode`	使用 `*ProcessCode`
字典字段	用 `*Constants` 静态类	枚举 `implements BaseEnum`
跨模块调用	注入他域 `*ServiceImpl`	注入 `Api**Service`
事务消息	事务内直接 publish	`publishAfterCommit`

在提示词里不要写“请遵守规范”，而要写具体规则 + 具体反例。模型对反例的敏感度通常更高。

六、验收：让“完成”有证据

一个功能至少要通过四类检查：

层级	命令 / 动作	通过标准
编译	`mvn -q -DskipTests compile`	无编译错误
单测	目标模块测试	新增逻辑有覆盖
架构	`mvn -pl spring-boot-starter-architecture-tests -am test`	无越界
运行	启动 runner，调用接口	返回符合契约

如果是前端或跨端任务，再补：

类型检查；
关键页面的移动端截图；
空态、错误态、加载态；
接口失败时的降级。

让 AI 自己写验收命令

在计划阶段就要求它列出“准备执行哪些命令、预期输出是什么”。实现完成后，再让它逐条报告实际结果。这样更容易发现“看起来完成、其实没跑”的情况。

七、审查清单

改动是否只落在计划允许的文件里？
是否新增了不必要的抽象或依赖？
实体、字段、枚举是否符合命名与状态约定？
跨模块调用是否只经过契约？
事件是否在事务提交后发布，消费者是否幂等？
是否补充了测试、README 或事件登记？
是否泄漏了密钥、真实数据或本地路径？

八、一个反例

需求：给“活动报名”加一个导出 Excel 的接口。

错误做法：

在 campaign-biz 里直接引入 spring-boot-starter-excel-biz；
自己写 POI 工具类；
在 Controller 里拼 SQL 查询报名人；
把导出逻辑塞进 system。

正确做法：

复用 spring-boot-starter-excel 的模板能力；
报名数据留在 campaign 域；
导出用例放在 campaign-biz，通过本域 Service 取数；
如果导出需要跨域用户信息，调用 ApiSysUserService，不直接查 sys_user；
补一条集成测试，验证模板字段与数据映射。

AI 的效率来自生成速度，AI 的可靠性来自反馈速度。工作流的意义，是让每一次生成都尽快碰到边界。 SMALL DIFF · FAST FEEDBACK