一文搞懂 AI Agent Harness:它是什么,为什么重要,以及开发者需要建立哪些认知?

15 阅读26分钟

一文搞懂 Spec Kit 与 OpenSpec:AI 编程为什么需要规格驱动开发?

核心认知

Harness 解决的是如何让 AI 可靠地执行任务。 它通过上下文管理、工具执行、状态控制、安全约束和可观测性等机制,将模型能力转化为可交付、可评测的 Agent 系统。

Spec Kit 和 OpenSpec 解决的是如何让 AI 围绕明确的需求、约束和开发流程开展工作。 它们通过规格管理和流程组织,降低需求理解偏差,让开发过程更加可控。


我们知道,Codex、Claude Code 这类 AI 编程 Agent,能够理解需求、读取代码、修改文件,甚至自动运行测试。

但在实际开发中,很容易遇到一个问题:

AI 写代码的能力越来越强,但它写出来的代码,不一定是我们真正想要的。

例如,我们让 Codex 开发一个会员订阅功能。

AI 可能很快生成代码,但如果没有提前明确订阅规则、异常处理、退款逻辑和验收标准,最终实现的功能可能与真实业务需求存在偏差。

这正是 Spec Kit 和 OpenSpec 试图解决的问题。

它们背后有一个共同的核心理念:

Spec-Driven Development(SDD,规格驱动开发)。

本文将从软件工程的角度,结合 Android 开发场景,理解 SDD、Spec Kit 和 OpenSpec 的工作原理,以及它们与 Agent、Harness、Skill、Workflow 等概念的关系。


一、先理解什么是 Spec-Driven Development(SDD)

Spec 是 Specification 的缩写,中文通常翻译为“规格”或“规格说明”。

在软件开发中,Spec 用来明确:

  • 系统应该实现什么功能。
  • 功能需要满足哪些业务规则。
  • 不同情况下应该如何处理。
  • 存在哪些技术约束。
  • 如何判断功能已经正确完成。

例如,开发一个金币充值功能。

如果只是告诉 AI:

“帮我实现 Google Play 金币充值。”

这个需求其实非常模糊。

至少还需要明确:

  • 支持哪些充值商品?
  • 支付成功后由谁发放金币?
  • 如果支付成功但金币未到账怎么办?
  • 如何避免重复发放金币?
  • 订单状态如何同步?
  • 网络中断后如何恢复?
  • 如何验证充值流程正确?

这些问题最终形成的需求约束和验收标准,就是 Spec 的重要组成部分。

1. 直接对话式 AI 编程

提出需求
   ↓
AI 理解需求
   ↓
AI 生成代码
   ↓
开发者检查
   ↓
发现问题后继续修改

这种方式适合简单、明确的任务。

但当需求复杂、业务规则较多时,AI 可能自行补全未明确的条件,导致实现偏离预期。

2. 规格驱动开发方式

提出需求
   ↓
明确需求规格(Spec)
   ↓
澄清需求歧义(Clarify)
   ↓
制定技术方案(Plan / Design)
   ↓
拆分开发任务(Tasks)
   ↓
AI 执行开发(Implement)
   ↓
根据规格验证结果(Verify)

这是一个概念化的 SDD 流程,不代表所有工具都必须包含这些独立阶段。

两者最大的区别在于:

直接对话式开发容易让 AI 一边理解需求、一边设计、一边编码;SDD 则强调先明确开发目标与约束,再围绕规格实施。

需要注意,SDD 并不意味着所有任务都必须经过完整、严格的文档流程。

对于简单的 Bug 修复,可能只需要简短的规格和验收条件;对于涉及支付、权限或复杂业务规则的功能,则值得投入更多时间进行规格设计。

二、Spec Kit 和 OpenSpec 是什么?

Spec Kit 和 OpenSpec 都是围绕 SDD 理念构建的开源工具。

它们不是大模型,也不是新的 AI 编程 Agent。

它们主要帮助开发者组织需求规格、技术方案、任务拆解和实施过程,让 AI 编程更加可控。

1. Spec Kit:强调结构化、可扩展的开发流程

Spec Kit 是 GitHub 推出的规格驱动开发工具包。

它通过模板、命令和工作流,帮助开发者将自然语言需求逐步转化为可执行的开发任务。

其核心 SDD 工作流可以概括为:

Constitution(项目原则)
       ↓
Specify(定义规格)
       ↓
Clarify(澄清需求,可选)
       ↓
Plan(技术规划)
       ↓
Checklist(质量检查,可选)
       ↓
Tasks(任务拆解)
       ↓
Analyze(一致性分析,可选)
       ↓
Implement(实施开发)
       ↓
Converge(检查实现与规格的差距)

其中,Clarify、Checklist 和 Analyze 是可选的质量检查环节,并不是每个任务都必须执行。

各阶段的作用:

Constitution(项目原则)

建立项目长期遵守的工程规范和约束。

例如:

  • Android 代码优先使用 Kotlin。
  • 遵循现有项目架构。
  • 不随意引入新的第三方依赖。
  • 涉及支付的逻辑必须具备幂等性。
  • 核心业务修改需要补充测试。

Specify(定义规格)

明确需要实现什么功能、用户场景、业务规则和验收标准。

Clarify(需求澄清)

检查规格中存在的歧义、遗漏和未确定的规则,通过向开发者提问完善规格。

Plan(技术规划)

确定技术方案、架构设计、依赖关系和实现策略。

Tasks(任务拆解)

将需求与技术方案拆分为具体、可执行的开发任务。

Implement(实施开发)

让 AI 编程 Agent 根据任务清单执行代码修改,并进行必要的验证。

Converge(实现收敛)

检查实现与规格、计划和任务之间的差距,识别尚未完成的工作。

除了核心 SDD 流程,Spec Kit 还支持 Bug 修复、方案评估以及自定义工作流等扩展能力。

可以将 Spec Kit 理解为:帮助开发者建立结构化、可扩展、可重复执行的 AI 开发流程。

2. OpenSpec:强调规格与变更管理

OpenSpec 是 Fission AI 推出的规格驱动开发工具。

它同样关注需求规格和 AI 开发流程,但其设计中特别值得关注的是 Change(变更)机制。

对于长期维护的软件项目,开发工作往往不是从零开始,而是在现有系统上不断增加功能、修复问题和调整规则。

OpenSpec 将系统当前的规格与正在实施的变更分开管理。

典型目录结构如下:

openspec/
├── specs/
│   └── 当前系统规格
│
└── changes/
    └── 正在实施的变更

其中:

  • specs/:描述当前系统已经确定的行为和规则。
  • changes/:保存新需求或修改需求的相关资料。

OpenSpec 的默认工作流可以概括为:

Explore(探索,可选)
       ↓
Propose(提出变更)
       ↓
Update(修订规格,按需)
       ↓
Apply(实施开发)
       ↓
Sync(同步规格,可选)
       ↓
Archive(归档变更)

实际流程并非严格的单向流水线。在实施过程中发现需求变化时,可以返回 Update 修订规格;验证也可以作为可选环节加入。

各阶段的作用:

Explore(探索需求)

分析现有系统,讨论可能的实现方案,澄清不确定的问题。

Propose(提出变更)

创建变更提案,明确需要增加、修改或删除哪些行为,并形成设计和任务资料。

Update(更新规格)

当需求、设计或任务存在遗漏、变化时,修订相关文档,保持内容一致。

Apply(实施变更)

让 AI 编程 Agent 根据规格和任务执行开发。

Sync(同步规格)

将变更中的增量规格同步到当前系统规格。是否需要独立执行取决于工作流。

Archive(归档变更)

在确认变更完成后,归档相关资料,并根据流程完成必要的规格同步。

需要注意:

Archive 是规格与变更管理操作,并不天然保证代码已经通过测试或业务验收。

OpenSpec 还提供可选的 Verify(验证)能力,用于检查实现是否符合相关规格和任务资料。

这里有一个重要概念:

Delta Spec(增量规格)。

它描述本次变更相对于当前系统规格,增加、修改或删除了什么,而不需要每次都重新编写整个系统的完整规格。

这对于长期迭代的项目很有价值。

三、Clarify 到底是什么?Spec Kit 和 OpenSpec 有什么区别?

Clarify 的英文含义是“澄清、明确”。

在 AI 开发中,它主要解决一个问题:

当需求存在歧义、遗漏或未确定的规则时,不让 AI 直接猜测,而是先通过提问把关键问题明确下来。

例如,我们提出:

“增加金币充值失败后的自动补单功能。”

