约束工程与规格驱动开发的实践心得

最近，我在Harness Engineering的指导下，尝试以SDD的开发模式，开发了多个项目，包括一个框架（基于Python）、一个Demo案例（基于Spring Boot与React）、一个企业级的真实项目——主计划排产功能（基于Spring Boot与Vue）、一个工业IDE开发的Demo（基于C++和QT）。

第一个项目在Cursor进行，遵循Spec-Kit提炼的SDD方法，但没有使用任何SDD框架；后面三个项目使用了Cursor+OpenSpec+Superpowers的组合，并在第三个项目运用了ui-ux-pro-max skill用以开发前端代码。为了体验Qoder的能力，最后一个项目在Qoder Quest模式+OpenSpec下做过一个版本。

之所以主要选择Cursor而非大家普遍推崇的Claude Code，主要因为我购买了它的Pro版本，最近一年都在使用Cursor，已经习惯了。

Harness Engineering作为一种AI时代的软件工程方法体系，在整个开发过程中都有所体现。在使用这些具体的IDE、开发框架以及Skill的配合下，我得到了一些体验和心得。

规约优先

对比多个项目的开发过程与结果，我发现一个事实：规约的质量会直接决定最终开发得到的结果。遵循良好的内容结构和编写格式显得尤为重要。

如果是开发一个demo案例，通过给OpenSpec的opsx:propose指令发送一个简单的项目说明，框架就可以智能地生成符合规范格式的spec；但对于垂直领域的真实项目而言，如此生成的Spec内容并不值得信任。唯一可以借鉴的是它规划spec的结构，以及采用Given-When-Then的场景描述方式。

我的做法是采用用例规约的形式由人工编写PRD，并要求团队对组成PRD的所有系统用例进行评审。只有通过了评审的系统用例，才会作为opsx:propose的输入，而propose输出的spec又会进一步进行评审，通过验收场景的方式对齐输入和输出的这两份规约，确保其意图和需求的一致性。

规约优先.png

敏捷开发思想仍然有效

敏捷开发思想中的部分实践仍然有效。在整个SDD过程中，我倾向于使用MVP（Minimal Viable Product，最小可用产品）的概念确定PRD的版本划分原则。一个MVP也是人机协作的闭环。它的输入就是通过团队集体评审通过的需求规约，它的输出则是可以真正运行的产品版本，这个能够运行的版本又可以交由团队进行验收测试。

不同之处在于速率和周期。在AI参与软件研发的过程中，研发效率得到接近10倍的提升，过去要发布一个版本可能是以月为单位，现在可以缩短为一周，甚至一天。敏捷的一个核心思想是快速反馈，正因为如此才划分了MVP和迭代（即Scrum的Sprint）。然而，快速反馈是需要成本的，包括测试、验收、评审和回顾，都需要一定的人力成本。随着反馈变得越来越快，既然一个MVP都可以在一周甚至一天内完成，更小时间单位的迭代就失去了存在的意义。当然，也可以说，一个MVP就是一个迭代。

在以“规约优先”的工程原则基础上，我们可以根据产品愿景、上线要求、功能完整程度等多个维度界定MVP，主动将整个产品的PRD划分为多个mvp版本，并以此作为OpenSpec进行提案（propose）的权威输入。这可以认为是时间维度对规约的划分。

空间维度上，规约可以按照product -> domain -> feature -> task的层次划分。若以OpenSpec为例，domain就是specs目录下的子目录，feature就是生成的spec.md文档，task则定义在tasks.md文档中。

时空维度的规约拆解如下所示：

时空维度的规约拆解.png

为何同时需要OpenSpec和Superpowers

OpenSpec本身就是一个完整的SDD框架，为何在使用了OpenSpec的基础上，还需要引入Superpowers？

虽说通过使用OpenSpec的opsx-apply指令，可以直接实现spec划分出来的tasks，且对比Superpowers的执行过程，OpenSpec的apply执行过程要更加直接而高效；却又因此显得不够精细，难以控制代码的质量。

