企业官网建设流程全解析

三层合起来才是闭环：AI 编程铁三角怎么一起用

本文是「AI 编程铁三角」系列的第四篇，也是收束篇。
前三篇分别讲了三层：Harness 给 Agent 准备可工作的工程环境，OpenSpec 把需求变成可执行规格，Superpowers 按流程完成代码变更。
本篇不再展开任何一层的细节，而是回答一个问题：这三层为什么必须一起上，少一层会怎样，以及它们在一个真实变更里如何前后衔接。

一、先说清楚：铁三角不是三个工具，是三个控制面

很多人会把铁三角理解成"三个工具选一个用"。这是误解。

铁三角的三层不是互相替代的工具，而是三个互补的控制面：

• OpenSpec固化需求和设计——回答"做什么、为什么、边界在哪"
• Superpowers把工作组织成可执行流程——回答"怎么做、按什么顺序、每步留什么证据"
• Harness用上下文、权限、脚本和质量门禁约束 Agent 行为——回答"在什么环境里做、不能碰什么、怎么证明做对了"

三者共同形成「规范—执行—验证」的闭环。判断是否落地成功，只看三类职责是否完整，不看工具名字是否一致——OpenSpec 可以由企业已有的需求/设计模板实现，Superpowers 可以由 Skills、命令和工作流脚本实现，Harness 可以由AGENTS.md、CLAUDE.md、CI、Pre-commit、权限网关和内部知识库共同构成。

二、少一层会怎样

把三层拆开看，每一层缺失都会导致一类典型问题。

只用 Harness，没有 OpenSpec

Agent 在一个约束良好的仓库里跑得很快，但跑的是谁的需求不清楚。没有规格，Agent 会自己补齐"合理但不一定正确"的默认值：失败次数按用户名还是按来源？表满走 fail-open 还是 fail-close？时钟回绕怎么处理？这些决策每个都影响系统行为，却都藏在 Agent 的"合理默认"里，审查者很难发现。

症状：代码跑得快、测试也过，但做错了事。

只用 OpenSpec，没有 Superpowers

规格写得很清楚，但 Agent 执行时跳步：直接改代码、一次改太多、忽略失败测试、看到报错连续打补丁让代码"碰巧通过"、修复症状而不是根因。规格再好，没有流程约束，Agent 照样会在执行环节把规格意图走样。

症状：规格很完整，代码却对不上规格，审查时才发现漏了关键边界。

只用 Superpowers，没有 Harness

流程很规范：先写失败测试、小步提交、两轮审查。但 Agent 跑在错误分支、脏工作区、过期构建结果上，能修改不该改的目录，能外发不该外发的数据。流程约束了"怎么改"，却约束不了"在哪改、能碰什么"。

症状：流程都对，但环境失控，证据不可信。

三层都没有

这就是大多数团队上 AI Coding 的现状：先装工具，再让开发者自行摸索。每个人用法不同，Agent 反复猜测构建方式和目录边界，最终形成大量不可复用的对话，风险被放大而不是被控制。

三、三层之间的数据流

三层不是平行关系，而是有明确的数据流：

OpenSpec 产物 ──► Superpowers 任务输入 │ ▼ 代码 + 测试 │ ▼ Harness 持续约束（上下文/权限/门禁） │ ▼ 验证结果回写变更记录 ──► 归档

• OpenSpec 的产物（proposal / behavior / design / tasks）是 Superpowers 的输入。
• Superpowers 产生的代码和测试接受 Harness 的持续约束。
• 验证结果再回写变更记录并完成归档。

这条数据流的关键在于单向依赖：Superpowers 读 OpenSpec，但 OpenSpec 不依赖 Superpowers 的实现细节；Harness 约束 Superpowers 的执行，但 Superpowers 不负责定义 Harness 的规则。每一层只对自己的职责负责，边界清晰。

四、一个变更里三层如何衔接

用一个防暴力破解的变更走一遍，看三层如何前后衔接。

阶段一：Harness 先行（变更开始前）

Agent 开始任务前，先跑scripts/context.sh，拿到当前分支、基线测试、工具链版本。AGENTS.md告诉它：不得修改third_party/、不得改变对外 API、数据面热路径禁止动态内存分配。PreToolUse Hook 拦住任何试图写入禁止目录的动作。

这一步的意义：Agent 在一个可约束的环境里开始工作，边界由技术控制，不靠口头承诺。

阶段二：OpenSpec 固化决策（编码前）

变更目录openspec/changes/add-mgmt-bruteforce-guard/里有四类产物：

