让 Agent 按流程改代码、每步留证据：Superpowers 的作用

半句唐诗

205人浏览 · 2026-07-21 17:54:20

半句唐诗 · 2026-07-21 17:54:20 发布

让 Agent 按流程改代码、每步留证据：Superpowers 的作用

本文是「AI 编程铁三角」系列的第三篇。
上一篇讲 OpenSpec：把需求变成可执行的规格。本篇讲 Superpowers：规格确定后，怎么把编码过程拆成明确技能，让每一步都产生可审查证据。
三层各司其职：Harness 提供可约束的工程环境，OpenSpec 提供可执行的规格，Superpowers 提供可审查的执行流程。下一篇会把三层合起来，看它们如何共同构成 AI 编程的完整闭环。

一、规格定了，Agent 还是会跳步

规格确定后，Agent 仍可能出问题：

直接改代码，不先写失败测试
一次改太多，中途丢失上下文
忽略失败测试，改测试让它通过
看到报错连续打补丁，让代码"碰巧通过"
修复症状而不是根因

Superpowers 的作用是把编码过程拆成明确技能，并让每一步都产生可审查证据。它不是"多写几个文档"，而是用流程约束 Agent 不能跳步。

二、九步工作流：比通用七步多两步

针对系统级软件研发，推荐使用九步工作流。相较通用七步流程，增加了风险分级和目标侧验证两个步骤：

读取规范与上下文
风险分级与审批点确认
编写任务计划
先写失败测试（RED）
实现至通过（GREEN）
重构（REFACTOR）
静态分析与增量验证
代码审查（两轮）
目标侧验证与分支收尾

任务入口应使用固定模板，避免一上来就说"帮我实现"。推荐入口包含：变更 ID、风险等级、规范路径、当前工作区、允许修改目录、禁止项、验证命令和人工审批点。下面以第二篇的防暴力破解变更为例：

任务：实现 add-mgmt-bruteforce-guard
风险等级：L3
规范：openspec/changes/add-mgmt-bruteforce-guard/
允许修改：src/mgmt/auth_guard/、tests/host/auth_guard/、docs/diagnostics/
禁止修改：src/ha/protocol/、src/config/schema/、third_party/
执行流程：读取规范 → 检查基线 → 编写计划 → TDD → 静态分析 → 代码审查
人工审批点：公开接口变化、持久化格式变化、HA 同步方案、目标板部署
完成定义：tasks 全部完成，verify_changed.sh 通过，设备测试报告已签字。

这个模板的关键是把允许修改、禁止修改、审批点、完成定义都写进任务入口。Agent 不需要猜边界，审查者也能据此逐条核对。

三、Worktree 与子代理：并行有边界

复杂变更可以用 Worktree 和子代理并行推进，但有规则：

子代理并行适合文件边界清晰的任务。例如一个改解析器、一个改测试语料，互不依赖。
若多个任务同时修改同一状态机或核心头文件，应由主代理串行推进，避免合并后语义冲突。
每个 Worktree 必须能独立编译和测试，否则并行没有意义。
子代理的产出必须由主代理整合并重跑验证，不能直接信任子代理的"已完成"声明。

并行的前提是边界清晰 + 独立可验证。边界模糊时，串行更安全。

四、TDD：分离逻辑与硬件副作用

TDD 的关键不是把所有硬件都模拟出来，而是把业务逻辑与硬件副作用分离。先在主机侧验证纯逻辑、状态机和边界，再用接口适配器、Fake 或 Mock 替代时钟、存储、消息、驱动和 SDK。

测试金字塔分四层：

主机单元测试：纯逻辑、状态机、边界。高频反馈。
组件/仿真测试：线程交互、消息时序、配置下发。
目标板测试：真实工具链、硬件、资源。
系统流量测试：最终安全效果和性能。

主机测试承担高频反馈，目标侧测试负责证明真实环境。AI 应优先生成和维护下层测试，再根据风险触发上层验证。

