AI 开发工作流

现在AI发展飞快，似乎每个团队都在干这样几件事：

  1. 体验AI编码
  2. 构建团队的知识库
  3. 构建团队的开发工作流

AI编码确实很快，但往往结果写了一大堆发现谬以千里，问题就是在没有给AI加约束，导致它干起来天马行空。

下面以开源项目 superpowers 、openspec和团队内的AI工作流为样本,拆解"给 AI 编码套上工作流"这件事到底在约束什么、怎么约束、以及边界在哪。

一、AI 工作流约束的到底是什么

第一次做"AI 开发工作流",脑子里更多想的是:把资深专家会做的步骤写成清单,让 AI 照着做。

先对齐需求、再出技术方案、先写测试、写完要 review——这确实是资深专家和新手的差别所在。新手拿到需求就开写,资深的先问"验收标准是什么";新手一条路走到黑,资深的先列两个方案再选;新手写完就说"好了",资深的知道"没测过不算完"。

把这些"资深工程师不会省的步骤"固化成 AI 必须执行的清单,是对的。但这只是三层里的第一层。如果只做到这一层,产出的东西和一份《研发最佳实践.md》没有区别——而那种文档,团队里从来没人真正照着执行过。

真正让 AI 工作流区别于"一份最佳实践文档"的,是另外两层:

  1. 把资深专家的隐性判断显式化成清单 —— 大多数人只想到这一层
  2. 叠加一层专门对抗 AI"合理化"倾向的护栏 —— 这一层最独特
  3. 强制留痕,让整个过程可审计 —— 这一层决定它能不能规模化

下面逐层展开,每一层都给出可以直接抄的写法。

二、第一层:把隐性判断显式化成清单

2.1 一个节点 = 一份"资深工程师不会省的动作"清单

以 prd-review(PRD 审视)节点为例。它的核心 Checklist 长这样:

1. 读 lessons/*.md,检查有没有相关的历史踩坑
2. 查领域知识库,把结论内化为评审参考
3. 完整读一遍 PRD,不要边读边改
4. 提炼 4 字段:背景 / 目标 / 验收标准 / 风险
5. 识别缺失:任一字段无法从原文回答 → STOP + 向用户提问
6. 填 proposal.md
7. 自检:TODO / XXX / ? 占位符是否全部清除
8. 汇报"PRD 审视完成",等待用户显式确认

注意这些动作里没有一条是"高深技术"。它们全是资深工程师默认会做、但从不写下来的动作。工作流做的事,就是把这些"默会知识(tacit knowledge)“逼成一条条显式指令。

2.2 给"模糊的好标准"补上可判定的定义

隐性判断显式化最难的地方,是"标准本身很模糊”。资深工程师说"验收标准要写清楚",但"清楚"是什么?AI 不知道,会糊弄过去。

所以好的工作流会把模糊标准翻译成可判定的规则。同样是 prd-review,它给"可回答"下了硬定义:

"可回答"的最低标准:
- 背景:能说清"为什么现在要做"(不是"需要这个功能")
- 目标:至少 1 个可量化指标(数字/百分比/时间)
- 验收标准:每条满足 SMART
- 风险:至少 1 条非"无"的风险描述

字段内容仅为"待定"/"后续补充"等占位 → 视为缺失。

tdd-implementation 更极端,直接把"测试够不够"变成一个数字门槛:

- 增量代码行覆盖率 ≥ 85% → 通过
- 增量代码行覆盖率 < 85% → STOP,补测试直到达标

经验法则:任何一条清单项,如果 AI 能用"我觉得差不多了"绕过,它就还不算显式化。 显式化的终点是"可判定"——要么给数字,要么给可枚举的判定条件。

2.3 用依赖图定义节点顺序,而不是靠 AI 记忆

节点之间的先后关系,不要写在散文里,要写成机器可读的依赖声明。workflow.yaml 里每个节点都有:

tdd-implementation:
  skill: skills/tdd-implementation/SKILL.md
  requires: [execution-plan]      # 前置依赖
  generates: "src/**"             # 产物
  gate: |                         # 进入下一节点的必要条件
    所有 execution-plan 任务已完成
    增量代码行覆盖率 >= 85%

requires 不是运行时校验(纯 Bash 仓库没有调度引擎),而是给 AI 的"进入前检查":tdd 节点入口会校验 execution-plan 的产物在不在,不在就 STOP 回退。这样节点顺序就不依赖 AI"记得"上一步做过什么。

三、第二层:对抗 AI 的"合理化"

3.1 为什么真人不需要这层,AI 需要

一个真人资深工程师,你告诉他"要写测试",他会照做。但 AI 有一个真人没有的失效模式——它会在推理过程里给自己找借口跳过流程,而且找的借口每一条听起来都很合理:

  • “这个改动太小了,不需要测试”
  • “用户赶时间,先写代码后补文档”
  • “需求已经很清楚了,提炼 7 字段是多余的”
  • “覆盖率 80% 差不多了”

这些话都是 AI 自己说服自己的。它不是恶意跳过,是"理性地"论证出跳过是合理的。所以工作流约束的重心,从"教它做专家该做的事",偏移到了"预判它会用哪些理由偷懒,然后逐条封死"。

这也是为什么 superpowers 的入口 skill using-superpowers 里有一整张表,列的全是 AI 会冒出来的念头:

你的念头 现实
“这只是个简单问题” 问题也是任务。检查 skill。
“我需要先了解上下文” skill 检查在澄清问题之前。
“让我先探索一下代码库” skill 会告诉你怎么探索。先查。
“这个 skill 有点小题大做” 简单的事会变复杂。用它。
“我记得这个 skill” skill 会演进。读当前版本。

3.2 三件套写法:反模式表 + 合理化对照表 + Red Flags

这是对抗合理化最实用的模板,每个节点都值得配齐:

(1) 反模式表 —— 列出"错误的做法长什么样",让 AI 能自我识别:

## 反模式
- ❌ 自己脑补范围填 proposal(编造事实)
- ❌ 把 PRD 原文复制粘贴到 proposal(没做提炼)
- ❌ 未获批准就创建 tech-design.md(违反 HARD-GATE)
- ❌ 验收标准写"功能正常"(不可度量)

(2) 合理化对照表 —— 左边是 AI 会说服自己的话,右边是拆穿它:

合理化对照表

你在想什么 实际情况
“用户催得急,先写代码再补方案” HARD-GATE 不可绕过。没有批准的方案 = 没有方向的编码
“先写代码再补测试,效果一样” 不一样。后补的测试是"验证我写了什么",先写是"定义我要什么"
“覆盖率 80% 差不多了” HARD-GATE 是 85%,没有"差不多"。补测试
“用户说’继续吧’就是批准” 不是。HARD-GATE 要求"确认"/“OK"等显式表述

(3) Red Flags —— 一句话总结:出现这些念头本身就是警报:

## Red Flags — 立即停下
如果你正在想以下任何一条,说明你在合理化跳过流程:
- "这个需求太简单不需要 proposal"
- "用户赶时间,先写代码再补文档"

以上全部意味着:停下,按 Checklist 走。

写这三件套的诀窍:不要凭空想 AI 会怎么偷懒,去翻你自己和 AI 的真实对话记录。 AI 每一次说"其实这个可以简化"“我觉得没必要”,就是一条该补进对照表的素材。

3.3 HARD-GATE:把"人的批准"设成不可绕过的物理闸门

对抗合理化最强的一招,是设置必须真人点头才能通过的闸门,并且把"什么算点头"定义死:

## <HARD-GATE>
proposal.md 未获得用户明确批准前,不得创建 tech-design.md。

"明确批准"指用户显式回复"确认"/"OK"/"进入下一步",
不是"这样也行"、"继续吧"等模糊表述。

关键在最后一句。如果不把"模糊表述不算批准"写死,AI 会把用户随口一句"嗯继续吧"解读成放行信号。HARD-GATE 的价值不在于"要批准”,而在于堵死 AI 对’什么是批准’的自由解释。

在整条 lite 流程(prd → tech → plan → tdd → review)里,HARD-GATE 卡在两个位置:

  • prd-review 出口:不确认不许进技术方案
  • tech-design 出口:未批准不得写代码

所以流程看起来"自己在跑",实际是每一棒交出去前先撞一次 gate,gate 放行才继续。

3.4 用"强制过渡"接力,但接力棒前面永远有 gate

一个容易被忽略的设计:这套工作流没有后台调度引擎,流程能"自己往下走",靠的是每个节点 Checklist 的最后一步,硬编码了"立即加载下一个节点"的指令:

【强制过渡】必须立即:调用 Skill 工具加载 tech-design →
执行其入口校验 → 按其 Checklist 开始 tech-design 节点。
禁止跳过 tech-design 直接写代码。

这句话让 AI 执行完当前节点后,自动把下一个节点的指令读进来接着执行。但它永远排在 gate 后面——先撞闸门,放行了才交棒。“自动接力"和"人工闸门"的组合,是这类工作流既流畅又可控的关键:不需要人一步步喊"下一步”,但关键节点必须人点头。

四、第三层:强制留痕,让过程可审计

4.1 为什么单个专家不需要这层,团队需要

一个真人专家做判断,大多在脑子里、在口头评审里完成,是隐性的、事后无法复盘的。他不需要给自己写审计日志。

但当你要规模化地托管 AI 的产出——十几个人各自让 AI 写代码,你怎么知道哪次靠谱、哪次在糊弄?这时"过程留痕"就从可选项变成必需品。

4.2 两种留痕:产物落盘 + 指标采集

(1) 每个节点强制产出文件,而不是只在对话里说说:

节点 产物
prd-review docs/work/active/{slug}/proposal.md
tech-design docs/work/active/{slug}/tech-design.md
tdd-implementation src/** 代码改动
code-review docs/work/active/{slug}/code-review.md

文档和代码在同一个 PR 里联合评审。这样团队里其他人 review 的不只是结果,而是 AI 的思路——proposal 里的需求理解、tech-design 里的方案取舍,都摊在明面上。

4.3 偏离必须显式记录

留痕最后一环:允许偏离,但偏离必须写下来。code-review 节点强制——“实现与 tech-design 不一致,必须在 code-review 中显式记录原因”。

这一条很重要。它不是禁止 AI 变通(那不现实),而是要求变通留下痕迹。过程留痕,责任才可追。 这已经超出"专家水平"了,是"专家 + 可管理 + 可观测"——是团队规模化托管 AI 产出的前提。

五、把三层串起来:一个节点的完整骨架

综合下来,一个设计良好的工作流节点(SKILL.md)应该长这样:

---
name: 节点名
description: 什么场景下触发这个节点(写清"何时用/何时不用")
---

# 节点名

## 适用 / 不适用场景        ← 让 AI 判断该不该进这个节点

进入时执行: collect-metrics node-start ...   ← 第三层:留痕

## Checklist               ← 第一层:显式化的动作清单
1. ...
2. ...(每条尽量可判定,给数字或可枚举条件)

## <HARD-GATE>             ← 第二层:不可绕过的闸门 + 判定定义

## 反模式                  ← 第二层:错误做法长什么样
## 合理化对照表            ← 第二层:拆穿 AI 的借口
## Red Flags — 立即停下    ← 第二层:出现这些念头即警报

gate 通过后: collect-metrics gate-pass ...   ← 第三层:留痕
【强制过渡】立即加载下一节点 ...              ← 接力棒(排在 gate 之后)

## 输出契约                ← 第一层+第三层:产物路径 / 模板 / 必填字段

三层不是并列的功能,是层层加固:第一层定义"该做什么",第二层保证"不偷懒",第三层保证"可复盘"。

六、边界:这类约束的天花板在哪

写这类工作流之前,必须清楚它的极限,否则会高估它。

1. 天花板就是设计者的水平。 工作流没法让 AI 超过写 skill 的那个人——它只能保证 AI 不低于设计者定的下限。你们团队这套 workflow,本质是把某个资深工程师的判断标准,复制到每一次 AI 编码里。这既是价值,也是边界。skill 写错了、标准定低了,AI 就会稳定地产出错误/低质的结果。

2. 护栏能被"更聪明的合理化"绕过。 合理化对照表是"打地鼠"——你封死一条借口,AI 可能发明一条你没预料到的新借口。所以这类工作流需要持续迭代:定期回看 AI 的真实偏离,把新借口补进对照表。

3. 约束越重,context 预算消耗越大。 每个节点的 checklist、反模式、对照表都要占 AI 的上下文。所以要分档(profile):小改动走 lite,紧急修走 hotfix(跳过 PRD 和 tech-design),大项目才走 bootstrap。别用最重的流程杀鸡——那既浪费预算又拖慢迭代。

七、工作流编写清单

那么给自己团队写一个 AI 开发工作流,就按这个顺序做:

  1. 先定分档(profile):至少分"轻/重"两档,别让所有任务走同一条重流程。
  2. 画依赖图:先写机器可读的 workflow.yaml(节点 / requires / gate / 产物),它是地图。
  3. 逐节点写 Checklist:把资深工程师的隐性动作显式化,每条尽量可判定(给数字/可枚举条件)。
  4. 给每个节点配三件套:反模式表 + 合理化对照表 + Red Flags。素材来自你和 AI 的真实对话,不要凭空编。
  5. 在关键节点设 HARD-GATE:必须真人点头,并把"什么算点头"定义死。
  6. 加留痕:每个节点强制产出文件 + 关键节点采集指标 + 偏离必须记录。
  7. 加接力:每个节点结尾写"强制过渡到下一节点",但排在 gate 之后。
  8. 准备迭代机制:定期复盘 AI 的真实偏离,把新借口补进对照表。

结语

AI 开发工作流是把资深专家的隐性判断显式化成清单,再叠加一层专门对抗 AI 合理化倾向的护栏,最后强制留痕让整个过程可审计。