三层架构，一个目标：让 AI 编程可控、可预测、可工程化

回顾：三个工具解决三个问题

到目前为止，你已经认识了三个工具：

工具	核心问题	解决方案
Superpowers	AI 不按流程来	7步工作流 + 14个 Skills
OpenSpec	AI 理解偏差	规范驱动 + 三步工作流
Harness	AI 行为失控	三大支柱 + 三级约束

但问题来了：为什么要三个？一个不够吗？

---

为什么一个不够

尝试用OpenSpec 解决所有问题

场景：AI 写代码太快，不写测试

OpenSpec 能解决吗？
→ tasks.md 里写"必须写测试"

结果：
→ AI 看到规范，但执行时还是跳过了
→ OpenSpec 只能定义"做什么"，管不了"怎么做"

尝试用 Superpowers 解决所有问题

场景：AI 理解错了需求，一路狂奔

Superpowers 能解决吗？
→ brainstorm skill 会澄清需求

结果：
→ 澄清后的需求还是只存在于"对话"中
→ 没有规范文档，后面还是容易跑偏

尝试用 Harness 解决所有问题

场景：需求变更频繁，AI 改来改去

Harness 能解决吗？
→ CLAUDE.md 定义约束

结果：
→ 约束的是"行为边界"，管不了"需求内容"
→ 需求对了，约束才有意义

---

三层架构的本质

三个工具各有职责，形成三层架构：

框架名称	层级	解决问题	核心价值	输出产物	作用时机
OpenSpec	需求层	AI 理解偏差	对齐需求	规范文档 (proposal/ specs/ design/ tasks)	开发前
Superpowers	流程层	AI 不按流程来	标准化执行	工作流状态	开发中
Harness Engineering	约束层	AI 行为失控	行为可控	约束规则 + 验证机制	全程

---

信息流转：三层如何协同

完整的开发流程

1. 需求阶段（OpenSpec主导）
   │
   │  /opsx:propose创建规范文档
   │  proposal / specs / design / tasks
   │
   ▼
2. 执行阶段（Superpowers 主导，Harness 保障）
   │
   │  brainstorm（读取 OpenSpec 规范）
   │  plan（拆分 tasks）
   │  tdd（测试先行）
   │  implement（写代码）
   │  review（代码审查）
   │  │
   │  └─→ Harness 全程约束：
   │      - CLAUDE.md 定义代码规范
   │      - 测试套件验证边界
   │      - Hooks 自动检查
   │
   ▼
3. 完成阶段（OpenSpec 收尾）
   │
   │  /opsx:archive 归档变更
   │  更新主规范文档
   │
   ▼
4. 维护阶段（Harness 持续）
   │
   │  熵管理：保持系统健康
   │
   ▼
   ✓交付

关键数据流

流程集成：从规范到执行

OpenSpec 输出产物	流向	Superpowers 技能输入
proposal.md	→	brainstorm skill
specs/	→	tdd skill
design.md	→	implement skill
tasks.md	→	plan skill

约束与验证：Harness 机制

机制类型	来源/依据	作用对象/执行点	具体约束/验证内容
约束源 (基于 OpenSpec)	specs/ tasks.md design.md	──→	架构约束 (CLAUDE.md) 测试边界 命名规范
验证点 (基于 Superpowers)	tdd skill review skill implement skill	──→	测试套件验证 Hook 自动检查 代码风格约束

---

三层协作的必要性

为什么缺一层都不行

只有 OpenSpec + Superpowers（缺 Harness）

问题场景：
OpenSpec 定义规范：使用 PostgreSQL
Superpowers 执行流程：写代码

缺失 Harness：
→ AI 可能还是写成了 MongoDB
→ 没有约束机制强制检查
→ 规范是规范，执行是执行

只有 OpenSpec + Harness（缺 Superpowers）

问题场景：
OpenSpec 定义规范：实现登录功能
Harness 定义约束：TypeScript strict

缺失 Superpowers：
→ AI 没有标准流程可遵循
→ 可能先写代码再写测试
→ 可能跳过代码审查
→ 流程混乱

