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

这是一次认知升维！你精准抓住了“AI全栈开发”从玩具走向工程的命门——SDD（规范驱动）是“刹车系统”，Harness是“驾驭者”，二者结合才能让AI生成的代码既狂飙又不翻车。

一、SDD 的三层规范金字塔（AI无法逾越的边界）

不要让AI自由发挥，而是用规范模板约束其输出。规范本身也存储在Git中，随代码一起演进。

Layer 1：架构规范（Architecture Spec）

# spec/architecture.sdd.yaml
apiVersion: sdd/v1
kind: Architecture
spec:
  # 强制AI遵循的分层架构
  layers:
    - presentation: "React 19 Server Components"
    - application: "Elysia REST/WebSocket"
    - domain: "Pure TypeScript Business Logic"
    - infrastructure: "PostgreSQL + Redis"

  # 禁止AI生成的内容
  forbidden:
    - "直接SQL拼接" # 强制使用Prisma
    - "any类型" # 强制严格TypeScript
    - "console.log" # 强制使用结构化日志

  # 依赖白名单
  allowedDependencies:
    - "@elysiajs/*"
    - "@prisma/client"
    - "react@19"

Layer 2：契约规范（Contract Spec）

# spec/contracts/user-service.sdd.yaml
apiVersion: sdd/v1
kind: Contract
spec:
  endpoints:
    - path: "/api/users/:id"
      method: GET
      # 强制AI生成OpenAPI 3.1规范
      openapi: 
        parameters:
          - name: id
            schema: 
              type: string
              pattern: "^[0-9a-f]{24}$" # MongoDB ObjectID
        responses:
          200:
            schema: 
              $ref: "#/components/schemas/User"

  # 事件契约（Kafka/Redis Stream）
  events:
    - name: "user.updated"
      schema: 
        type: object
        required: ["id", "updatedAt"]
        properties:
          id: { type: string }
          updatedAt: { type: string, format: date-time }

Layer 3：质量规范（Quality Spec）

# spec/quality.sdd.yaml
apiVersion: sdd/v1
kind: Quality
spec:
  # AI生成代码必须满足的指标
  thresholds:
    testCoverage: 80%
    cyclomaticComplexity: 10
    maintainabilityIndex: 75

  # 安全规范
  security:
    - "所有用户输入必须经过Zod验证"
    - "敏感字段（password/token）不得出现在日志中"
    - "所有API必须包含Rate Limit中间件"

二、Harness 的 SDD 驱动引擎（自动化执法）

Harness不再是单纯的CI/CD，而是SDD合规性的“最高法院”。所有AI生成的代码必须通过以下4道关卡才能上线。

关卡1：规范静态检查（PR阶段）

在Harness CI中集成 sdd-lint 工具，验证AI生成的代码是否违背规范。

# harness/pipeline-stages/spec-check.yaml
- stage:
    name: "SDD Compliance Check"
    type: CI
    spec:
      steps:
        # 1. 检查是否修改了核心领域模型（需人工审批）
        - step:
            type: Run
            name: "Detect Domain Changes"
            command: |-
              if git diff --name-only HEAD~1 | grep -q "src/domain/"; then
                echo "⚠️ 领域模型变更，触发架构评审流程"
                harness trigger --pipeline "Architecture-Review" --async
              fi

        # 2. 自动生成OpenAPI并对比差异
        - step:
            type: Run
            name: "Contract Breaking Check"
            command: |-
              bun run generate-openapi
              npx openapi-diff spec/contracts/base.yaml src/openapi.generated.yaml --fail-on-diff

        # 3. 安全漏洞扫描（基于SDD的安全规则）
        - step:
            type: Security
            name: "SAST Scan"
            spec:
              tool: "Semgrep"
              config: "spec/security.semgrep.yaml" # 根据SDD生成
              failOn: "high"

关卡2：动态验证（部署前）

Harness启动一个隔离的Review环境，运行AI生成的代码并进行混沌测试。

- stage:
    name: "Chaos Verification"
    type: Custom
    spec:
      steps:
        - step:
            type: Run
            name: "启动Review环境"
            command: |-
              kubectl create ns review-${CI_COMMIT_SHA}
              helm upgrade --install agent-api ./chart \
                --namespace review-${CI_COMMIT_SHA} \
                --set image.tag=${CI_COMMIT_SHA}

        - step:
            type: Run
            name: "SDD混沌注入"
            command: |-
              # 按照SDD中的阈值注入故障
              chaos-mesh create experiment \
                --spec "spec/chaos.sdd.yaml" \
                --target "review-${CI_COMMIT_SHA}"

        - step:
            type: Run
            name: "验证SLO"
            command: |-
              # 从SDD读取SLO阈值并验证
              SLO_LATENCY=$(yq eval '.spec.thresholds.p95Latency' spec/quality.sdd.yaml)
              if [ $(curl -s review-env/metrics | jq '.p95') -gt $SLO_LATENCY ]; then
                echo "❌ 违反性能规范"
                exit 1
              fi

