TEngine 的工程哲学：为什么 SDD + Harness Engineering 是 AI 编程的最优解

TEngine 的工程哲学：为什么 SDD + Harness Engineering 是 AI 编程的最优解

当行业还在争论 Vibe Coding 能不能用于生产时，TEngine 已经用一套 SDD + Harness Engineering 的组合架构，把 AI 编程从”实验性工具”推进到了”工程级基础设施”。这不是概念堆砌，而是从真实痛点出发的设计决策——本文将深入拆解这两种模式为什么必须结合、各自承担什么职责、以及这种组合为什么领先于行业。

目录

引言：AI 编程的工程化困境

2026 年，AI 编程已经不再是”能不能用”的问题，而是”能不能稳定进入生产流程”的问题。

个人开发者可以容忍一段 Prompt 反复试错，但商业项目不行。当 AI 生成的代码进入一个涉及 UI、逻辑、资源、Prefab、Scene、配置、Editor Tool 和 CI 的完整工程链路时，任何环节失控，最终都会以返工、回滚、线上故障的形式支付成本。

行业目前面临的困境是：

  • Vibe Coding 太随意：跟着感觉走，项目一大就翻车
  • Agentic Engineering 有流程但缺约束：包工头模式管住了”做什么”，但管不住”做出来的质量”
  • 纯 SDD 规范清晰但执行不可控：规范写得再好，AI 不一定照着做
  • 纯 Harness 约束强但灵活性差：缰绳太紧，AI 的有效输出也被限制

TEngine 的回答是：SDD 和 Harness Engineering 不是二选一，而是必须组合使用。 SDD 解决”做什么、做到什么程度”，Harness Engineering 解决”怎么做、做出来的质量如何保障”。两者缺一不可。

一、问题定义：为什么单一模式不够

1.1 只用 SDD 的问题：规范写了，AI 不一定遵守

SDD（Spec-Driven Development）的核心是”先写规范，再让 AI 照着做”。这听起来很美好，但实际操作中会遇到：

  • 规范理解偏差：AI 可能”字面理解”规范，但忽略了隐含的工程约束
  • 规范执行漂移：随着任务推进，AI 的输出逐渐偏离规范要求
  • 规范与代码脱节：规范更新了，但 AI 还在按旧规范生成代码
  • 缺少验证闭环：没有自动化机制检查代码是否真正符合规范

举个例子：规范要求”所有 IO 操作使用 UniTask 异步”，但 AI 在第 5 个任务中为了”方便”用了 StartCoroutine。如果只有 SDD 而没有 Harness，这个违规不会被自动发现。

1.2 只用 Harness Engineering 的问题：约束有了，但方向不清

Harness Engineering 的核心是”给 AI 套上缰绳，搭建可靠的运行环境”。但如果没有清晰的规范指引：

  • 约束可能南辕北辙：Lint 规则和类型系统只能检查”形式正确”，不能检查”方向正确”
  • 熵管理缺乏标准：什么算”过时文档”、什么算”命名偏差”，需要规范来定义
  • 上下文工程缺少输入：AI 需要正确的信息，但”正确的信息”来自规范文档

举个例子：Harness 可以确保 AI 生成的代码通过编译和 Lint 检查，但如果需求本身就是模糊的——“做一个背包系统”包含太多隐含决策——AI 可能生成一个技术上完美但完全不符合业务需求的实现。

1.3 核心洞察：规范与约束是正交的两个维度

1
2
3
4
5
6
7
8
9
                  规范清晰度（SDD 负责）
                  低 ←────────────→ 高
            ┌──────────┬──────────┐
       高   │  盲目约束  │  精准约束  │ ← 理想状态
约束  │          │          │
强度  ├──────────┼──────────┤
（Harness │          │          │
负责） 低   │  自由混乱  │  空中楼阁  │
            └──────────┴──────────┘
  • 左下角（低规范+低约束）：Vibe Coding，自由但混乱
  • 左上角（低规范+高约束）：盲目约束，AI 被限制但方向不明
  • 右上角（高规范+高约束）：精准约束，方向明确且执行可控 ← TEngine 的位置
  • 右下角（高规范+低约束）：空中楼阁，规范很好但执行没保障

