最近一直在尝试 Vibe Coding 的各种 SDD 开发方式，比如 OpenSpec、SpecKit、oh-my-openagent 的 Prometheus。

Andrej Karpathy 在 2025 年 2 月提出了 Vibe Coding 这个概念——用自然语言描述意图，让 LLM 生成代码，“Accept All” 不看 diffs，错了直接复制错误信息让 AI 修复。

但真正上手后，我发现一个致命问题：AI 老是胡乱发挥。

尤其在维护旧项目时，你给它一个需求，它能给你整出三套实现方案，每个都"看起来合理"，但哪个才是你真正想要的？

什么是 Spec-Driven Development (SDD)

规约驱动开发（Spec-Driven Development，SDD），或者说"契约优先开发"（Contract-First Development），核心思想很简单：

先定义规范，再让 AI 执行。

不是传统的"先写代码，文档是脚手架"，而是把规范作为唯一事实来源（Single Source of Truth）。

GitHub Spec Kit 提出了六阶段工作流：

• /constitution - 定义项目级原则（质量标准、架构约束）
• /specify - 描述功能"是什么"，不涉及"怎么做"
• /clarify - 消除歧义、识别边界条件
• /plan - 技术选型、架构决策
• /tasks - 分解为可执行单元
• /implement - 按规约编写代码

这个流程让我意识到：Vibe Coding 的终极目标不是让模型发挥多强，而是确保意图能被 100% 理解和实现。

Harness Engineering：给模型套上缰绳

Anthropic 有个经典隐喻：

1
2

LLM = 强大的马，强大的力量，但没有方向感，不理解边界
Harness = 缰绳 + 马鞍，引导力量，设定边界，防止失控

Harness Engineering 就是设计、构建和运营 AI Agent 基础设施的学科——约束、引导、验证、纠正生产环境中的 AI。

这跟 Prompt Engineering 完全不同：

有个真实案例让我印象深刻：某金融公司的 Agent 在凌晨 3 点失控，连续 11 分钟疯狂重试一个失败的 API，累计重试 847 次，消耗了 2200 美元的 API 费用，还给同一个客户发了 14 封重复邮件。

事后复盘发现：Model 运行正常，Prompt 也精心设计了，但问题出在基础设施层面——缺少三个硬性控制：重试上限、执行超时、熔断机制。

这件事让我真正理解了 Harness 的核心价值：写在 Prompt 里的"请勿超过 10 次重试"，只是建议，AI 可以忽略，可以被其他指令覆盖。但在 Harness 层强制执行的重试上限，才是真正的治理——Agent 无法绕过，必须遵守。

工程范式发生了彻底的改变

从对话交互到严格约束

过去我们：

• 不断和 AI 对话交互
• 写更好的 prompt
• 用更强的单一模型（GPT-4 → GPT-4o → Claude Opus）

现在的 Harness Engineering：

• 严格约束：哪些要做，哪些不能做
• 人类意图的理解：面试式访谈，消除歧义
• 全流程把控：从规约 → 计划 → 执行 → 验证
• 多 Agent 多模型协作（oh-my-openagent插件）：Sisyphus + Prometheus + Metis + Momus

核心组件

Harness Engineering 有五大组件：

1. Context Engineering - 决定 Agent 每一步看到什么信息
2. Tool Orchestration - 工具选择、参数验证、执行沙箱
3. Verification Loops - 每步验证输出（83% → 96% 任务完成率）
4. Cost Envelope Management - Per-task 预算上限（median × 3）
5. Observability - 结构化执行追踪，因果关系记录

我的 Harness Engineering 实践：DDD + gRPC 项目

第一步：定义 gRPC 输入输出规范

DDD 架构的项目，必须先人工定义 gRPC 的输入输出规范。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

service UserService {
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
}

message CreateUserRequest {
  string name = 1;      // 2-100 字符
  string email = 2;     // 必须是有效邮箱格式
  string role = 3;      // 只允许 "admin", "user", "guest"
}

message CreateUserResponse {
  string user_id = 1;   // UUID 格式
  int64 created_at = 2;
}

这个 .proto 文件就是契约——AI 不能超出这个范围胡乱发挥。

第二步：让 AI 全量探索项目

项目中有很多 repo 层的可复用资源，需要让 AI 做全局探索（只读），产出项目概要 markdown。

使用 oh-my-openagent 的 /init-deep ，并行启动多个 Agent：

• 搜索现有数据模型
• 分析 repo 层接口
• 提炼可复用组件

第三步：编写业务细节 markdown

切记：不要贪图一个文档囊括大量业务细节。

小颗粒度拆分：

1
2
3
4
5
6
7
8

