SDD规范驱动 + Harness驾驭工程AI全栈开发

——从“提示词工程”到“规范驱动工程”的进化之路

前言：AI编码的“第二次浪潮”

2025年，Cursor、Copilot、Codex让开发者体验到了“AI辅助编码”的魔力。但很快，大家发现了一个尴尬的现实：

• AI生成的代码质量参差不齐
• 缺乏统一的规范和约束
• 无法融入企业的CI/CD流水线
• 代码审查变成了“AI代码debug大会”

于是，SDD（Specification-Driven Development，规范驱动开发） 应运而生，而 Harness 作为AI工程化平台，正在成为驾驭这股力量的关键缰绳。

第一章：SDD——让AI“按规矩办事”

1.1 什么是SDD？

规范驱动开发（Specification-Driven Development） 是一种将规范（Specification） 作为“单一事实来源”的开发范式。

核心思想： 先写“要做什么”（Spec），再让AI生成“怎么做”（Code），最后用Spec验证“做对了没”（Test）。

与传统开发对比：

1.2 SDD的三层规范体系

在实践中，SDD需要建立三层规范金字塔：

        ┌─────────────────────┐
        │   业务规范层 (Gherkin) │  ← 用户故事、验收标准
        ├─────────────────────┤
        │   架构规范层 (ADL)    │  ← 模块划分、接口契约、数据流
        ├─────────────────────┤
        │   代码规范层 (Linter)  │  ← 命名、格式、安全规则、测试覆盖率
        └─────────────────────┘

实战示例：

# 业务规范层 - 用Gherkin描述需求
Feature: 用户订单退款
  作为 已购用户
  我希望 在订单支付后30分钟内申请退款
  以便 获得全额自动退款

  Scenario: 30分钟内申请退款
    Given 用户已支付订单 "ORD-2026-001"
    And 当前时间距离支付时间 < 30分钟
    When 用户发起退款申请
    Then 系统自动批准退款
    And 退款金额 = 订单总额
    And 库存恢复

# 架构规范层 - 定义接口契约 (OpenAPI规范)
paths:
  /api/v1/refund:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [orderId, reason]
              properties:
                orderId: { type: string, pattern: '^ORD-\d{3}-\d+$' }
                reason: { type: string, maxLength: 500 }
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                required: [refundId, amount, status]

// 代码规范层 - 用自定义规则约束AI生成 (示例)
{
  "ai_rules": {
    "naming": { "function": "camelCase", "class": "PascalCase" },
    "error_handling": "必须使用Result<T, E>模式，禁止panic",
    "logging": "所有外部调用必须记录requestId和耗时",
    "testing": "每个public方法必须有对应的单元测试，覆盖率≥80%"
  }
}

1.3 SDD的核心收益

1. AI行为可预测： 给AI喂Spec而非模糊需求，输出稳定可控
2. 知识沉淀： Spec本身就是活的文档，新人或新AI接手成本极低
3. 自动化验证： Spec可直接转化为测试用例，实现“Spec即测试”
4. 跨团队协作： 产品、架构、开发、测试共用同一套Spec语言

第二章：Harness——给工程AI装上“方向盘”

2.1 Harness是什么？

Harness 是一个AI驱动的软件交付工程化平台，它不仅是CI/CD工具，更是：

• AI代码生成的质量闸门
• 全栈开发流程的编排引擎
• 工程效能的度量与优化中心

通俗理解：如果SDD是“交通规则”，Harness就是“智能交通管理系统”——它知道谁在开车、开得好不好、有没有违规、需不需要干预。

2.2 Harness的核心能力矩阵

2.3 Harness如何与SDD协同工作？

完整工作流：

┌──────────────┐
│  产品经理编写  │
│  Gherkin Spec │
└──────┬───────┘
       │
       ▼