Superpowers则引入了精细计划+检查点+子代理驱动的模式，遵循敏捷实践，针对每个task都严格遵循TDD的执行过程。如此既能通过测试及时获得反馈，也能通过对代码的及时重构，提升代码的质量。

实际执行过程中，我发现Superpowers的执行过程相对OpenSpec的apply要慢很多，感觉上，它也会消耗更多的token。然则，在软件研发过程中，有时候“慢就是快”，尤其针对相对复杂的业务逻辑开发，采用Superpowers的可控性明显更高。

二者的分工可以总结为：

• OpenSpec 负责锁定设计意图，把模糊的想法翻译成结构化的规格文档，同时提供对规格的版本管理。
• Superpowers完成方案探索，并负责针对每次迭代与发布的版本严格按照TDD执行，提升编码质量。

合理组合Superpowers与OpenSpec，可以形成跨越设计与质量的双闭环工作流。

设计与质量的双闭环工作流

如何完美地形成设计与质量的双闭环呢？

我个人的实践流程如下所示。

整个工作流的前置输入为定义了MVP版本的PRD文档，并明确分割为不同的markdown文件。在通过人工审核之后，进入Superpowers工作流，交由brainstorming进行设计探索。

brainstorming会在superpowers/specs目录下生成一份带有时间戳的设计文档。现在，把接力棒交给OpenSpec，在执行propose命令时，清晰地指定根据该设计文档创建提案。

propose会创建一个change，其下会生成proposal、design以及按照领域划分的spec文档和对应的task。如果希望确保后续执行阶段的质量，可以针对propose生成的spec文件，再次发起一次评审，即通过交叉验证prd与spec，以检测在整个过程中是否出现漂移现象。

接下来，把整个change作为输入，指派给Superpowers，由其显式地执行writing plan。Superpowers会根据change的proposal/design/tasks/specs，整理设计定稿，写入细化实现计划，并放到superpowers/plans目录下。然后，它会以推荐的Subagent-Driven模式（可以由用户选择），采用TDD方式实现各个任务，并完成代码、文档和其他内容的原子提交（通常会提交到框架自动创建的worktree中，避免代码的版本冲突）。

Subagent-Driven模式在执行任务时，默认情况下会在执行完一个任务后，得到用户授权认可才会继续执行下一个任务。这个环节同样可以引入人工评审。

一旦当前MVP的所有任务实现完成，又可以回到OpenSpec，对整个change执行archive。由于实现过程使用了Superpowers操作OpenSpec的change，会导致工件状态与任务状态不一致，即工件状态为done，但任务却未勾选。可以忽略这些未勾选的OpenSpec任务，确认归档即可。归档的规格文件会放到OpenSpec的主规格树中，同时在change/archive保留归档的内容。

整个开发流程如下示意图所示：

意图和质量的双闭环.png

前端设计与开发

虽然OpenSpec和Superpowers都可以完成前端的设计与开发，但从实际执行的效果看，仍然存在不足之处。我们可以引入ui-ux-pro-max来弥补前端设计与开发这一不足。

ui-ux-pro-max提供了以下设计能力：

├── 用户研究分析
│   ├── 用户画像创建
│   ├── 用户旅程映射
│   ├── 场景定义
│   └── 需求优先级排序
├── 界面设计系统
│   ├── 视觉风格定义
│   ├── 设计Token生成
│   ├── 组件库设计
│   └── 交互规范制定
├── 原型设计
│   ├── 线框图生成
│   ├── 高保真原型
│   ├── 交互动效设计
│   └── 设计评审文档
└── 前端实现
├── 代码生成
├── 设计系统集成
├── 响应式适配
└── 可访问性实现

通过ui-ux-pro-max分别定义用户画像、用户旅程和需求场景后，可以得到对应的文档persona-journey-and-page-scenarios.md。进而可以要求它执行：

1. 视觉风格定义
2. 组件库设计（使用Vue）.
3. 制订交互规范
4. 生成线框图
5. 设计高保真原型
6. 交互动效设计

最终可以得到一个效果较好的前端设计，并生成指定技术栈（例如Vue）的前端实现代码。