• proposal.md：为什么做、范围、影响、风险等级 L3
• specs/behavior.md：失败 N 次锁定、窗口滚动、表满策略
• design.md：auth_guard_check()接口契约、状态机、并发模型、所有权
• tasks.md：小步任务和验证命令

规格评审确认：Agent 可以在不发明任何关键决策的前提下开始工作。内存分配失败走 fail-close、时钟回绕由 time 模块统一处理、HA 切换时状态如何同步——这些决策都写清了，不是 Agent 自选。

这一步的意义：所有会影响系统行为的决策，在编码前被看见。

阶段三：Superpowers 按流程执行（编码中）

Agent 按九步工作流推进：

1. 读取规范与上下文（Harness 提供的CONTEXT.md+ OpenSpec 的变更目录）
2. 风险分级确认（L3，公开接口变化需人工审批）
3. 编写任务计划（基于tasks.md）
4. 先写失败测试（RED）——test_lock_user_when_failures_reach_threshold
5. 实现至通过（GREEN）
6. 重构（REFACTOR）
7. 静态分析与增量验证（verify_changed.sh）
8. 代码审查两轮（先规格符合性，再代码质量）
9. 目标侧验证与分支收尾

每个任务 15–60 分钟，独立可编译可测试。完成报告引用真实命令和返回码，不是"代码看起来正确"。

这一步的意义：每一步都产生可审查证据，Agent 不能跳步。

阶段四：归档（变更结束后）

变更目录移动到archive/，归档包包含最终规格、审查意见、CI 链接、设备报告、性能数据、已知限制、回滚说明。后续新增"按租户策略"时，以该归档为基线创建新变更，不直接修改历史记录。

这一步的意义：任何时刻都能回答"这段代码当年为什么这么写"。

五、三层各自的"到位标准"

把三层的自检问题放一起，就是铁三角的到位标准：

Harness 到位了吗？

1. Agent 一条命令能否拿到当前分支、基线测试和工具链版本？
2. Agent 试图修改禁止目录或改变对外 API 时，会不会被自动阻断？
3. 每次任务结束时，Agent 能不能列出验证命令和返回码？

OpenSpec 到位了吗？

1. 读完规格，能不能在不发明任何关键决策的前提下开始写测试？
2. 每条行为规格，是否都有可执行的验证命令对应？
3. 内存分配失败、表满、时钟回绕、HA 切换这些边界，规格里写清了吗？

Superpowers 到位了吗？

1. Agent 是先写失败测试再写实现，还是直接改代码？
2. 审查是分两轮（先规格符合性、再代码质量），还是混在一起看实现细节？
3. 完成报告引用的是真实命令和返回码，还是"代码逻辑看起来正确"？

九个问题都能答"是"，铁三角才算闭环。任何一层缺位，都会在某个环节把风险放大。

六、不必绑定具体产品

三层是职责划分，不是工具绑定。OpenSpec 可以由企业已有的需求/设计模板实现，Superpowers 可以由 Skills、命令和工作流脚本实现，Harness 可以由AGENTS.md、CLAUDE.md、CI、Pre-commit、权限网关和内部知识库共同构成。不同 Agent 对指令文件名称和加载规则不同，建议以一份平台无关的源文件为准，再同步到各工具入口（详见第一篇）。

判断是否落地成功，只看三类职责是否完整，不看工具名字是否一致。

七、结语：从"偶尔写对"到"稳定产出"

AI 能显著缩短代码生成、测试编写、信息检索和问题分析的时间，但它不会自动理解企业架构，也不会自然承担质量责任。

真正可持续的做法，是把 Agent 放入已有的软件工程体系，并用规格、流程和约束把其能力转化为稳定产出：

• Harness让上下文、权限和门禁在整个生命周期持续生效——解决"在哪做、能碰什么"
• OpenSpec让关键决策在编码前被看见——解决"做什么、边界在哪"
• Superpowers让工作按小步、TDD、审查和验证推进——解决"怎么做、怎么证明"

三者结合后，AI 才从"偶尔能写对代码的助手"转变为"受控、可审计、可复用的研发执行力"。

这不是一次培训能落地的，而是靠仓库改造、试点场景、门禁建设和指标复盘逐步形成。推广顺序应从具体问题出发，避免先建设一个大而全平台。每个阶段都要以可工作的仓库和真实变更为验收，避免只完成制度、模板和工具安装。

铁三角的真正价值，不在于让 AI 写得更快，而在于让 AI 的产出可被信任。