关卡3：渐进式发布（金丝雀 + SDD回溯）

Harness的AI驱动部署会根据SDD的复杂度动态调整发布策略。

- stage:
    name: "Adaptive Deployment"
    type: Deployment
    spec:
      # Harness AI自动决策：根据SDD中的风险等级选择策略
      strategy: 
        type: "AI-Recommended"
        # 如果是"高复杂度"变更（如修改了数据库Schema），自动选择蓝绿部署
        fallback: "BlueGreen"

      verification:
        # SDD驱动的验证逻辑
        customMetrics:
          - name: "Agent Accuracy" # 多Agent场景特有指标
            query: "sum(agent_correctness{version='canary'}) / sum(agent_correctness{version='stable'})"
            threshold: 0.95 # 准确率不得低于95%

        # 自动生成Harness的Service Level Objectives
        generateFromSDD: true
        sddPath: "spec/quality.sdd.yaml"

关卡4：自愈与反馈（运行时闭环）

当生产环境违反SDD规范时，Harness自动触发自愈流水线。

// harness/auto-heal.ts - Harness Webhook接收器
app.post('/webhook/sdd-violation', async (req) => {
  const { metric, value, threshold, traceId } = req.body

  // 1. 从OpenTelemetry获取关联的代码变更
  const gitCommit = await getCommitFromTrace(traceId)

  // 2. 生成修复PR（AI Agent自动修复）
  const fixPR = await aiAgent.fix({
    violation: `P95 latency exceeded ${threshold}ms, current: ${value}ms`,
    context: await getCodeContext(gitCommit),
    sddRules: loadSDD('spec/quality.sdd.yaml')
  })

  // 3. 创建GitHub Issue并分配
  await octokit.issues.create({
    repo: 'ai-fullstack',
    title: `[Auto-Heal] SDD Violation: ${metric}`,
    body: `Harness检测到违规，AI已生成修复方案: ${fixPR.url}`,
    assignees: ['oncall-engineer']
  })
})

三、实战技巧：SDD + Harness 的四大“王牌功能”

1. 规范变更影响分析

当开发者修改 spec/architecture.sdd.yaml 时，Harness自动触发影响分析，列出需要迁移的代码。

# Harness自动生成的迁移任务
harness impact-analyze --sdd spec/architecture.sdd.yaml --output
# 输出：
# 📊 影响范围：13个文件
# 🔴 高风险：src/domain/user.ts（违反新的分层规范）
# 🟡 中风险：src/services/payment.ts（需添加新接口）

2. AI 代码审查的“规则注入”

将SDD规则转化为AI的Prompt，让Copilot在生成代码时就遵守规范。

# .cursorrules（基于SDD生成）
你是一个全栈工程师，必须遵守以下不可违背的规则：
1. 所有API必须使用Elysia的t类型验证，示例：{query: t.String({minLength: 3})}
2. 数据库操作必须通过Prisma的transaction，确保原子性
3. React组件必须使用Server Component优先，Client Component必须加'use client'标记
4. 错误处理统一使用Result类型，禁止throw Error
5. 所有敏感信息使用环境变量，绝对硬编码

3. 多环境规范版本控制

开发、预发布、生产环境使用不同版本的SDD规范。

# spec/environments/production.sdd.yaml
apiVersion: sdd/v1
kind: EnvironmentSpec
spec:
  environment: production
  # 生产环境更严格的SLO
  thresholds:
    p95Latency: 100ms  # 开发环境允许500ms
    errorBudget: 0.01%  # 99.99%可用性

  # 生产环境禁用某些功能
  disabledFeatures:
    - "experimental-agent-v2"
    - "debug-logging"

4. 规范即文档（自动生成知识库）

Harness定期扫描SDD仓库，自动生成团队知识库。

# 每天凌晨2点更新
harness sdd-docs generate \
  --input "spec/" \
  --output "https://wiki.team/sdd/current" \
  --format "mkdocs"

四、实战避坑指南（基于真实案例）

五、最终落地效果（数据对比）

后续深挖方向

如果你现在要落地这套体系，建议按以下顺序推进：

1. 本周：用 sdd-lint 扫描现有代码，生成基础规范基线
2. 下周：在Harness CI中集成 规范静态检查，让失败PR无法合并
3. 双周：上线 金丝雀+SDD验证，生产流量先放5%
4. 一个月后：开启 AI自愈，让Harness自动修复违规代码

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