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

一、前言

AI Harness 企业级落地实践（一）

Harness 企业级落地(二) - 让 AI 读懂项目

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

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

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

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

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

二、背景

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

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

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

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

三、职责分工

层	放在哪里	它负责什么	它不负责什么
Harness	`.ai-harness/` 与项目入口	项目画像、模块边界、任务路由、验证门禁	不保存每一次需求的详细方案
OpenSpec	`openspec/changes/`	一次变更的动机、行为规格、任务与验收	不复制项目画像，也不直接替你写代码
omx	运行时执行链路	把已经批准的任务拆开、执行、回收结果	不越过规格决定需求范围
运行证据	`.ai-runtime-artifacts/`	执行日志、独立决策、评审与非 OpenSpec 验证记录	不重复保存 change 内已有的事实

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

markdown 复制代码

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

四、OpenSpec 介入方式

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

任务情况	该走哪条路
文档、拼写、纯配置、机械修改、无契约的局部缺陷	直接处理，运行最接近的验证
新能力、架构、跨模块、外部 API、数据模型、安全、复杂 UI 行为	创建或继续当前业务项目里的 OpenSpec change
已经在一个 change 中的后续工作	继续该 change，不能绕开它另起一条私有流程

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

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

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

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

五、omx 介入方式

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

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

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

css 复制代码

openspec instructions apply --change <change-name> --json

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

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

六、cow-harness 接入

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

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

bash 复制代码

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 变更和验证门禁组织到一起的一套可迁移基建。

它们可能本身不难，但你完全可以把cow-harness，当成 AI 进入真实项目时的工程地基。

项目现场	只靠对话推进	接入 OpenSpec 和 omx 之后
需求变更	需求、方案与验收混在上下文里，时间一长就只剩代码结果	变更动机、行为规格与任务留在同一个 change，可以回看和继续
代码评审	主要看 diff，很难确认是否覆盖了原本要解决的问题	可以把实现、规格和验证放在一起核对
长任务或多人协作	前一轮的判断依赖记忆，任务交接容易失焦	项目画像、change 与运行证据各有位置，接手的人知道先读什么
多任务实现	容易把可并行和强依赖任务混在一起，执行结果也难回收	先由 tasks 明确依赖，再由 omx 按适合的执行方式推进并回收验证

OpenSpec 最直接的价值，是把"我以为要这么做"变成"我们约定要做到这里"。
- 很多返工并不是代码能力不够，而是需求、接口、数据和 UI 行为在开发前没有被拆到可以验收的粒度。
- delta spec 把变化本身单独拿出来，不会随着新的对话被冲掉。
- 下一次出现争议时，可以直接回到 change 看当时约定的行为。
是让评审从结果导向变成闭环导向。
- 有了规格和验证记录，才可以继续判断：这个需求有没有遗漏？边界场景有没有覆盖？
- 这对 AI 开发尤其重要，因为模型很擅长把一段代码写完整，但不天然知道哪一个行为才是产品真正关心的。
omx 的价值，则是让"任务列表"不再只是文档最后的几行字。
- 当一个 change 已经被拆成多个任务时，omx 可以在规则允许的范围内处理任务顺序、并行机会和结果回收，并把执行重新拉回验证环节。
两者放在一起，才能避免两种极端。
- 没有 OpenSpec，omx 可能把错误方向执行得更快；
- 只有 OpenSpec 而没有执行编排，规格又容易停在文档里。
- Harness 把前者接到项目边界上，再把后者接到验证门禁上，才形成"需求有出处、执行有依据、结果有证据"的闭环。

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

八、写在最后

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

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

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

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

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

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

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