┌──────────────┐     ┌──────────────┐
│  Harness解析  │────▶│  自动生成    │
│  Spec并生成   │     │  测试用例    │
│  任务拆解     │     │              │
└──────┬───────┘     └──────────────┘
       │
       ▼
┌──────────────┐
│  调用Codex/   │
│  Claude生成   │
│  代码（受规范 │
│  约束）       │
└──────┬───────┘
       │
       ▼
┌──────────────┐     ┌──────────────┐
│  Harness AI  │────▶│  不通过 →    │
│  Code Review │     │  自动打回重写 │
└──────┬───────┘     └──────────────┘
       │ 通过
       ▼
┌──────────────┐
│  自动部署到   │
│  测试环境     │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  运行测试套件 │
│  （来自Spec） │
└──────┬───────┘
       │ 全部通过
       ▼
┌──────────────┐
│  Quality Gate│
│  评估 → 灰度 │
│  发布        │
└──────────────┘

第三章：实战——用SDD+Harness构建“智能退款系统”

让我们通过一个完整的实战案例，把这套方法论跑通。

3.1 Step 1：编写规范（Spec）

文件：specs/refund.feature

Feature: 智能退款系统
  作为 电商平台
  我希望 自动化处理退款申请
  以便 提升用户满意度和运营效率

  Rule: 退款资格校验
    Scenario: 30分钟内全额退款
      Given 订单支付时间 < 30分钟
      And 订单状态为 "已支付"
      When 用户申请退款
      Then 自动批准全额退款
      And 退款原路返回

    Scenario: 超过30天拒绝退款
      Given 订单支付时间 > 30天
      When 用户申请退款
      Then 拒绝退款并提示联系客服

  Rule: 风控拦截
    Scenario: 同一用户频繁退款触发风控
      Given 用户过去7天退款次数 > 3
      When 用户再次申请退款
      Then 标记为"人工审核"
      And 发送风控告警

文件：specs/refund-api.yaml（OpenAPI 3.0，篇幅原因仅展示核心部分）

paths:
  /api/v1/refund/apply:
    post:
      operationId: applyRefund
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [orderId, userId, reason]
      responses:
        '200':
          description: 退款申请已处理
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AutoApprovedResponse'
                  - $ref: '#/components/schemas/ManualReviewResponse'
                  - $ref: '#/components/schemas/RejectedResponse'

3.2 Step 2：Harness流水线配置

文件：harness/pipeline.yaml

pipeline:
  name: "SDD-Refund-Pipeline"
  stages:
    - name: "Spec解析与任务拆解"
      type: "ai-planning"
      inputs:
        spec_path: "./specs/*.feature"
      outputs:
        tasks: "tasks.json"

    - name: "AI代码生成"
      type: "ai-codegen"
      inputs:
        model: "openai/codex"
        spec_ref: "./specs/refund-api.yaml"
        rules_ref: "./.ai-rules.json"
      outputs:
        code_path: "./src/generated/"

    - name: "AI代码审查"
      type: "ai-review"
      inputs:
        code_path: "./src/generated/"
        rules_ref: "./.ai-rules.json"
      conditions:
        score_threshold: 8.0  # 满分10分，低于8分自动打回
      outputs:
        review_report: "review-report.json"

    - name: "自动生成测试"
      type: "ai-testgen"
      inputs:
        spec_path: "./specs/refund.feature"
        code_path: "./src/generated/"
      outputs:
        test_path: "./tests/generated/"

    - name: "执行测试"
      type: "test-runner"
      inputs:
        test_path: "./tests/generated/"
      quality_gates:
        - name: "覆盖率"
          threshold: 80%
        - name: "所有场景通过"
          threshold: 100%

    - name: "部署与灰度"
      type: "deploy"
      strategy: "canary"
      feature_flags:
        - "refund_v2_enabled"

3.3 Step 3：AI根据规范生成代码（示例输出）

AI在Harness调度下，受规范约束生成的代码：