工程化任务依旧重要

即便是AI时代，一些重要的工程化任务依旧重要，甚至超过传统编程时代的重要性。

首先是需求工程能力。无论是调研、捕获原始需求，还是编写和评审PRD，随着开发效率的提升，以及受到Agent结构型特征的影响，都对PRD的质量提出了更高要求。参考《Harness Engineering手册》的内容，一个好的PRD需要满足：

1. 边界清晰：每个子域只负责一类核心业务逻辑
2. 低耦合：跨域只走契约（API/Event），不共享可写内部模型。
3. 可验证：能证明完备性与正交性，而不是“看起来差不多”。
4. 可编译：最终能落到原子、自包含、粒度合适的任务单元。

所谓的边界清晰以及契约继承的低耦合，又对工程师的架构能力提出了明确的要求。此外，对于部署和运行资源的规划，对产品质量的验证与评估，对持续集成和持续交付能力的满足，都需要工程师和AI对其进行共同治理。

这个过程必然有别于传统软件工程，人类工程师如何和AI协作，各自发挥其优势，会是AI时代的新课题和新挑战。诸如Y Combinator CEO Garry Tan开源的gstack似乎就是对这一问题的一种应对方式。

例如gstack的/office-hours与/plan-ceo-review就是需求工程的体现，通过它可以更好地输出PRD，且确保PRD的质量。/plan-eng-review用于锁定工程架构，扮演的是架构师的架构能力。/qa用于验收产品质量，/ship和/land-and-deploy用于发布和部署。

我暂时还没有在项目中尝试gstack，单单从它的介绍，可以看到它代表了AI软件工程的一种发展方向。对应的，它对现有的研发组织管理模式提出了新的挑战。

研发组织受到挑战

我始终认为，即便是在AI研发时代，康威定律仍然生效，不同之处在于组成团队的角色发生了变化，即特性团队由多位人类工程师转变为一位人类工程师带领一个由多Agent构成的虚拟特性团队。

如果针对一个小规模且复杂度较低的产品研发而言，这样的一人特性团队就足以满足研发需求。但是，对于一个规模较大且复杂度较高的产品而言，就需要处理好人与人之间、人与Agent之间的协作关系。

个人认为，类似Scrum of Scrum的组织结构仍然应该保持，同时，也应该遵循特性团队的划分原则，根据领域（或限界上下文）划分团队，即建立垂直的领域特性团队，从而形成产品级和领域级两个层次的研发团队。产品级团队全部由人类工程师组成，角色仍然对应管理、需求、技术和质量四个维度。同时，按照领域特性团队的责任边界，将熟悉对应领域知识的人类工程师分配给虚拟的领域特性团队。

产品级团队负责定义整个产品的最高意图（即产品愿景Vision）、架构规范和原则、UI设计规范和原则，并将整个产品划分为多个领域（或子领域，也可以认为是DDD中的限界上下文），并确定领域之间的协作方式和契约定义，也包括API的设计规范。同时，还需要确定对产品质量的约束规则、测试金字塔等。在整个开发过程中，可以继续沿用敏捷开发中的CoP（Community of Practice），该形式可以认为是人类工程师的交流社区，同时也可以由这一组织发起评审。

每个领域级产品团队只有一位人类工程师，但关键节点的评审都需要产品级人员的参与，甚至可以将关键节点的评审视为进入下一个阶段的门禁。在AI高效的并行研发模式下，还是需要把握“慢即是快”的原则。AI的研发效率虽然很高，但如果方向不对，就会导致南辕北辙，带来的返工成本，反过来会拖慢研发的效率。

AI时代的人机协作团队.png

如前所述，AI时代对架构单元边界的清晰性提出了更高的要求。一方面，引入DDD限界上下文的概念来界定PRD的边界或许是一个好的实践（它和AI工程的上下文名称上不谋而合）；另一方面，依然需要遵循康威定律，跨团队的交流成本更高，一旦发现人与人之间的交流变多（因为一个人可能就代表一个子领域或限界上下文），就意味着边界可能出现了模糊的地方，需要警醒。