AI 可能需要进一步确认:

  • 补单由客户端主动触发,还是服务端自动处理?
  • 如果购买成功但金币发放失败,应该重试多少次?
  • 同一笔订单重复提交时应该如何处理?
  • 用户切换账号后,原订单如何归属?
  • 超过一定时间仍未补单成功,是否需要人工处理?

这些问题并不是无关紧要的细节。

不同的答案,可能直接影响数据库设计、API 设计、状态机和测试用例。

1. Spec Kit:提供独立的 Clarify 命令

Spec Kit 提供:

/speckit.clarify

它通常在 Specify 之后、Plan 之前使用。

Specify
   ↓
Clarify
   ↓
Plan
   ↓
Tasks
   ↓
Implement

执行 Clarify 时,Agent 会检查当前规格中尚未明确的重要问题,并通过交互式提问获取开发者的确认。

官方的 Clarify 工作流每轮最多提出 5 个重点问题,并将确认结果更新到规格文档中;必要时可以再次运行。

它重点检查的内容包括:

  • 功能范围。
  • 用户角色。
  • 数据模型。
  • 业务状态变化。
  • 异常场景。
  • 性能和安全要求。
  • 验收标准。

例如:

问题:同一笔 Google Play 购买记录被重复提交时,系统应该如何处理?

A. 每次都发放金币。

B. 已成功发放的购买记录不再重复发放。

C. 全部交给人工处理。

开发者确认后,Agent 将结果写入规格,后续技术规划就能够基于更明确的需求进行。

因此:

Spec Kit 的 Clarify 是一个显式、可重复执行的需求质量检查环节。

它是可选的,但对于复杂业务非常值得使用。

2. OpenSpec:默认没有独立的 Clarify 命令

OpenSpec 的默认 OPSX 工作流没有独立的 /opsx:clarify 命令。

但这不代表它不支持需求澄清。

OpenSpec 更倾向于将澄清融入探索和规格迭代过程。

例如:

Explore
   ↓
讨论需求与不确定问题
   ↓
Propose
   ↓
审查规格
   ↓
Update(必要时继续澄清、修改)
   ↓
Apply

其中:

  • /opsx:explore:用于探索问题、分析代码和讨论方案。
  • /opsx:propose:用于生成变更提案及相关规格。
  • /opsx:update:用于修订规格、设计和任务资料。

即使没有独立的 Clarify 命令,也可以要求 Agent:

“先检查当前规格中有哪些业务规则不明确,逐项向我确认,确认完成后再实施。”

因此:

OpenSpec 不是不需要 Clarify,而是没有将 Clarify 固定为默认工作流中的独立命令。

3. 两者的区别

对比维度Spec KitOpenSpec
独立 Clarify 命令有,/speckit.clarify默认没有
澄清方式专门检查规格歧义并提问Explore、Propose、Update 中持续澄清
典型时机Specify 后、Plan 前探索、提案及实施调整过程中
是否强制否无独立强制阶段
澄清结果更新规格文档更新变更相关文档

这里需要建立一个重要认知:

Clarify 是一种需求澄清能力,不一定必须对应一个独立命令。

对于复杂业务,关键不是有没有 /clarify,而是开发流程是否能够及时发现并解决影响实现正确性的需求歧义。

四、Spec Kit 和 OpenSpec 有什么区别?

两者都属于规格驱动开发工具,但设计侧重点有所不同。

对比维度Spec KitOpenSpec
项目来源GitHubFission AI
核心关注结构化、可扩展的开发流程规格与变更管理
主要组织方式规格、计划、任务、实施当前规格、变更提案、增量规格
项目原则Constitution 机制可通过项目约定与配置表达
需求澄清独立 Clarify 命令Explore / Propose / Update
现有项目迭代支持增量变更机制尤其直观
工作流风格更强调阶段和质量检查默认流程相对轻量、灵活
AI 编程工具可配合 Codex 等工具可配合 Codex 等工具

需要注意,这并不意味着 Spec Kit 只能用于新项目,或者 OpenSpec 只能用于已有项目。

两者都可以支持新项目开发和现有项目迭代。

它们的区别更多体现在默认工作方式和规格组织思路上。

可以用两句话帮助记忆:

Spec Kit 更强调:如何通过结构化、可扩展的流程组织 AI 开发,并在关键阶段进行质量检查。

