从 Vibe Coding 到 Harness × SDD：AI全栈开发的工程化进化之路

// 数据契约：用户模块
import { t } from 'elysia';

// 请求规范
export const CreateUserSchema = t.Object({
  email: t.String({ format: 'email' }),
  password: t.String({ minLength: 8, maxLength: 64 }),
  name: t.String({ minLength: 1, maxLength: 50 }),
  role: t.Enum(['admin', 'user', 'guest'])
});

// 响应规范
export const UserResponseSchema = t.Object({
  id: t.String({ format: 'uuid' }),
  email: t.String(),
  name: t.String(),
  role: t.String(),
  createdAt: t.Date(),
  // 敏感字段不返回
});

// 错误规范（统一错误码）
export const ErrorSchema = t.Union([
  t.Object({ code: t.Literal('VALIDATION_ERROR'), message: t.String() }),
  t.Object({ code: t.Literal('DUPLICATE_EMAIL'), message: t.String() }),
  t.Object({ code: t.Literal('INTERNAL_ERROR'), message: t.String() })
]);

# behavior_contract.yaml
module: UserRegistration
flows:
  - name: 注册流程
    steps:
      - 验证邮箱格式和唯一性
      - 密码加密（bcrypt, cost=10）
      - 创建用户记录（状态: PENDING_VERIFICATION）
      - 发送验证邮件（异步，不阻塞响应）
      - 返回用户信息（不包含密码字段）
    
    business_rules:
      - 同一邮箱24小时内最多注册3次（防刷）
      - 密码不能与最近3次历史密码相同
      - 注册成功后自动分配默认角色'user'
    
    error_handling:
      - 邮箱已存在 → 返回 409 DUPLICATE_EMAIL
      - 邮箱格式错误 → 返回 400 VALIDATION_ERROR
      - 邮件服务失败 → 记录日志，但不影响用户注册成功（最终一致性）

quality_gates:
  performance:
    - api_p95_latency: < 200ms
    - db_query_time: < 50ms
    - memory_usage: < 512MB
  
  test:
    - unit_test_coverage: > 80%
    - integration_test_pass_rate: 100%
    - e2e_critical_paths: 全部覆盖
  
  code_style:
    - typescript_strict: true
    - no_any: true  # 禁止使用any类型
    - max_function_lines: 50
    - max_complexity: 10

// 规范驱动的AI Prompt模板
const sddPrompt = `
你是一个严格遵守规范的全栈工程师。

【数据契约】
${JSON.stringify(dataContract, null, 2)}

【行为契约】
${behaviorContract}

【质量契约】
${qualityContract}

【任务】
根据以上规范，实现 ${taskDescription}

要求：
1. 所有输入输出必须严格遵循数据契约的类型定义
2. 业务逻辑必须覆盖行为契约中的所有步骤和业务规则
3. 代码必须通过质量契约中的检查项
4. 生成的代码需要包含对应的单元测试

请开始实现。
`;

[开发提交PR]
    │
    ▼
┌──────────────────────────────────────────────────────┐
│ Stage 1: 规范静态检查 (SDD Static Validation)        │
│ - 校验 specs/ 目录下的所有YAML/TS文件格式            │
│ - 运行 spec-validator 检查契约完整性                 │
│ - 检查是否有破坏性变更（API breaking change检测）    │
└────────────────┬─────────────────────────────────────┘
                 │ 通过
                 ▼
┌──────────────────────────────────────────────────────┐
│ Stage 2: 单元测试 + 覆盖率门禁                      │
│ - 运行所有单元测试（含AI生成的测试）                 │
│ - 覆盖率 < 80% → 流水线失败                         │
│ - 运行类型检查 (tsc --noEmit)                       │
└────────────────┬─────────────────────────────────────┘
                 │ 通过
                 ▼
┌──────────────────────────────────────────────────────┐
│ Stage 3: 构建镜像                                   │
│ - 前端: npm run build (Next.js)                     │
│ - 后端: bun build (Elysia)                          │
│ - 多阶段构建优化镜像大小                            │
└────────────────┬─────────────────────────────────────┘
                 │
                 ▼
┌──────────────────────────────────────────────────────┐
│ Stage 4: 部署到开发环境 (自动)                       │
│ - 部署策略: 滚动更新                                │
│ - 部署后自动运行烟雾测试（smoke test）              │
│ - 烟雾测试失败 → 自动回滚                          │
└────────────────┬─────────────────────────────────────┘
                 │ 通过
                 ▼
┌──────────────────────────────────────────────────────┐
│ Stage 5: 部署到预发环境 (需人工审批)                │
│ - 部署策略: 金丝雀发布 (10% 流量)                   │
│ - 运行30分钟金丝雀验证                              │
│ - 对比业务指标（错误率、延迟、吞吐）                │
│ - 指标异常 → 自动回滚                              │
└────────────────┬─────────────────────────────────────┘
                 │ 通过
                 ▼
┌──────────────────────────────────────────────────────┐
│ Stage 6: 部署到生产环境 (需二次审批)                │
│ - 部署策略: 蓝绿部署                               │
│ - 全量运行契约测试套件                             │
│ - 自动更新API文档 (OpenAPI生成)                    │
└──────────────────────────────────────────────────────┘

# harness/verification_gates.yaml
- name: contract_validation
  type: HTTP_TEST
  spec:
    requests:
      - method: POST
        url: /api/users
        body: '{"email":"test@example.com","password":"Test1234","name":"Test"}'
        expected:
          status: 201
          schema: $ref: specs/user_schema.json#/UserResponse
      - method: GET
        url: /api/users/test@example.com
        expected:
          status: 200
          schema: $ref: specs/user_schema.json#/UserResponse
          # 验证敏感字段不存在
          absent_fields: ["password", "passwordHash"]
    failure_condition: "任何请求失败或schema不匹配"

- name: performance_baseline
  type: LOAD_TEST
  spec:
    duration: 5m
    requests_per_second: 100
    recording_source: "harness_recordings/production_traffic_2026_06.har"
    thresholds:
      p95_latency: 200ms  # 超过200ms则失败
      error_rate: 0.1%    # 超过0.1%则失败

- name: ai_quality_gate
  type: CUSTOM_SCRIPT
  spec:
    script: |
      # 运行AI自检套件
      bun run agent:self-check --threshold=0.85
      # 检查是否有已知的安全漏洞（通过Trivy扫描）
      trivy image myapp:latest --severity HIGH,CRITICAL
    failure_condition: "ai_quality_score < 0.85 或 存在高危漏洞"

// 在代码中使用Feature Flag
import { getFlag } from '@harness/feature-flags';

const generateResponse = async (userInput: string) => {
  const useNewPrompt = await getFlag('use_enhanced_prompt', {
    target: { identifier: user.id }
  });
  
  const temperature = await getFlag('model_temperature', {
    defaultValue: 0.7,
    target: { identifier: user.id }
  });
  
  const prompt = useNewPrompt ? ENHANCED_PROMPT : BASE_PROMPT;
  return await llm.generate(prompt, { temperature });
};