# src/generated/refund_service.py
# 此文件由AI生成，受 .ai-rules.json 规范约束

from datetime import datetime, timedelta
from typing import Union
from pydantic import BaseModel, Field, validator
import logging
from src.core.result import Result, Ok, Err

# 规范要求：所有public函数必须有类型注解和docstring
class RefundRequest(BaseModel):
    order_id: str = Field(..., pattern=r'^ORD-\d{3}-\d+$')
    user_id: str
    reason: str = Field(..., max_length=500)

    @validator('order_id')
    def validate_order_format(cls, v):
        # 规范要求：输入校验必须清晰
        if not v.startswith('ORD-'):
            raise ValueError('订单号格式不正确')
        return v

class RefundService:
    def __init__(self, order_repo, risk_repo):
        self.order_repo = order_repo
        self.risk_repo = risk_repo
        self.logger = logging.getLogger(__name__)

    # 规范要求：每个public方法必须有单元测试覆盖
    def apply_refund(self, request: RefundRequest) -> Result[Union[AutoApproved, ManualReview, Rejected], str]:
        """
        处理退款申请，遵循SDD规范中的业务规则。

        规则来源: specs/refund.feature
        """
        # 规范要求：所有外部调用必须记录requestId和耗时
        with self.logger.context(request_id=request.order_id):
            self.logger.info(f"处理退款申请: {request.order_id}")

            # 1. 获取订单信息
            order = self.order_repo.get_by_id(request.order_id)
            if not order:
                return Err("订单不存在")

            # 2. 规范要求：使用Result模式处理错误，禁止panic
            elapsed = datetime.now() - order.paid_at

            # 3. 业务规则：超过30天拒绝
            if elapsed > timedelta(days=30):
                self.logger.warning(f"订单超过30天，拒绝退款: {request.order_id}")
                return Ok(RejectedResponse(
                    reason="订单已超过30天退款期限，请联系客服",
                    contact="support@example.com"
                ))

            # 4. 风控规则：频繁退款触发人工审核
            recent_refunds = self.risk_repo.count_refunds(request.user_id, days=7)
            if recent_refunds > 3:
                self.logger.warning(f"用户频繁退款，触发风控: {request.user_id}")
                return Ok(ManualReviewResponse(
                    reason="风控规则触发，需人工审核",
                    estimated_time="24小时内"
                ))

            # 5. 30分钟内全额退款
            if elapsed < timedelta(minutes=30):
                return Ok(AutoApprovedResponse(
                    refund_id=f"REF-{datetime.now().strftime('%Y%m%d%H%M%S')}",
                    amount=order.total_amount,
                    status="approved"
                ))

            # 6. 其他情况：标准流程
            return Ok(ManualReviewResponse(
                reason="常规退款流程，需人工审核",
                estimated_time="48小时内"
            ))

3.4 Step 4：Harness自动审查与测试

AI审查报告（Harness生成）：

{
  "score": 8.7,
  "checks": [
    {"rule": "类型注解完整性", "passed": true, "score": 1.0},
    {"rule": "错误处理规范 (Result模式)", "passed": true, "score": 1.0},
    {"rule": "日志规范 (包含requestId)", "passed": true, "score": 1.0},
    {"rule": "输入校验", "passed": true, "score": 1.0},
    {"rule": "函数复杂度 (Cyclomatic ≤ 10)", "passed": true, "score": 1.0},
    {"rule": "与Spec的一致性 (Gherkin场景覆盖)", "passed": false, "score": 0.7,
     "comment": "Spec中'同一用户7天退款>3次'场景已实现，但缺少对'退款金额=订单总额'的显式校验"},
    {"rule": "安全规范 (无硬编码密钥等)", "passed": true, "score": 1.0},
    {"rule": "测试覆盖率预测", "passed": false, "score": 0.5,
     "comment": "当前仅覆盖Happy Path，建议补充风控拒绝、30天拒绝等边界场景"}
  ],
  "recommendations": [
    "建议在AutoApprovedResponse中显式断言 refund_amount == order.total_amount",
    "建议补充测试用例: test_refund_reject_over_30_days, test_refund_risk_trigger"
  ],
  "auto_fix": true  // Harness可以自动修复部分问题
}