OpenSpec 更强调:如何管理系统当前规格,以及每一次需求变更。

这是理解它们设计侧重点的简化方式,并不是严格的能力边界。

五、通过 Android 项目理解 OpenSpec 的价值

假设我们已经上线了一款海外 App,现在需要增加一个功能:

Google Play 金币充值失败后的自动补单。

1. 不使用 SDD

我们直接告诉 Codex:

“增加金币充值失败后的自动补单功能。”

Codex 可能立即开始分析代码并进行修改。

但实际业务中存在很多需要明确的问题:

  • Google Play 购买已完成,但服务端没有发放金币怎么办?
  • 客户端重启后如何恢复?
  • Google Play 重复返回购买信息怎么办?
  • 服务端如何避免重复发放金币?
  • 用户切换账号后,如何处理订单归属?
  • 补单失败是否需要人工介入?

如果这些规则没有明确,AI 就可能自行假设处理方式。

代码即使能够编译,也不一定满足业务要求。

2. 使用 OpenSpec

我们可以先创建一个变更:

fix-google-play-recharge

然后按照流程推进。

第一步:Explore,梳理需求

先讨论充值流程中可能出现的异常情况。

例如:

  • 购买已完成,但服务端权益发放失败。
  • 客户端在支付完成后退出。
  • 服务端请求超时。
  • 同一订单重复提交。
  • 用户切换登录账号。

这一阶段重点不是写代码,而是把业务规则和边界条件明确下来。

如果发现某些规则没有确定,就先进行 Clarify 式的需求澄清,而不是让 AI 自行决定。

第二步:Propose,形成变更规格

定义自动补单的预期行为。

例如:

当 Google Play 购买已完成,但服务端尚未成功发放金币时,系统应支持重新校验购买凭证,并在验证通过后完成补发。

同时明确:

  • 必须由可信服务端验证购买状态。
  • 必须保证同一购买记录不会重复发放金币。
  • 订单必须与正确的用户账户关联。
  • 补单失败需要保留可追踪记录。
  • 不得仅凭客户端声称支付成功就发放金币。

这些规则构成了 AI 开发时需要遵守的规格。

第三步:Cross-Spec Review,跨规格一致性审查

假设项目中已经存在多个规格:

openspec/specs/
├── payment/
│   └── spec.md
├── order/
│   └── spec.md
├── wallet/
│   └── spec.md
├── subscription/
│   └── spec.md
└── account/
    └── spec.md

在实施新变更之前,需要检查新规格是否与已有规则冲突。

例如:

已有 payment/spec.md 规定:

同一笔已成功处理的购买记录,只允许发放一次金币。

但新变更提出:

用户每次点击补单按钮,都重新发放金币。

这两条规则显然存在冲突。

如果 AI 只关注新变更,而没有读取已有支付规格,就可能实现重复发放金币的错误逻辑。

因此,我们应该在实施之前增加一次跨规格一致性审查:

  1. 识别本次变更涉及的业务模块。
  2. 检索相关的已有规格。
  3. 检查是否存在重复定义或相互矛盾的业务规则。
  4. 检查是否破坏已有接口、状态机或全局约束。
  5. 对存在歧义或冲突的规则进行澄清。
  6. 确认后更新相关规格,再进入实施阶段。

这里需要注意:

OpenSpec 和 Spec Kit 都不保证在创建新 Spec 时自动读取全部历史规格,也不保证自动发现所有跨规格的业务语义冲突。

OpenSpec 的规格校验能够检查文档结构和部分增量规格问题,但不能等同于完整的跨模块语义冲突分析。

Spec Kit 的 /speckit.analyze 主要用于检查当前功能的规格、计划、任务之间的一致性,以及与 Constitution 的关系,也不能简单理解为全项目 Spec 冲突检测器。

因此,Cross-Spec Review 更适合作为团队额外建立的一项工程治理流程,而不是默认认为工具已经完整实现了这项能力。

对于复杂项目,可以要求 Agent 在实施前明确执行跨规格检查,并输出检查范围和冲突报告。

第四步:Apply,实施开发

在确认规格没有未解决的重大冲突后,让 Codex 根据规格逐项执行任务。

例如:

  1. 检查现有 BillingClient 购买流程。
  2. 增加未完成订单的恢复逻辑。
  3. 完善服务端购买验证接口。
  4. 增加订单幂等处理。
  5. 补充异常场景测试。