先写行为测试的样子：

// test_auth_guard.c（Unity/CMock 风格示例）
void test_lock_user_when_failures_reach_threshold(void)
{
    auth_guard_t guard;
    fake_time_set_ms(1000U);
    auth_guard_init(&guard, &test_config);

    auth_key_t key = make_key("admin", "10.0.0.8", AUTH_ENTRY_SSH);
    auth_guard_record_failure(&guard, &key, AUTH_FAIL_BAD_PASSWORD);
    auth_guard_record_failure(&guard, &key, AUTH_FAIL_BAD_PASSWORD);
    auth_guard_record_failure(&guard, &key, AUTH_FAIL_BAD_PASSWORD);

    TEST_ASSERT_EQUAL(AUTH_GUARD_LOCKED,
                      auth_guard_check(&guard, &key, fake_time_now_ms()));
}

对于难以主机测试的代码，不允许简单标注"无法测试"。必须说明不可测试的原因，并选择替代策略：

抽取纯逻辑
增加 Fake HAL
使用 QEMU/仿真
在目标板运行测试程序
通过静态证明和故障注入提供证据

五、系统化调试：先复现，再假设，最后改根因

AI 很容易在看到报错后连续尝试补丁，最终让代码"碰巧通过"。系统化调试要求：

建立稳定复现：不能稳定复现的 bug，无法证明修复有效。
提出可证伪假设：明确"我认为是 X 导致的，如果改 X 后问题消失，假设成立"。
收集最小证据：用日志、计数器、Trace 缩小范围，而不是全量打印。
只修改根因所在位置：症状修复会让真正的 bug 在更晚、更危险的地方暴露。

一个常见的反模式：Agent 看到 ASan 报越界，就在读取前加一个长度检查，测试通过了，提交。但根因可能是上游调用者传入了错误的缓冲区长度，而那个错误长度会在数据面热路径上造成更严重的后果。只改症状，根因就会在别处复发。

六、两轮代码审查：先对不对，再好不好

AI 生成代码的审查要分两轮：

第一轮：规格符合性。只看是否满足规格，防止"代码写得漂亮但做错了事"。
第二轮：代码质量、安全、性能、可维护性。

两轮混在一起时，审查者容易被实现细节带偏——看到一个漂亮的零拷贝实现就放行，却没发现它漏掉了规格要求的"表满时 fail-close"。

第一轮要逐条核对规格：

所有入口是否在密码校验前调用统一 check，并在失败后调用统一 record？
是否存在某个入口只做本地限速而绕过 Guard？
表满、分配失败、时钟异常、配置关闭和白名单行为是否与规格一致？
是否意外改变了外部错误提示、旧配置、HA 协议或认证返回码？
每条行为规格是否有测试和实现映射？

第二轮再看：

Hash key 是否稳定且不保存敏感明文；日志是否可被用户名中的控制字符注入？
时间差计算是否安全处理回绕；乘法和单位转换是否可能溢出？
锁顺序、分片映射和状态查询是否会死锁或长时间阻塞认证？
表满策略是否可被攻击者利用驱逐合法管理员状态？
关闭、重载、HA 切换和设备重启时对象是否完整释放或恢复？
热路径是否新增无界日志、动态分配或高复杂度遍历？

七、分支收尾：从干净环境重放

分支收尾前必须从干净环境重放关键命令。Agent 应生成完成报告，但报告只引用真实执行结果，不能以"代码逻辑看起来正确"代替运行证据。

完成报告的最低内容：

# Completion Report
- Change: add-mgmt-bruteforce-guard; 8 commits, all buildable
- Host: build PASS; unit 42/42; static analysis 0 new high/critical
- Dynamic/target: ASan/UBSan PASS; fuzz 0 crash; ARM64-A and x86_64-B PASS
- Performance/review: P99 +7 us within budget; all reviewers approved; no open issue

注意几个细节：