深入解析Harness范式中的Spec：规范性、操作性与审计性的三层定义与应用

在实践CI/CD之后，你会发现日常工作从紧盯代码，逐渐变成了反复核对各类技术文档。这个过程看似解放了双手，实则对工作流的规范性和文档质量提出了更高要求，有时甚至感觉更“累”了。这恰恰是向更高成熟度工程实践迈进时的一种常态。

近期，“Harness Engineering”（驾驭工程）这个概念在社区中被频繁讨论。为了理清其脉络，避免人云亦云，我深入研读了一系列相关资料，并希望从一个核心构件——Spec（规范/说明书）——开始，分享我的理解和思考。

从Harness范式的能力边界谈起

要理解Harness范式，首先得明确它的能力和边界。我们可以从几个简单的文件入手：

• proposal.md：这个功能究竟要解决什么问题？
• specs/：具体的需求细节是什么？
• design.md：技术方案如何设计？
• tasks.md：需要拆解成哪些具体任务？

这些文件共同指向一个核心：它们要求项目的实现者具备交叉学科的知识背景，并且将几乎所有关键决策都沉淀为文档。这引发了我的一个困惑：“Harness”这个词，在不同语境下究竟指代什么？

与GPT“聊”出的定义：Spec的三层结构

经过长时间的探讨和梳理，我认为有必要为“Spec”建立一个清晰、可操作的定义。至少，是我自己能够理解并应用的定义。在我看来，一个完整的Spec体系应当包含以下三个层次：

1. 规范性Spec (Normative Spec)
   它定义了项目的目标、边界、验收标准、责任划分以及准入条件。这类Spec不应在开发循环中被随意重写，它扮演着项目“宪法”的角色，确保了项目演进的基本方向和原则稳定。

2. 操作性Spec (Operational Spec)
   它定义了单次循环中具体要修改什么、如何修改、如何验证、以及失败后如何进入下一轮。这类Spec更像是“战术计划”，它是可以且应该被反复迭代和改写的，直接指导每一次具体的开发活动。

3. 审计性Spec (Audit Spec)
   它既不是要求，也不是计划，而是对已完成工作的记录：这次循环到底做了什么、改动了什么、为什么做这些改动、如何论证这些改动更接近目标，以及有哪些规则支持这个判断。本质上，它是一份审计材料，用于追溯和复盘。

这三层结构，将Spec从一个静态的“需求文档”概念，拓展为一个动态的、贯穿项目生命周期的治理与协作框架。

背景知识：Harness Engineering的核心视角

要深入理解上述Spec体系，需要回到OpenAI提出的Harness Engineering视角。其核心观点是：与其将智能体系统视为离散工具的堆叠，不如将其理解为一个可持续驱动的软件工程控制体系。

这对应的不是传统的微服务式分散调用，而是一种更偏向协调器模式（Orchestrator）的设计：

• 由中心控制逻辑统一调度任务。
• 持续维护上下文。
• 明确约束执行边界。
• 并通过循环不断逼近目标结果。

这个视角为理解后续的参考项目提供了基础。

关键项目参考：Ralph与OMX

• Ralph：单体进程中的循环执行
  Ralph并非微服务拼装系统，而是一个运行在独立仓库中的单体应用。它是一个可垂直扩展的单一操作系统进程，并遵循“每个循环只执行一个任务”的原则。其重点在于“循环的稳定性”，它将系统视为一个持续运转的loop：给定目标 -> 加载backing specifications -> 执行一轮 -> 审查结果 -> 进入下一轮。Ralph提供了一种工程组织方式，即围绕目标驱动循环，而非线性堆叠任务。

• oh-my-codex (OMX)：多Agent协作的调用链参考
  OMX则展示了一套多Agent协作系统的调用链。它的价值在于清晰表达了多个Agent之间的职责分配、调用顺序和信息传递关系，非常适合用sequenceDiagram来描述完整的交互时序。OMX可以作为多Agent系统在 “执行链路层” 的参考样本，解决了调用链应如何清晰建模的问题。

简单总结：Ralph更像是 “循环控制思想” 的来源，而OMX更像是 “多Agent交互结构” 的参考。

实践结合：CMMI5理念下的项目管理流水线设计

基于以上知识，我尝试整理一个基于CMMI5理念的“项目管理流水线 — Agent协作设计”。你可能会好奇：上述项目不是已经实现了吗？

实际上，OpenAI的作者们常常“话说一半”。在Ralph中，规范更像是一种“可执行的假设”和“可变的引导状态”；而在CMMI5中，规范更接近于“社会契约”和“治理文件”。这两者表面存在冲突，实则优化了不同的失败模式。

关键就在于前文定义的Spec分层：如何将规范拆分为规范性规范和操作性规范，并对具体问题作出针对性说明。

知识结构的构建与“控制平面”设计

一些项目（如Codex）提到了“知识结构”的示例（例如AGENTS.md导航文件和结构化的docs/目录），但并未详细阐述如何构建这一知识基座。其设计重点在于：AGENTS.md提供导航，docs/目录提供真实的知识沉淀，而代码仓库本身承担记录系统的角色。

这一整套思路，与我设想的《项目管理流水线 — Agent协作设计》理念相通。共同点不在于“都用了Agent”，而在于都将系统理解为一种 “控制平面（Control Plane）”：

• 目标不是替代所有执行器。
• 目标是约束、编排、校验执行器。
• 通过文档、规则、阶段与反馈，维持整个系统的可控演化。

因此，我们讨论的并非单纯的“多智能体分工”，而是一个面向AI-Agent组织方式的控制面（Control Plane）设计。

延伸参考与资源

如果你想进一步探索更偏商业化的生态，可以关注Harness.io的商业Agent平台。同时，社区中也有像paperclip这样的实验性项目（例如pnpm paperclipai company import https://github.com/WaytoAGI-Community/paperclip-suoxya-org，但可能仍存在bug），为理解和实践提供了更多切入点。

其他推荐阅读资料：

• Geoffrey Huntley: Loop / Program the Loop
• 相关视频讲解: https://www.youtube.com/watch?v=4Nna09dG_c0
• Anthropic: Harness Design for Long-Running Apps
• GitHub项目: OpenSpec, OpenHarness, superpowers
• 微信公众号文章: https://mp.weixin.qq.com/s/wOCKIKdh5YIGY6HTGd_dnQ

通过对Spec进行三层解构，并将其置于Harness Engineering和控制平面设计的上下文中，我们或许能更清晰地把握如何利用AI Agent来构建可靠、可控且持续演进的复杂软件系统。这不仅仅是技术的堆砌，更是一种工程哲学与组织方式的变革。在云栈社区的技术讨论中，我们也常常围绕如何将这类前沿理念落地进行深入交流。