需要强调的是,OpenSpec 负责组织规格和开发过程,真正读取代码、修改文件和执行测试的仍然是 Codex 等编程 Agent。

第五步:Verify,验证实现

开发完成后,需要根据规格和验收标准检查:

  • 购买成功但权益发放失败时,是否能够正确补单?
  • 重复提交同一购买记录,是否会重复发放金币?
  • 网络异常是否会造成订单状态不一致?
  • 是否存在未经验证就发放金币的路径?

可以使用 OpenSpec 的可选 Verify 工作流辅助检查,也可以通过自动化测试、人工验收等方式完成。

第六步:Archive,归档变更

完成开发并通过必要的验证后,将本次变更归档,并根据流程将相关规则同步到系统当前规格中。

这样,下一次 AI 再修改充值模块时,就有机会通过现有规格了解系统已经确立的行为约束。

这正是 OpenSpec 的价值之一:

让业务规则不再只存在于某一次 AI 对话中,而是成为可维护、可版本管理的项目资产。

六、Clarify、Cross-Spec Review、Verify 有什么区别?

这三个环节很容易混淆,但解决的问题不同。

环节核心问题典型检查对象
Clarify需求是否已经说清楚?当前需求和规格
Cross-Spec Review新需求是否与已有规则冲突?当前规格、历史有效规格、并行变更
Verify实际实现是否符合规格?代码、测试、规格与任务

例如,开发金币补单功能:

Clarify:

“自动补单应该由客户端触发,还是服务端触发?”

这是需求尚未明确的问题。

Cross-Spec Review:

“新补单规则是否违反了已有的支付幂等性要求?”

这是新旧规格之间的一致性问题。

Verify:

“代码是否真的保证同一笔购买记录只发放一次金币?”

这是实现是否符合规格的问题。

三者可以形成一个更完整的质量控制流程:

提出需求
   ↓
Clarify
明确需求和边界
   ↓
形成 Spec
   ↓
Cross-Spec Review
检查新旧规格冲突
   ↓
Plan / Tasks
制定方案与任务
   ↓
Implement
执行开发
   ↓
Verify
验证实现
   ↓
Archive
归档并维护规格

这是建议的工程实践流程,不是 Spec Kit 或 OpenSpec 的统一内置工作流。

其中,Cross-Spec Review 也可以在技术设计、实施或归档前再次执行,尤其是在存在多个并行变更的情况下。

七、Spec Kit、OpenSpec 与 Harness、Agent、Skill、Workflow 有什么关系?

这是理解整个 AI 编程技术体系的重要部分。

前面我们已经知道:

  • LLM 提供推理与生成能力。
  • Agent 围绕目标采取行动。
  • Harness 支撑 Agent 的执行与控制。
  • Tools 提供文件、终端、搜索和 API 等能力。

那么 Spec Kit 和 OpenSpec 应该放在哪里?

可以通过下面的逻辑架构理解:

             开发者提出需求
                    │
                    ▼
       ┌────────────────────────┐
       │  Spec Kit / OpenSpec   │
       │                        │
       │  需求规格               │
       │  需求澄清               │
       │  技术方案               │
       │  任务拆解               │
       │  跨规格一致性审查       │
       │  验收与变更管理         │
       └────────────────────────┘
                    │
                    │ 提供规格与开发约束
                    ▼
       ┌────────────────────────┐
       │    AI 编程 Agent       │
       │  Codex / Claude Code   │
       │                        │
       │  ┌──────────────────┐  │
       │  │  Agent Harness   │  │
       │  │                  │  │
       │  │  上下文管理       │  │
       │  │  工具执行         │  │
       │  │  执行循环         │  │
       │  │  状态与权限控制   │  │
       │  └──────────────────┘  │
       │          ↕             │
       │     LLM / Tools        │
       └────────────────────────┘
                    │
                    ▼
              代码与验证结果

这是一张概念关系图,不代表真实产品内部必须采用这种模块划分。

实际上,Spec Kit 和 OpenSpec 通常通过命令、模板、Skill 和项目文件等方式与编程 Agent 集成,而不是作为一个独立服务运行在 Agent 外部。

1. 与 Harness 的关系

Harness 主要解决:

AI 如何可靠地执行任务?

例如:

  • 如何调用模型?
  • 如何读取文件?
  • 如何执行终端命令?
  • 如何管理上下文?
  • 如何处理错误?
  • 如何控制执行权限?

Spec Kit 和 OpenSpec 主要解决:

AI 应该按照什么需求、约束和流程完成任务?

两者关注点不同,但可以相互配合。

从广义上讲,规格驱动工具也可能被视为 Agent Harness 生态中的流程约束或能力扩展。

2. 与 Skill 的关系

Skill 通常用于封装可复用的任务知识、操作说明或执行规范。

例如,一个 Android 开发 Skill 可以要求:

  • 修改代码前先阅读相关模块。
  • 遵循项目现有架构。
  • 不随意引入依赖。
  • 修改完成后执行测试。

Spec Kit 和 OpenSpec 可以利用类似的机制,让 Agent 知道如何执行规格编写、需求澄清、技术规划和任务实施等工作。

但不能简单地认为:

“Spec Kit 就是一个 Skill。”

因为它们通常还包含模板、命令、配置和项目规格文件等内容。

3. 与 Workflow 的关系

Workflow 关注任务的执行流程。

例如:

需求分析
   ↓
需求澄清
   ↓
规格评审
   ↓
跨规格一致性审查
   ↓
技术设计
   ↓
任务拆解
   ↓
代码实现
   ↓
测试验收

Spec Kit 和 OpenSpec 都提供了围绕规格驱动开发组织工作的方式。

可以理解为,它们将传统软件工程中的部分开发流程,通过结构化文档和 AI 工具集成,变得更容易重复执行。

4. 与 MCP 的关系

MCP(Model Context Protocol)主要解决 AI 应用如何标准化连接外部工具和数据源的问题。

例如,Agent 可以通过 MCP 连接代码仓库、项目管理系统或其他开发工具。

而 Spec Kit 和 OpenSpec 主要管理需求规格及开发过程。

因此:

MCP 关注能力连接,Spec Kit / OpenSpec 关注开发规格与流程。

它们可以协同使用,但并不存在必须依赖的关系。

八、AI 开发者需要建立哪些认知?

我认为最重要的是建立四个认知。

认知一:SDD 不是全新的软件工程思想

需求规格、技术设计、任务拆解和测试验收,并不是 AI 时代才出现的概念。

传统软件工程早就强调:

  • 需求评审。
  • 技术方案设计。
  • 开发任务拆解。
  • 测试用例。
  • 验收标准。
  • 变更管理。

SDD 的价值,不是重新发明这些流程。

而是让结构化规格能够更直接地参与 AI 辅助开发。

例如,过去的需求文档主要由开发者阅读,再由开发者编写代码。

现在,AI 编程 Agent 也可以读取这些规格,并据此生成代码、执行任务和辅助验证。

规格从单纯供人阅读的文档,进一步成为 AI 开发过程的重要输入。

认知二:AI 的执行能力越强,需求约束越重要

过去,开发者需要亲自完成大量代码编写工作。

在这个过程中,开发者往往能够发现需求中的问题。

但 AI 编程工具可能在很短时间内生成大量代码。

如果需求本身存在歧义,AI 也可能快速实现一个错误的方案。

因此:

AI 编码效率越高,越需要重视需求澄清、边界条件和验收标准。

这也是 Clarify 重要的原因。

当然,Spec 也不保证绝对正确。

如果规格本身存在遗漏或错误,AI 仍然可能按照错误的规格进行开发。

所以,需求评审、技术决策和最终验收,仍然需要明确责任人。

认知三:规格文档是 AI 开发的重要上下文资产

这是一个很值得关注的变化。

传统 AI 对话中的很多信息,只存在于当前会话中。

例如:

  • 为什么采用某种技术方案?
  • 某个业务规则为什么这样设计?
  • 哪些异常情况必须处理?
  • 哪些模块不能随意修改?

如果这些信息没有保存下来,新的 AI 对话可能需要重新理解整个项目。

而通过 Spec Kit、OpenSpec 等工具,可以将部分重要信息沉淀为项目文件。

这些文件可以:

  • 纳入 Git 版本管理。
  • 参与代码评审。
  • 在后续开发中重新读取。
  • 帮助团队理解历史决策。
  • 作为 AI 开发的上下文来源。