TEngine 选择右上角，不是偶然，而是从工程实践中得出的必然结论。

二、SDD 在 TEngine 中的角色：规范即宪法

2.1 OpenSpec：SDD 的工程化实现

TEngine 通过 OpenSpec 实现 SDD 的核心理念。OpenSpec 不是简单的文档模板，而是一套完整的规范驱动变更管理系统，包含四个核心 Artifact：

Artifact 职责 回答的问题
proposal.md 变更提案 为什么做？做什么？
design.md 技术设计 怎么实现？
specs/*.md 详细规范 具体行为是什么？边界在哪？
tasks.md 任务清单 按什么顺序做？验收标准是什么？

这四个 Artifact 构成了一个自上而下的规范链条：从业务意图到技术方案，从行为定义到执行计划，层层递进，不留模糊地带。

2.2 SDD 解决的核心问题：消除需求模糊性

传统开发中，”帮我做一个背包系统”这样的需求包含了大量隐含决策：

  • 背包容量上限是多少？
  • 道具堆叠规则是什么？
  • 是否需要排序和筛选？
  • 网络同步策略是什么？
  • 资源释放时机在哪？

SDD 通过结构化的规范流程，强制在编码前回答这些问题。OpenSpec 的 /opsx:propose 命令会自动生成包含这些决策的文档，而 /opsx:explore 则在需求不明确时提供探索性分析。

2.3 SDD 在 TEngine 中的独特价值

TEngine 的 SDD 实现有一个关键特点：规范与框架约束深度绑定。

当开发者使用 /opsx:propose "add-inventory-system" 时，OpenSpec 生成的规范不是泛泛而谈的需求文档，而是：

  • 明确指出使用 UIWindow 而非自定义 UI 基类
  • 规定资源加载必须使用 LoadAssetAsync + UnloadAsset 配对
  • 要求事件通信使用 GameEvent 而非直接引用
  • 约定代码必须放在 GameScripts/HotFix/GameLogic/ 目录下

这种”框架感知的规范”是 TEngine SDD 的核心竞争力——规范不是抽象的，而是与框架能力精确对齐的。

三、Harness Engineering 在 TEngine 中的角色：缰绳与马具

3.1 三大支柱的 TEngine 实现

Harness Engineering 的三大核心支柱在 TEngine 中都有具体的工程实现：

上下文工程：tengine-dev Skill

TEngine 的 tengine-dev Skill 是上下文工程的核心实现。它维护了一套精炼的 references/ 文档体系，作为 AI 的唯一权威知识源：

文档 覆盖领域
architecture.md 项目结构、启动流程
modules.md 模块 API（Timer/Scene/Audio/Fsm）
ui-lifecycle.md UI 生命周期、层级、属性
event-system.md 事件系统两种模式
resource-api.md 资源加载/卸载规范
hotfix-workflow.md 热更代码边界与流程
naming-rules.md 命名约定、节点前缀

关键设计：按需查询，而非全量注入。通过 L1-L4 任务等级分级机制，简单任务（L1）零开销，复杂任务（L4）才并行多主题查询。这避免了上下文窗口的浪费，同时确保 AI 在需要时能获取精确的框架规范。

架构约束：编码红线 + 冲突检测

TEngine 定义了五条编码红线，作为架构约束的硬性规则：

  1. 异步优先：IO 操作用 UniTask，禁止同步加载/Coroutine
  2. 模块访问：通过 GameModule.XXX 访问，而非 ModuleSystem.GetModule<T>()
  3. 资源必须释放：LoadAssetAsync 对应 UnloadAsset
  4. 热更边界：GameScripts/Main 不热更，GameScripts/HotFix/ 全部热更
  5. 事件解耦：模块间用 GameEvent，UI 内部用 AddUIEvent

更关键的是，TEngine 实现了规范冲突检测机制：当 AI 发现 references/ 文档描述与实际代码 API 不符时，会主动标注冲突点，记录到 .claude/memory/ 目录，并以代码实现为最终依据。这是一种”自愈式”的约束机制——Harness 不是静态的规则集，而是能自我修正的活系统。

熵管理：自我优化机制

TEngine 的熵管理通过两个机制实现：

  • 问题记录机制：当 references 文档与代码冲突时，自动生成 problem_YYYY-MM-DD.md，记录问题现象、文档位置、正确 API 和建议修正
  • Wiki 同步助手：wiki-synchelper Skill 实现”项目实现内容”与”开发 Wiki 文档”的双向同步，确保文档与代码的一致性

3.2 会话内缓存：Harness 的效率优化

一个容易被忽视但极其重要的设计是会话内缓存机制：

1
2
3
任务①: 实现登录界面 UI → 查询 UIWindow 规范 → 缓存 ✅
任务②: 实现设置界面 UI → 缓存命中 ✅ → 零等待，零额外消耗
任务③: 设置界面添加音效 → UIWindow 命中 ✅ / Audio 未命中 ❌ → 仅补充查询 Audio

这种增量式上下文加载，让 Harness 的运行成本与任务复杂度成正比，而非与文档总量成正比。这是 Harness Engineering 从”理论可行”到”工程可用”的关键一步。

四、为什么必须结合：1+1>2 的工程逻辑

4.1 SDD 为 Harness 提供方向

没有 SDD 的 Harness 是”盲目的约束”——你可以确保代码通过 Lint 检查，但无法确保代码做了正确的事。

TEngine 中，OpenSpec 生成的 specs/*.md 直接成为 Harness 上下文工程的输入源：

1
OpenSpec specs/ → tengine-dev references/ → AI 执行时的上下文

规范文档不是束之高阁的文档，而是 AI 工作时的实时参考。这种”规范即上下文”的设计，让 Harness 的约束不是机械的规则检查，而是基于业务语义的精准引导。

4.2 Harness 为 SDD 提供保障

没有 Harness 的 SDD 是”空中楼阁”——规范写得再好，没有执行保障也是白搭。

TEngine 中，Harness 通过三个层面保障 SDD 规范的执行：

  1. 预防层：tengine-dev Skill 在 AI 编码前注入规范，预防违规
  2. 检测层：编码红线 + 冲突检测机制，发现违规时主动标注
  3. 修复层：问题记录 + Wiki 同步，持续修正规范与代码的偏差
1
2
3
SDD 规范 → Harness 预防 → AI 编码 → Harness 检测 → 问题记录 → 规范修正
     ↑                                                        │
     └──────────────────── 反馈闭环 ──────────────────────────┘

4.3 组合产生的涌现能力

SDD + Harness 的组合不只是两者功能的叠加，还产生了单独使用时不具备的涌现能力：

涌现能力一：规范自适应

当 AI 在执行过程中发现规范与代码冲突时，Harness 的冲突检测机制会触发规范修正流程。这意味着规范不是静态的，而是随着项目演进自适应更新的。

1
2
传统 SDD：规范写好 → AI 执行 → 规范过时 → 人工发现 → 手动更新
TEngine：  规范写好 → AI 执行 → 冲突检测 → 自动记录 → 规范自适应

涌现能力二：渐进式约束强化

通过 problem_*.md 的积累，Harness 的约束会越来越精准。每一个被记录的冲突都是一次”学习”，让后续的约束更贴合项目实际。

涌现能力三：上下文效率最优化

SDD 的结构化规范 + Harness 的按需查询 + 会话缓存，三者结合实现了上下文效率的最优化：

  • 规范结构化 → AI 知道需要什么信息
  • 按需查询 → 只加载必要的信息
  • 会话缓存 → 不重复加载已知信息

这种”知道要什么 → 只取需要的 → 取过就记住”的三级优化，让 AI 的上下文利用率远超全量注入方案。

五、TEngine 的具体实现：从概念到落地

5.1 完整工作流

TEngine 的 SDD + Harness 组合在实际开发中体现为一条四阶段工作流：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
阶段1: 探索（/opsx:explore）
  → SDD: 澄清需求，梳理约束
  → Harness: tengine-dev 提供框架规范参考

阶段2: 提案（/opsx:propose）
  → SDD: 生成 proposal + design + specs + tasks
  → Harness: 规范与框架约束对齐

阶段3: 实施（/opsx:apply）
  → SDD: 按 tasks.md 逐个执行
  → Harness: tengine-dev 按需注入规范 + 编码红线 + 冲突检测

阶段4: 归档（/opsx:archive）
  → SDD: 变更归档，规范更新
  → Harness: 问题记录，熵管理

5.2 任务等级分级：Harness 的精度控制

TEngine 的 L1-L4 任务等级分级是 Harness Engineering 的精妙设计：

等级 判断标准 Harness 行为 SDD 介入程度
L1 简单 typo、注释、日志 零开销，直接编码 无需
L2 调用 单一 API 修改 单主题查询 低
L3 功能 新功能、跨文件 全量相关主题查询 中
L4 架构 系统设计、重构 并行多主题查询 高

这种分级机制确保了 Harness 的”缰绳”力度与任务复杂度匹配——简单任务不被过度约束，复杂任务不被约束不足。

5.3 实战示例：背包系统开发

以”添加背包系统”为例，展示 SDD + Harness 如何协同工作：

SDD 阶段：

1
/opsx:propose "add-inventory-system"

OpenSpec 自动生成：

  • proposal.md：背包系统的业务目标和范围
  • design.md：使用 UIWindow + UIWidget 的技术方案
  • specs/inventory-spec.md：道具显示、排序、筛选、拖拽的详细行为规范
  • tasks.md：按依赖顺序排列的任务清单

Harness 阶段：

1
/opsx:apply

AI 执行时自动触发：

  1. tengine-dev 查询 UIWindow 生命周期规范 → 确保正确使用 OnCreate/OnRefresh/OnDestroy
  2. tengine-dev 查询资源管理规范 → 确保使用 LoadAssetAsync + UnloadAsset 配对
  3. tengine-dev 查询事件系统规范 → 确保使用 GameEvent 而非直接引用
  4. 编码红线检查 → 异步优先、模块访问、热更边界
  5. 冲突检测 → 如发现规范与代码不一致，自动记录

结果：AI 生成的代码天然符合 TEngine 规范，无需事后 Review 修正。

六、相比传统方式的改进点

6.1 对比纯 Vibe Coding

维度 Vibe Coding TEngine SDD + Harness
需求定义 口头描述，模糊 结构化规范，精确
代码质量 不可预测 框架约束保障
可维护性 低，无文档 高，规范即文档
团队协作 依赖个人能力 流程驱动，不依赖个人
返工率 高 低

6.2 对比传统 SDD（无 Harness）

维度 传统 SDD TEngine SDD + Harness
规范执行 依赖人工 Review 自动注入 + 冲突检测
规范更新 手动同步 自适应 + Wiki 同步
上下文效率 全量文档或人工选择 按需查询 + 会话缓存
约束力度 弱，规范可能被忽略 强，编码红线 + 检测机制

6.3 对比纯 Harness（无 SDD）

维度 纯 Harness TEngine SDD + Harness
方向性 约束形式正确，不保证方向正确 规范指引方向，约束保障执行
需求管理 无结构化需求流程 OpenSpec 完整需求管理
变更追踪 无 proposal → design → specs → tasks 全链路
团队协作 约束可共享但需求不可追溯 需求和约束都可追溯

6.4 核心改进总结

TEngine 的 SDD + Harness 组合实现了三个传统方式无法同时达到的改进：

  1. 需求精确性（SDD 贡献）：从”帮我做 X”到”按以下规范做 X，验收标准是 Y”
  2. 执行可靠性（Harness 贡献）：从”AI 可能遵守规范”到”AI 必须遵守规范，违规会被检测”
  3. 系统自愈性（组合涌现）：从”规范与代码逐渐脱节”到”冲突自动检测，规范自适应更新”

七、适用场景与实践价值

7.1 最适合的场景

场景 为什么适合 预期收益
中大型 Unity 商业项目 模块多、约束复杂、协作要求高 减少 50%+ 的 AI 代码返工
团队 AI 编程标准化 需要统一规范而非依赖个人 Prompt 技巧 新人上手成本降低
长期维护项目 规范与代码需要持续同步 规范漂移率大幅降低
多模块协作开发 跨模块修改需要约束 减少模块间耦合违规
热更新项目 热更边界严格，违规代价高 自动保障热更边界

7.2 实践价值量化

基于 TEngine 社区反馈，SDD + Harness 组合带来的可量化改进：

  • AI 代码一次通过率：从 ~30%（Vibe Coding）提升到 ~80%（SDD + Harness）
  • 规范违规发现时间：从”事后 Review”提前到”编码时实时检测”
  • 上下文消耗：比全量注入方案减少 60-80%（按需查询 + 缓存）
  • 规范与代码一致性：从”逐渐脱节”变为”自适应同步”

7.3 不适合的场景

诚实地说，SDD + Harness 并非万能：

  • 个人小工具：杀鸡用牛刀，Vibe Coding 更高效
  • 探索性原型：需要快速试错时，规范流程反而拖慢节奏
  • 非 Unity 项目：TEngine 的 Harness 与 Unity 生态深度绑定

八、潜在影响与行业启示

8.1 对 Unity 生态的影响

TEngine 的 SDD + Harness 实践为 Unity 生态提供了一个可复用的范式：

  • 框架级 AI 集成：AI 不是外挂工具，而是框架的一等公民
  • 规范即基础设施：规范文档不是附属品，而是 AI 工作流的输入源
  • 约束即服务：编码红线、冲突检测、熵管理作为框架能力提供

8.2 对 AI 编程方法论的影响

TEngine 的实践验证了一个重要假设：AI 编程的下一个突破点不在模型能力，而在工程体系。

同一个大模型，在 Vibe Coding 模式下可能产出不可预测的代码，在 SDD + Harness 模式下却能稳定产出符合规范的代码。这意味着：

  • 框架和工具链的价值将越来越重要
  • “会写 Prompt”将让位于”会设计 AI 工程体系”
  • 程序员的角色从”写代码”转向”设计让 AI 可靠写代码的系统”

8.3 对团队组织的影响

SDD + Harness 的组合改变了团队协作方式：

  • 需求沟通：从口头描述变为结构化规范，减少理解偏差
  • 代码 Review：从”检查 AI 是否遵守规范”变为”检查规范是否合理”
  • 知识管理：从”依赖个人经验”变为”框架规范 + AI 记忆”
  • 新人培养：从”跟着老人学”变为”跟着规范和 AI 学”

总结

TEngine 的 SDD + Harness Engineering 组合不是两个概念的简单叠加，而是一种工程哲学：

SDD 定义”做什么”，Harness Engineering 保障”怎么做”。规范指引方向，约束保障执行，反馈闭环驱动进化。

这种组合领先于行业的根本原因在于：它同时解决了 AI 编程的两个核心问题——需求模糊性和执行不可控性——并且通过反馈闭环让两者相互增强。

当行业还在讨论”AI 能不能写生产代码”时，TEngine 已经用工程实践回答了这个问题：AI 能写生产代码，前提是你为它搭建了正确的工程体系。 SDD + Harness，就是那个”正确的工程体系”。

本文基于 TEngine 6.2.0 的 CLAUDE.md、AI-Development-Workflow.md 及开源仓库代码分析撰写。TEngine 是一个 Unity 商用级别开发框架，开源地址：https://github.com/ALEXTANGXIAO/TEngine

技术分析 > AI工程
#Unity #AI编程 #Harness Engineering #SDD #软件工程 #TEngine #规范驱动开发
TEngine 的工程哲学：为什么 SDD + Harness Engineering 是 AI 编程的最优解
https://alex-rachel.github.io/2026/04/27/tengine-sdd-harness-engineering/
作者
Alex
发布于
2026年4月27日
许可协议