3.5 Step 5：部署策略与Feature Flag

# Harness部署配置
deployment:
  strategy: canary
  stages:
    - weight: 10%
      flag: "refund_v2_enabled"
      condition: "quality_gate.passed"
    - weight: 50%
      wait: 30min
      monitor: "error_rate < 0.5%"
    - weight: 100%
      wait: 1h
      monitor: "error_rate < 0.1%"

  rollback:
    trigger: "error_rate > 1%"
    action: "auto_rollback"

第四章：全栈开发的完整技术栈

一套完整的SDD+Harness全栈方案，需要以下技术组件：

4.1 前端层

4.2 后端层

4.3 工程化层

4.4 AI工程化层

第五章：落地路线图——从0到1的6个月计划

Phase 1：规范先行（Month 1-2）

• 选择1个核心业务模块（如退款、用户注册）
• 用Gherkin编写完整的业务规范
• 用OpenAPI定义接口契约
• 建立团队规范评审机制

Phase 2：工具链搭建（Month 2-3）

• 部署Harness基础环境
• 配置AI Code Review规则（从Linter规则开始）
• 搭建Spec到测试的自动转化管道
• 实现简单的“Spec→AI生成→人工审查”流程

Phase 3：试点项目跑通（Month 3-4）

• 选择1个低风险模块完全用SDD方式交付
• 统计质量指标（Bug率、代码审查时长、部署频率）
• 收集团队反馈，优化规范模板

Phase 4：规模化推广（Month 4-5）

• 将规范覆盖扩展到3-5个核心服务
• 建立规范库（Spec Library），允许跨项目复用
• 接入生产环境监控，建立质量反馈闭环

Phase 5：智能化升级（Month 5-6）

• 引入AI Test Generation自动补充边缘用例
• 开启Harness Auto-Fix能力
• 建立“规范变更→代码自动适配”机制
• 用混沌工程验证规范的完备性

第六章：避坑指南——我踩过的5个坑

坑1：Spec写得过于详细，变成“伪代码”

• 现象： Spec写成了详细设计文档，AI只需机械翻译，开发体验极差
• 对策： Spec只写What（业务规则、约束条件），不写How（实现细节）

坑2：规范与代码脱节

• 现象： 代码改了，Spec没更新，两周后Spec已完全失效
• 对策： 在CI流水线中强制检查“代码变更是否伴随Spec更新”，使用Harness的Diff校验

坑3：过度依赖AI生成全部代码

• 现象： 生成的代码80%可用，但20%的“长尾”问题花了80%的时间修复
• 对策： 让AI负责结构化代码（CRUD、DTO、Mapper），复杂业务逻辑人机协作

坑4：忘记成本治理

• 现象： AI API调用成本从$100/月暴涨到$5000/月
• 对策： 使用Harness Cost Governance设置预算告警，对非关键任务使用开源模型（如Qwen、DeepSeek）

坑5：忽略了“人的规范”

• 现象： 技术规范落地了，但团队沟通规范、代码审查规范还是老样子
• 对策： SDD不仅是技术转型，更是文化转型。需要配套的培训和激励机制

结语：从“AI辅助编程”到“规范驱动工程”

SDD + Harness的组合，代表了一次根本性的范式转移：

最关键的认知转变： 在SDD的世界里，规范是资产，代码是负债。代码越少越好，规范越完整越强。

Harness作为这个体系中的“工程AI大脑”，让规范不再是挂在墙上的装饰品，而是驱动每一次代码生成、审查、测试、部署的活水源泉。

本作品采用《CC 协议》，转载必须注明作者和本文链接