这与 Agent Harness 中的 Context Engineering(上下文工程)有着直接联系。

与其只依赖不断增长的聊天记录,不如把重要的项目知识保存为可维护、可检索的工程资产。

认知四:Spec 数量增加后,需要治理跨规格一致性

当项目中只有一两个 Spec 时,开发者通常能够比较容易地理解它们之间的关系。

但随着项目不断迭代,规格数量可能逐渐增加到几十个甚至更多。

这时容易出现:

  • 不同规格重复定义相同业务规则。
  • 新规格与已有规则矛盾。
  • 某个规格已经过时,但仍被 AI 引用。
  • 多个并行变更修改同一项系统行为。
  • 跨模块约束没有被正确传递。

因此,不能简单地认为:

“项目里有 Spec,AI 就一定能够正确理解全部业务规则。”

更合理的做法是:

建立跨规格检索、冲突审查、需求澄清和变更同步机制。

例如,支付验证规则应有明确的归属,钱包模块可以引用支付结果,但不应该另行定义一套相互矛盾的支付成功标准。

这与传统软件架构中的 Single Source of Truth(单一事实来源)思想非常接近。

需要注意,单一事实来源并不意味着所有规则必须写在同一个文件中,而是强调每项关键规则应有清晰、权威的定义位置。

九、Spec Kit 和 OpenSpec 应该怎么选择?

两者都值得了解,但不一定需要同时引入。

什么时候考虑 Spec Kit?

如果团队希望:

  • 建立较为统一的 AI 开发流程。
  • 明确需求、设计和任务拆解阶段。
  • 通过 Constitution 约束 AI 编码行为。
  • 通过 Clarify 显式澄清需求。
  • 在关键阶段进行质量检查。
  • 支持自定义和扩展开发工作流。

可以优先研究 Spec Kit。

什么时候考虑 OpenSpec?

如果团队主要面对:

  • 已经上线、持续迭代的产品。
  • 频繁的功能增加和规则修改。
  • 需要记录需求变更。
  • 希望维护当前系统规格。
  • 希望让 AI 理解本次修改与现有行为的差异。
  • 倾向于在探索和迭代过程中持续澄清需求。

可以优先研究 OpenSpec。

不过,这只是基于两者设计侧重点的选择建议,不代表它们存在严格的适用边界。

对于个人开发者或小型团队,可以先选择一个实际需求试用,再根据项目复杂度决定是否长期采用。

还有一个需要避免的误区:

不是所有开发任务都需要完整的 SDD 流程。

简单的 UI 调整、明确的 Bug 修复,直接使用 AI 编程 Agent 可能更高效。

而涉及支付、账户、权限、复杂状态管理等业务时,规格驱动开发通常更值得投入。

十、总结

Spec Kit 和 OpenSpec 是理解 AI 编程工程化非常值得关注的两个项目。

如果只记住一句话:

Harness 解决的是如何让 AI 可靠地执行任务,Spec Kit 和 OpenSpec 帮助我们明确 AI 应该按照什么需求和约束完成任务。

它们背后的核心思想是 Spec-Driven Development(规格驱动开发)。

相比直接让 AI 开始写代码,SDD 更强调先明确需求、技术方案、任务和验收标准,再让 AI 执行开发。

其中:

  • Spec Kit 更强调结构化、可扩展的开发流程和质量检查机制。
  • OpenSpec 更强调当前系统规格与增量变更的管理。
  • Clarify 解决需求是否明确的问题。
  • Cross-Spec Review 解决新旧规格是否一致的问题。
  • Verify 解决实际实现是否符合规格的问题。

对于软件工程师而言,这些工具的价值并不只是提高 AI 生成代码的效率。

更重要的是:

让 AI 辅助开发从一次次临时对话,逐步转向有明确规格、可追踪变更、可验证结果的工程过程。

随着 AI 编程工具的能力不断提升,开发者的工作重点也可能逐渐从具体代码编写,向需求澄清、架构设计、任务编排、质量验证和工程治理延伸。

但无论 AI 工具如何发展,软件工程的核心问题依然存在:

我们究竟要解决什么问题?应该如何设计?如何保证实现正确?如何持续维护?

Spec Kit 和 OpenSpec,正是尝试将这些传统工程问题与 AI 编程能力结合起来的实践。


参考资料