Harness 企业级落地之三：高规格高质量开发

一、前言

通过前面两篇文章，harness 已经能正常使用且产生工程的项目画像。

这次我们要让每一项任务，有明确的边界、能被正确执行、最后留下可复用的证据。

笔者把 OpenSpec 和 omx（oh-my-codex 的运行时编排）接入到 cow-harness。从而达到 Harness 管项目边界，OpenSpec 管任务的拆分和梳理，omx 管已经批准任务的执行。

让 AI 运行过程更加的健壮！

开源地址：OpenSpec · omx · cow-harness

二、背景

AI 能读懂仓库，不等于它能持续把需求做对。一个新的需求还会带来另一组问题：为什么要改、改到哪里、哪些行为不能被破坏、做到什么算完成？

如果这些信息只散在聊天记录里，前面做过的判断很容易消失。

所以，不把 Harness 当成一个只会塞提示词的文件夹，而是更像项目的工作秩序：

• 稳定的事实： 沉淀为项目资产；
• 本次要改变的事实： 沉淀为变更规格；
• 执行和验证的事实： 沉淀为可追溯的过程证据。

三、职责分工

• Harness 会先告诉 AI “在哪个项目里工作”；
• OpenSpec 告诉 AI “这次要改什么”；
• omx 最后处理“已经说清楚的任务，怎么更可靠地做出来”。

项目画像 .ai-harness/
        ↓ 识别稳定事实与正确子项目
OpenSpec change
        ↓ 规格、任务、人工确认
omx 或当前 Agent
        ↓ 执行、测试、验证
变更归档 + 运行证据
        ↓ 回流为下一次任务可读取的项目上下文

四、OpenSpec 介入方式

OpenSpec 真正约束的是：有行为边界的变更

注意，一旦进入 OpenSpec，流程会把需求逐层压实：

• 先理解问题，再决定是否需要设计；
• 写出可验证的行为规格；
• 拆成可执行任务；
• 必要时让人确认，最后才进入实现和验证。

brainstorm
   → design（按需）
   → specs（必需）
   → tasks
   → human-review（按需）
   → apply
   → verify
   → retrospective
   → archive

当前 OpenSpec 的校验与归档流程，需要至少一份行为 delta spec 才能判断一项 change 是否完整；这正好让“改什么、怎么验收”有了明确落点。

五、omx 介入方式

OpenSpec 解决的是“做什么”；omx 解决的是“已经批准的事情，怎样执行得更可靠”。

两者的交接点非常明确：任务已经拆好并获得确认后，才允许进入执行。

在 cow-harness 的路由中，Agent 会先读取当前 change 的动态指令：

openspec instructions apply --change  --json

这一步会让执行方拿到当前 change 的任务、规格和验证要求，再决定采用哪种执行方式：

• 单目标、低耦合的任务： 可以由当前 Agent 直接实现并做聚焦验证；
• 多任务或高耦合的已批准实现： 交给 omx 做运行时编排，分别完成、回收和核验；
• 没有可用运行时： 就由当前 Agent 如实回退执行，不能假装 omx 已经替你跑完。

六、cow-harness 接入

这次改造 cow-harness，我们实际做了四件事

1. 把 domain-init 固定为 Harness 的 Git submodule。初始化时，AI 不再只看目录，而是会按领域初始化流程识别前端、后端、客户端、测试等项目规则，并把结果写进项目自己的 .ai-harness/。
2. 在 Harness 源码中加入 OpenSpec custom schema、模板和 bootstrap runbook。它们是通用能力，跟随 cow-harness/ 演进。
3. 重构 init 调用链：先形成项目画像，再运行 openspec init --tools none 初始化项目根目录的 OpenSpec，合并 schema，并生成 .ai-harness/openspec-context.md。
4. 把任务路由改成先选业务子项目、再创建或继续该子项目的 change。

business-project/
├── cow-harness/                 # Git submodule：通用框架与初始化流程
├── .ai-harness/                 # 该项目的长期画像
│   ├── project.profile.md
│   ├── context-map.md
│   ├── verification.md
│   └── openspec-context.md
├── openspec/                    # 该项目自己的规格与变更
│   ├── changes/
│   ├── specs/
│   └── schemas/cow-harness/
└── .ai-runtime-artifacts/       # 非 OpenSpec 的执行与验证证据

七、为什么值得用

OpenSpec 和 omx 在真实项目里，它们解决的是一套标准的研发流程，可靠性更高。

这也是 cow-harness 开源出来的原因，它不只是一个示例模板，而是把全栈项目路由、领域初始化、项目画像、OpenSpec 变更和验证门禁组织到一起的一套可迁移基建。

• OpenSpec 最直接的价值，是把“我以为要这么做”变成“我们约定要做到这里”。

  • 很多返工并不是代码能力不够，而是需求、接口、数据和 UI 行为在开发前没有被拆到可以验收的粒度。
  • delta spec 把变化本身单独拿出来，不会随着新的对话被冲掉。
  • 下一次出现争议时，可以直接回到 change 看当时约定的行为。

• 是让评审从结果导向变成闭环导向。

  • 有了规格和验证记录，才可以继续判断：这个需求有没有遗漏？边界场景有没有覆盖？
  • 这对 AI 开发尤其重要，因为模型很擅长把一段代码写完整，但不天然知道哪一个行为才是产品真正关心的。

• omx 的价值，则是让“任务列表”不再只是文档最后的几行字。

  • 当一个 change 已经被拆成多个任务时，omx 可以在规则允许的范围内处理任务顺序、并行机会和结果回收，并把执行重新拉回验证环节。

• 两者放在一起，才能避免两种极端。

  • 没有 OpenSpec，omx 可能把错误方向执行得更快；
  • 只有 OpenSpec 而没有执行编排，规格又容易停在文档里。
  • Harness 把前者接到项目边界上，再把后者接到验证门禁上，才形成“需求有出处、执行有依据、结果有证据”的闭环。

真正值得沉淀的，不是某一个框架的文件格式，而是这套工作方式。

八、写在最后

Harness 不是为了限制 AI，而是为了让 AI 真正参与软件生产。

诚然，随着大模型能力越来越强，Harness 这类约束看起来没那么“刚需”了。 今天的新一代模型，已经能在较长上下文里完成方案、开发、修改和纠错；我们当然不该为了流程而流程。

但 Harness 的价值，从来不只是约束模型，而是逼着我们把经验变成方法流程：需求怎么拆、规格怎么验、测试怎样对应，埋点、灰度、发布和回滚又该由谁守住。

模型是会越来越强大，但这些判断点不会自动长出来。 所以，我们更应该主动参与，把这些方法教给 AI 去执行。

接下来笔者会继续基于 Harness，锚定一个场景。比如：把产品一句话需求，逐步串成可验证的方案、设计稿、开发任务和自动化测试；再让 AI 持续观察同类软件，把外部的需求提炼出来，反哺成下一轮迭代。

这是相对理想化的流程，但并不空想。先让 AI 读懂项目，再让每一次变更有规格、每一段执行有证据，我们就在把它从概念跑成现实。

关注我不迷路，我们继续把这条路跑通。开源地址：cow-harness