SDD+Harness：从Vibe Coding到生产级AI全栈工程的范式跃迁

当AI编码从“代码补全”进化到“AI驱动开发”，我们面临的不再是“能不能生成代码”，而是“如何让生成的代码可控、可维护、可落地”。SDD规范驱动开发与Harness驾驭工程，正是连接AI非确定性推理与软件工程确定性要求的桥梁。

一、从Vibe Coding到Harness：AI开发的范式演进

1.1 Vibe Coding的困境

2025年以来，“Vibe Coding”风靡一时——开发者用自然语言描述需求，AI直接生成代码。这种“随性编程”确实极大提升了原型开发速度，但当项目规模膨胀到万行级别时，问题开始集中爆发：

• 风格漂移：AI生成的代码风格与团队规范不一致，命名、分层、目录结构各成体系
• 上下文溢出：复杂任务超出模型窗口限制，AI“遗忘”早期决策导致前后矛盾
• 技术债堆积：AI倾向于“能跑就行”，复用率低，重复代码遍地
• Review成本倒挂：AI生成代码花5分钟，人工Review和返工花2小时

核心矛盾在于：大模型本质是概率驱动的非确定性引擎，而软件工程要求绝对的确定性。如何弥合这一鸿沟？

1.2 三次范式跃迁

AI工程化经历了清晰的演进路径：

Harness Engineering不是简单的技术叠加，而是一套给AI智能体设立边界、搭建运行环境、实现可控自治的系统级工程方法论。它回答了一个核心问题：如何让AI在复杂代码库中像资深工程师一样工作，而非像刚入职的实习生？

二、SDD：让规范成为AI的“唯一事实来源”

2.1 什么是Spec-Driven Development

SDD（Spec-Driven Development，规范驱动开发） 的核心思想是：将需求文档（Spec）作为AI开发的“唯一事实来源”（Single Source of Truth）。与传统开发不同，SDD中的Spec不只是“文档”，而是可被AI解析、可驱动代码生成、可作为验收标准的结构化规范。

一个标准的SDD流程包含：

需求想法 → 结构化Spec撰写 → Spec Review → AI代码生成 → 自动化验证 → PR合流

2.2 SDD的核心产出物

以全栈功能开发为例，一份完整的SDD通常包含三个核心文档：

• proposal.md：需求提案，描述“为什么要做”和“要做什么”
• spec.md：技术规格，包含组件设计、接口契约、数据结构、修改范围
• tasks.md：任务拆分，每个task对应可执行的代码变更单元

关键在于，这些文档以结构化Markdown编写，AI可直接解析，而非仅供人类阅读的“说明书”。

2.3 Harness思维：让AI模仿，而非凭空创造

得物技术团队的实践揭示了一个关键洞察：Harness思维的本质是“给AI一个已有的实现作为参照，让它照着复刻一份，而不是凭空创造”。

对比两种提示词方式：

❌ 不推荐（凭空创造）：

“请实现一个结束语管理的CRUD接口。”

✅ 推荐（Harness约束）：

“请参照现有‘场景欢迎语’功能（后端接口 /api/v1/feature/list，前端入口 FeatureTable/index.tsx:53-58）实现‘结束语’功能。数据结构、分层方式、命名风格都保持一致。新增场景code：SCENARIO_CLOSING。”

两者差距在于约束和上下文的精度。后者给AI提供了明确的“模仿对象”，代码可用率从30%提升到80%以上。

三、Harness Engineering核心组件

3.1 七大核心组件

基于企业级实践，Harness Engineering包含七大核心组件：

3.2 三层落地路线

实际落地时，通常采用三步走策略：

阶段1：信息层——让AI看懂项目

• 构建AGENTS.md、REPO_WIKI.md等项目级知识文档
• 利用Codebase Indexing对代码库建立语义索引
• 目标是：AI能准确找到“在哪里改”

阶段2：约束层——让AI不能犯错

• 配置ArchUnit架构约束规则
• 定制Linter规则（ESLint、Pylint等）
• 建立CI护栏，违规自动拦截
• 目标是：AI即使想犯错也被拦住

阶段3：自动化层——让AI自我验证

• 构建自动化测试管线
• 实现Evals评估体系
• 建立基于反馈的自动修复机制
• 目标是：AI生成代码 → 自动验证 → 自动修复 → 人工最终确认

四、全栈工程实战：从需求到部署

4.1 工作区架构

全栈AI开发的关键决策是工作区组织形式。推荐采用多仓同工作区模式：

workspace/
├── service-frontend/     # 前端代码 + 前端SDD
├── service-backend/      # 后端代码 + 后端SDD
├── .cursor/              # IDE配置（Rules、SDD初始化）
└── .claude/              # CLI工具配置

将前后端放在同一工作区的价值在于：

• Codebase Indexing覆盖两侧：AI能跨仓库理解代码关系
• 接口契约自然对齐：AI同时看到前后端代码，字段命名自动保持一致
• SDD文档集中管理：便于接口契约同步评审

4.2 全栈SDD提示词范式

经过实战验证的全栈SDD提示词模板：

这是一个前后端全栈开发工作区，需要你设计技术接口方案，同时开发前后端项目。

首先你需要cd到对应前后端应用目录中，创建sdd文件。所以你需要生成两份sdd文档，之后我会启动两个agent分别实现。

前端应用：service-frontend/sdd-propose feature/your-feature-name
前端修改入口参考：@FeatureTable/index.tsx:53-58

后端应用：service-backend/sdd-propose feature/your-feature-name
后端修改入口参考接口：/api/v1/feature/list

需求内容：
[附上需求描述，并提供前后端需求点清单]

关键要素拆解：

4.3 工具链选型参考

4.4 多Agent协作模式

当项目复杂度超过单Agent能力边界时，需要引入多Agent协作框架：

                 ┌─────────────┐
                 │   Planner   │ ← 需求拆解、Spec生成
                 └──────┬──────┘
                        │
          ┌─────────────┼─────────────┐
          │             │             │
    ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
    │ Frontend  │ │ Backend   │ │ Reviewer │
    │  Worker   │ │  Worker   │ │          │
    └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
          │             │             │
          └─────────────┼─────────────┘
                        │
                 ┌──────▼──────┐
                 │  QA Agent  │ ← 自动化测试、自愈验证
                 └─────────────┘

核心原则：每个Agent有明确职责边界，通过结构化Spec作为通信协议。

五、验证体系与可观测性

5.1 三重验证机制

为保障AI生成代码质量，需建立多层验证体系：

5.2 可观测性指标

生产级Harness系统需监控以下核心指标：

• 推理延迟（P50/P99）
• 工具调用成功率
• 上下文命中率（Cache Hit Rate）
• 自动修复成功率
• Token消耗与成本

六、常见陷阱与对策

七、总结与展望

SDD+Harness的本质，是将AI从“随机文本生成器”转化为“可靠的软件工程师”。它不依赖更强的模型，而是通过工程化手段——规范驱动、上下文约束、自动验证、反馈自愈——让现有模型的能力被精准释放。

未来演进方向包括：

• 自适应Harness：系统根据任务自动调整约束策略
• 多模型协同：根据任务类型动态路由到最优模型
• 自主进化：从反馈中学习，持续优化Harness自身规则

在AI工程化时代，工程师的核心竞争力不再是“手写代码”，而是“设计AI的运行环境”——这份能力，正是Harness Engineer的使命所在。