只有 Superpowers + Harness（缺 OpenSpec）

问题场景：
Superpowers 执行流程：brainstorm → plan → tdd
Harness 定义约束：测试覆盖率 > 80%

缺失 OpenSpec：
→ brainstorm 澄清的需求只存在于对话中
→ 没有规范文档可追溯
→ 需求变更时难以定位

---

适用场景判断

场景矩阵

项目周期\ 需求复杂度	低	高
低	只需要 Harness	OpenSpec + Harness
高	Superpowers + Harness	铁三角全套

场景一：一次性小工具

特征：

• 项目周期：短（<1周）
• 需求复杂度：低
• 团队规模：1人

推荐：只需要 Harness

原因：
- 需求简单，OpenSpec 可以省略
- 流程简单，Superpowers 可以省略
- 但代码规范必须有（Harness）

场景二：中型项目

特征：

• 项目周期：中（1-3个月）
• 需求复杂度：中
• 团队规模：2-5人

推荐：OpenSpec + Harness

原因：
- 需求需要规范管理
- 流程不太复杂，可以不用 Superpowers
- 约束必须要有（多人协作）

场景三：长期大型项目

特征：

• 项目周期：长（>3个月）
• 需求复杂度：高
• 团队规模：5人以上

推荐：铁三角全套

原因：
- 需求复杂，必须用 OpenSpec 规范化
- 流程复杂，必须用 Superpowers 标准化
- 团队协作，必须用 Harness 约束化

---

三层融合的最佳实践

实践一：启动项目的标准流程

Step 1: 搭建 Harness（1小时）
├── 编写 CLAUDE.md
├── 配置 Pre-commit Hook
└── 创建基础测试

Step 2: 初始化 OpenSpec（15分钟）
├── openspec init
└── 创建第一个变更

Step 3: 安装 Superpowers（5分钟）
└── /plugin install superpowers

Step 4: 创建第一个功能
├── /opsx:propose feature-1（OpenSpec）
├── AI 自动进入 brainstorming（Superpowers）
├── 按 CLAUDE.md 约束执行
└── /opsx:archive 归档

实践二：日常开发的标准流程

1. 接到需求
   → /opsx:propose 创建变更（OpenSpec）

2. AI 自动进入 brainstorming
   → 澄清需求、确认设计（Superpowers）

3. 确认规范后执行
   → plan → tdd → implement → review（Superpowers）
   → 全程遵守 CLAUDE.md 约束

4. 完成后归档
   → /opsx:archive（OpenSpec）

5. 定期熵管理
   → 检查约束、清理债务

实践三：团队协作的标准流程

层级	适用范围	具体规范内容
L1	企业规范	代码风格基线、安全规范
L2	团队规范	技术栈选择、架构模式
L3	项目规范	OpenSpec 变更记录、项目特定约束

---

常见误区

误区一：三个都要用，否则不完整

纠正：缺哪层用哪层，不要过度工程化。

简单脚本 → 只用 Harness
中型项目 → OpenSpec + Harness
大型项目 → 铁三角全套

误区二：三层是串行的，必须按顺序来

纠正：三层是协同的，信息实时流转。

OpenSpec 定义规范 → Superpowers 读取执行
              ↑                ↓
              └── Harness 约束 ┘

误区三：三层会大大增加开发时间

纠正：前期投入，后期省时间。

无三层：
- 前期快，后期慢（返工、重构、维护）

有三层：
- 前期稍慢，后期快（规范清晰、流程标准、约束明确）

---

下一步

到此为止，你已经掌握了"铁三角"的核心概念：

1. 三个工具各有职责：需求/流程/约束
2. 三层架构缺一不可：协同才能完整
3. 适用场景因项目而异：按需选择

接下来的篇章，我们将进入三维融合实战，通过真实案例演示三层如何协同工作。

下一篇：完整流程演示——一个项目从需求到交付的三层协同

---

扩展阅读

• SuperpowersGitHub
• OpenSpec 官网
• Claude Code 文档