使用 OpenCode 实践 SDD（Specification-Driven Development）：从规范到代码的完整指南

💡 前置说明：本文中的 OpenCode 指代支持 AI 辅助开发的开源编码工具/插件（如 CLI 版、IDE 插件或本地 LLM 代理），SDD 指 Specification-Driven Development（规范驱动开发）。若你指的是特定仓库（如 GitHub 某 opencode 项目）或其他含义（如 State-Driven Development / Software Design Document），请补充说明，我将精准调整。

一、什么是 SDD？为什么结合 OpenCode？

SDD（规范驱动开发） 是一种“先定义机器可读的规范，再驱动代码生成、测试与迭代”的现代开发范式。它与传统“边写边调”模式的区别：

传统开发	SDD + AI 编码
需求 → 脑补实现 → 写代码 → 调 Bug	需求 → 写规范（YAML/JSON/Schema） → AI 生成代码 → 自动验证 → 闭环迭代
规范与代码易脱节	规范是“唯一真相源”，代码可随时从规范重建
重构风险高	改规范 → 重新生成 → 自动对齐

OpenCode 的优势：作为本地/开源 AI 编码代理，它能直接读取规范文件、理解结构约束、生成符合规范的代码，并支持“生成 → 测试 → 反馈 → 修正”的自动化闭环。

二、SDD 核心工作流（4 步闭环）

graph LR
A[编写规范文件] --> B[OpenCode 读取并生成代码]
B --> C[基于规范生成测试用例]
C --> D{测试通过?}
D -->|否| E[OpenCode 自动修复/调整]
D -->|是| F[提交规范+代码到 Git]
E --> B

三、实操 Demo：用户注册验证器

1. 编写 SDD 规范文件 `user_spec.yaml`

# user_spec.yaml
name: user-validator
version: "1.0"
description: "验证用户注册信息的合法性"

fields:
  username:
    type: string
    min_length: 3
    max_length: 20
    pattern: "^[a-zA-Z0-9_]+$"
    required: true

  email:
    type: string
    format: email
    required: true

  age:
    type: integer
    minimum: 18
    maximum: 120
    required: true

  is_vip:
    type: boolean
    default: false
    required: false

error_messages:
  username.pattern: "用户名仅支持字母、数字和下划线"
  age.minimum: "年龄必须 ≥ 18 岁"
  email.format: "邮箱格式不正确"

2. 使用 OpenCode 生成代码

在 OpenCode 会话中输入以下 Prompt（支持直接拖入 user_spec.yaml）：

请根据 user_spec.yaml 生成一个 Python 验证模块：
1. 使用 pydantic v2 实现数据模型
2. 包含自定义错误提示（优先使用 error_messages 中的定义）
3. 导出 validate_user(data: dict) -> dict | ValidationError
4. 附加 3 个边界测试用例（含正常、缺失字段、格式错误）
输出完整可运行的代码，不要解释过程。

3. OpenCode 输出示例（可直接运行）

# validator.py
from pydantic import BaseModel, Field, EmailStr, field_validator
from typing import Dict, Any, Optional
import re

class UserSpec(BaseModel):
    username: str = Field(..., min_length=3, max_length=20)
    email: EmailStr
    age: int = Field(..., ge=18, le=120)
    is_vip: bool = False

    @field_validator('username')
    @classmethod
    def check_username(cls, v: str) -> str:
        if not re.match(r'^[a-zA-Z0-9_]+$', v):
            raise ValueError('用户名仅支持字母、数字和下划线')
        return v

def validate_user(data: Dict[str, Any]) -> Dict[str, Any]:
    try:
        user = UserSpec(**data)
        return user.model_dump()
    except Exception as e:
        return {"error": str(e)}

# ========== 测试用例 ==========
if __name__ == "__main__":
    cases = [
        {"username": "alice_01", "email": "alice@test.com", "age": 25, "is_vip": True},
        {"username": "ab", "email": "bob@test.com", "age": 20},
        {"username": "carl", "email": "invalid-email", "age": 16}
    ]
    for i, c in enumerate(cases, 1):
        res = validate_user(c)
        print(f"用例 {i}: {res}")

4. 运行验证

1 2	pip install pydantic[email] python validator.py

输出：

1
2
3

用例 1: {'username': 'alice_01', 'email': 'alice@test.com', 'age': 25, 'is_vip': True}
用例 2: {'error': '1 validation error for UserSpec\nusername\n  String should have at least 3 characters [type=string_too_short, input_value='ab', input_type=str]\n    For further information visit https://errors.pydantic.dev/2.9/v/string_too_short'}
用例 3: {'error': '2 validation errors for UserSpec\nemail\n  value is not a valid email address: An email address must have an @-sign. [type=value_error, input_value='invalid-email', input_type=str]\nage\n  Input should be greater than or equal to 18 [type=greater_than_equal, input_value=16, input_type=int]'}

✅ SDD 价值体现：规范变更时（如 age.minimum: 21），只需改 YAML，重新运行 OpenCode 生成，代码自动对齐，无需手动找逻辑。

四、如何用 OpenCode 高效实践 SDD？

阶段	OpenCode 操作技巧
规范编写	使用 `@file user_spec.yaml` 引用规范，AI 会解析结构
代码生成	Prompt 模板：`根据 @file spec.yaml 生成 {语言} 代码，要求：1. 严格遵循字段约束 2. 包含类型提示 3. 输出可运行测试`
测试对齐	让 OpenCode 生成基于规范的断言：`为 spec.yaml 生成 pytest 用例，覆盖所有 error_messages`
迭代修复	测试失败后：`运行 pytest 失败，根据 @file spec.yaml 修正 validator.py，不要修改规范`
版本同步	规范与代码放在同一 Commit，使用 `git log --oneline -- spec.yaml` 追踪变更

五、学习与进阶路径

阶段	学习内容	推荐实践
🟢 入门	YAML/JSON Schema 基础、Pydantic/TypeScript Zod	用 SDD 写一个配置文件验证器
🟡 进阶	OpenAPI 规范转代码、AI Prompt 工程、测试覆盖率对齐	用 SDD 生成 REST API + 客户端 SDK
🔴 高阶	规范版本化、CI/CD 自动重建、多语言规范复用	搭建 `spec → code → test → deploy` 流水线