specs/
├── 001-user-auth/
│   ├── spec.md         # 用户场景、验收标准
│   ├── data-model.md   # 数据模型定义
│   ├── contracts/      # API 契约
│   └── tasks.md        # 可执行任务
├── 002-payment-flow/
│   └── ...

原则：尽量让主 Agent 每次任务不占用过多上下文。就算压缩上下文，也是信息准确度的丢失。

第四步：调研阶段——绝不能直接写代码

这是最关键的一步：一定要告诉 AI，不要一开始就写代码。

尤其在上下文累积越长的时候，模型越容易产生幻觉，自以为是地开始执行。我们要利用单个 AI session 的上下文空间，先让 AI 进行严格的调研，提出疑问，我们一起完善我之前编写的规约规范。

模拟对话的场景：

1
2
3
4
5
6
7
8

AI: "我看到项目中已有 UserRepository，但缺少 OAuthToken 实体。
     需要新建表还是复用现有的 user_tokens 表？"
     
我: "复用 user_tokens 表，但需要添加 provider 字段。"

AI: "provider 字段是否需要枚举约束？支持的 provider 有哪些？"

我: "目前只支持 google 和 github，用枚举约束。"

上面的对话场景，只是我模拟举出的案例。这种迭代式澄清，比直接让 AI 写代码效果好太多。

第五步：调研结束后，使用 OpenSpec 或 Prometheus 建立 Tasks/Plans

我常用的两种方式：

OpenSpec 的 /opsx:propose：

1
2
3
4
5
6

/opsx:propose 添加 OAuth 2.0 认证支持，请读取xxx.md开始调查并制定计划，但不要执行计划
# 自动生成：
#   proposal.md - 意图、范围、方案
#   specs/auth/spec.md - Delta Specs (ADDED/MODIFIED/REMOVED)
#   design.md - 技术架构决策
#   tasks.md - 实施清单

oh-my-openagent 的 Prometheus：

1
2
3
4
5
6
7
8

请读取 xxx.md 开始调查并制定计划，不要执行计划
# 面试式访谈：
#   - 先迁移哪些端点？
#   - REST 保留还是废弃？
#   - OAuth provider 选择？
#   - 是否使用TDD测试驱动开发？
# 
# 生成计划 → Oracle调研 → Metis 分析 → Momus 验证

当然我个人而言，我更喜欢omo插件的"访谈式"，或者说是"对话式"的确认很多细节。

第六步：Plans/Tasks 创建后，新建 session 执行

当 Plans 或 Tasks 的 markdown 文件创建好后，我会新创建一个 AI session，让它专一地执行这次任务。

使用 omo 的/start-work，或者 OpenSpec的 /opsx-apply xxxxx：

• 读取已验证的计划
• 委托给专业 Agent（代码生成、测试、集成）
• 独立验证结果
• 主 Agent 协调

题外话：oh-my-openagent 的多 agent、多 category 的方式，似乎在使用 OpenSpec 的 skills 时，无法正常启用，它只会让你当前主模型去执行。

总结：实践后的真实感受

用了2个多月 Harness Engineering 的方式做 Vibe Coding，最大的感受不是数据提升了多少，而是心态变了。

以前用 AI 写代码，每一步都提心吊胆——它会不会理解错了？会不会自作主张加一堆不需要的功能？会不会把简单的事情搞复杂？

现在有了规约约束，这些问题基本消失了。不是因为我用了更强的模型，而是因为我在 AI 执行之前，先把意图"钉死"了。

几个明显的改变：

返工少了。以前一个功能平均要来回改三四次，现在大部分一次就过。不是因为 AI 突然变聪明了，是因为规范把"怎么做"提前定清楚了。

成本降了。同样的任务，Token 消耗大概省了三分之一。因为 AI 不需要反复尝试、反复修正了。

模型要求没那么高了。以前觉得必须用 Claude Opus 才能干好活，现在用 Sonnet 配合完善的规约，效果差不多。

Vibe Coding 的本质不是"让 AI 更聪明"，而是"让 AI 更听话"。

听话的前提是：你先把话说清楚。

这才是 Harness Engineering 的核心——它不是让模型发挥更强的能力，而是确保你的意图被准确理解、严格执行。

搭这套基础设施确实费时间，反复探索这2个多月时间，才用顺手。但一旦搭好了，AI 编码就从"猜谜游戏"变成了"按图施工"——你可以真正享受 Vibe Coding 的乐趣，而不是每次都要盯着它有没有跑偏。

如果你对规约驱动开发感兴趣，可以看看我在 OpenCode 中尝试 OpenSpec 的体验。对于 AI agent 模型配置，可以参考我的 oh-my-opencode 配置优化历程。