Fork me on GitHub

Spec-Driven Development（SDD）

概览 — 什么是 Spec（或 Spec-Driven）编程？

简单说，Spec-Driven Programming / Spec-Driven Development（SDD） 是把“规格（spec）”从传统的需求文档升级为可执行、机器可理解的首要输入，由 AI/代码生成器直接把规格转换成实现、测试与监控管道。与以代码为中心不同，规格成为“事实来源”（source of truth）：写 Spec → 用 AI/工具实现 → 自动验证（测试 / 合规）→ 监控并迭代。这个思路在 2024–2025 年迅速走热，并被多家厂商、开源工具链与企业实践采纳与讨论。(GitHub)

核心内涵与概念（要点）

  1. 规格作为一等公民：规格不仅是文字说明，而是带有约束、示例、输入/输出范式和校验规则的结构化文档（JSON/YAML/IDL/行为测试）。AI 可据此生成代码与自动化测试。(GitHub)
  2. 可执行/可验证：规格通常包含验证步骤（示例用例、契约测试、契约 mock），使生成的实现能被自动化验证。(Medium)
  3. Agent + Tooling：SDD 常与“agentic IDE”或多 agent 协作结合（把大任务拆成多个子任务、管理依赖并保持规格一致性）。AWS、GitHub 等生态在推动类似工具。(TechRadar)
  4. 生命周期（Spec Lifecycle）：写 → 审阅 → 实现（自动生成）→ 验证→ 监控→ 细化（living spec）。规格是“活的”，随实现与运行数据迭代。(Medium)
  5. 治理与可追溯性：把设计意图、合规规则、性能预算都写进规格可以减少“vibe coding”式的随性输出带来的质量/安全隐患。(Red Hat Developer)

一个最小示例（概念性）

下面给出一个YAML 规格示例（描述一个简单的 REST API 接口），以及基于该规格的示意性 Python/Flask 实现片段（说明 SDD 的“写 Spec → 生成实现”流程）。

spec.yaml

service: TodoService
version: 1.0
endpoints:
  - name: CreateTodo
    path: /todos
    method: POST
    request:
      content-type: application/json
      schema:
        type: object
        required: ["title"]
        properties:
          title:
            type: string
            minLength: 1
          description:
            type: string
    responses:
      201:
        description: created
        schema:
          type: object
          properties:
            id: { type: string }
            title: { type: string }
            description: { type: string }
    examples:
      - input: { "title": "Buy milk" }
        output: { "id": "uuid-123", "title": "Buy milk", "description": "" }
tests:
  - name: create-todo-happy-path
    run:
      request: { method: POST, path: /todos, body: { "title": "x" } }
    expect:
      status: 201
      body: has_field: id

示意生成（由 AI 根据上面 spec 生成的 Flask 代码片段）

from flask import Flask, request, jsonify
import uuid

app = Flask(__name__)
store = {}

@app.route("/todos", methods=["POST"])
def create_todo():
    data = request.get_json() or {}
    title = data.get("title")
    if not title or not isinstance(title, str):
        return jsonify({"error":"title required"}), 400
    todo_id = str(uuid.uuid4())
    todo = {"id": todo_id, "title": title, "description": data.get("description","")}
    store[todo_id] = todo
    return jsonify(todo), 201

上面的过程演示了 Spec → 生成实现 → 可运行服务。实际 SDD 会同时生成/运行契约测试并把测试结果回写到规格管理平台。许多近期文章与工具链正围绕这种工作流构建。(GitHub)

代表性工具与生态（当前热点）

  • GitHub Spec Kit / Specify CLI（开源工具集合，帮助把规格模板化并驱动生成/验证流程）。(GitHub)
  • OpenAI Model Spec / 模型规格：大厂开始把模型行为也用“spec”来表达（模型期望行为、边界条件、API contract），这与 SDD 在理念上高度相关。(model-spec.openai.com)
  • AWS Kiro（agentic AI IDE）：针对“vibe coding 混乱”场景推出的 agentic IDE，强调把随机 prompt 变成可拆解、可验证的子任务与蓝图，从而支撑更成熟的 SDD 流程。(TechRadar)
  • 企业白皮书 / 实践指南：Red Hat、Google Cloud、IBM 等发布了如何在企业中以 Spec/agent 驱动 AI-assisted development 的实践文章。(Red Hat Developer)

Spec-driven vs Vibe coding — 区别与联系（直观对比）

简单一句话：Spec-driven = 以“结构化规格 + 验证”为中心的工程化流程；Vibe coding = 以“即时 prompt → 生成 → 迭代”为中心的快速原型/交互风格。 下面是更系统的对比：

维度 Spec-Driven（SDD） Vibe Coding
输入形式 结构化规格（YAML/JSON/IDL + 测试用例） 自然语言 prompt / 会话
主要目标 可靠性、可维护性、合规与可追溯 快速原型、低门槛创造力、交互式探索
生成与验证 自动生成 + 自动化契约/单元/集成测试 生成为主，人工／运行时观察为验证
典型用户 专业开发团队、需要治理的企业场景 产品设计师、个人开发者、快速原型团队
风险 需投资规格编写与维护成本 可能产生不可维护、质量不稳的代码
工具形态 Spec 管理平台、契约测试、agent orchestration Chatbot IDE、conversational agents、prompt library

两个范式也可以互补：你可以在“vibe”式对话里快速产生初版规格（用 LLM 把自然语言转成结构化 spec），再把得到的 spec 投入 SDD 流程以得到可验证的生产实现。许多最近的实践与工具就是在做这种“从 prompt 到 spec，再到实现”的链路优化。(Medium)

为什么现在会流行（技术与产业驱动）

  1. LLM / agent 能把高层意图转成可操作单元（接口、测试、实现），使得把“规格”作为中间件成为可行方案。(model-spec.openai.com)
  2. 企业对合规、安全、审计的需求使得“纯粹的 prompt→代码”变得不够可靠，推动了以 Spec 为中心的治理实践（减少技术债与知识流失）。(Red Hat Developer)
  3. 大厂与开源提供了 Spec 工具、agent IDE（如 AWS Kiro）和模板（GitHub Spec Kit），降低了上手门槛并推动标准化。(TechRadar)

实践建议（给工程/产品/团队的落地路线）

  1. 小步试点：在边缘服务或内部工具上先把接口规格化（YAML/JSON），并自动化生成契约测试。
  2. 把“验收标准”写进 spec：不仅写功能，还写性能、错误、边界与安全契约。
  3. 结合 agent：用 agent 把复杂任务分解（自动生成实现 + 生成测试 + CI 集成），但保留人工审查关键点。AWS Kiro、Spec-Kit 等可作为实验平台。(TechRadar)
  4. 监控与回写：让运行时数据（错误率、延迟、用户反馈）回写到规格，做“规格→实现→运行→规格”的闭环。(Medium)

推荐阅读与工具（起点）

  • GitHub Spec Kit（开源） — 入门模板与 CLI。(GitHub)
  • OpenAI Model Spec — 看大厂如何用“spec”规范模型行为。(model-spec.openai.com)
  • Red Hat: How spec-driven development improves AI coding quality — 企业实践视角。(Red Hat Developer)
  • AWS Kiro 报道 / 技术文章 — agentic IDE 如何尝试解决 vibe coding 带来的混乱。(TechRadar)
  • 关于 vibe coding 的背景解读（IBM / Google Cloud /媒体专栏） — 理解为何会出现以及适用场景。(Google Cloud)

（可选后续）

  • 把 一个真实需求（一段自然语言需求）转换成 结构化 spec（YAML/JSON），并给出可运行的生成代码模板。
  • 根据现有团队 / CI/CD 流程，设计一个 Spec→生成→测试→监控 的工程流水线草图（包括所需工具、质量门和审计点）。
  • 基于某个指定的 LLM（比如 GPT-5、Claude）演示一轮从自然语言到 spec，再到生成代码的完整示例（含 prompt 与生成策略）。

这里将完整演示一轮基于 GPT-5 的「自然语言 → 规格（Spec）→ 自动生成代码」的流程。
整个演示分为五个部分：

一、示例任务（自然语言输入）

假设用户输入的自然语言需求如下：

“我想做一个网页接口，可以让用户提交他们的邮箱地址进行订阅。提交后返回成功消息并记录到数据库。需要防止重复提交相同邮箱。”

二、GPT-5 的 Prompt 设计（即生成策略）

我们使用 Spec-Driven Prompt 模式。
GPT-5 不是直接生成代码，而是先生成一个 机器可执行的规范文档（Spec），然后再从 Spec 生成实现。

Prompt 模板示例如下（你可以在 LangChain、OpenAI API 或 IDE agent 中使用）：

SYSTEM:
You are a senior AI software architect practicing Spec-Driven Development (SDD).
Your job is to convert user requests into formal, executable specifications, not code yet.
Use JSON or YAML to define service name, endpoints, data schema, constraints, and validation logic.

USER:
${自然语言需求文本}

ASSISTANT:
(生成 structured spec 文档)

接下来，当 spec 确认无误后，我们使用第二个 prompt：

SYSTEM:
You are now a code generation agent. Generate production-level backend code
based strictly on the provided spec, including validation and database logic.
Use Python + FastAPI + SQLite for implementation.

USER:
${之前生成的 Spec 文档}

三、GPT-5 生成的 Spec（结构化规格）

GPT-5 根据自然语言需求生成的 spec.yaml 示例如下：

service: EmailSubscriptionService
version: 1.0
description: >
  RESTful API that allows users to submit email addresses for newsletter subscription.
  The service stores emails in a database and prevents duplicate subscriptions.

database:
  engine: sqlite
  name: subscriptions.db
  tables:
    - name: subscribers
      columns:
        - name: id
          type: integer
          primary_key: true
          autoincrement: true
        - name: email
          type: string
          unique: true
          not_null: true
        - name: created_at
          type: datetime
          default: now()

api:
  base_path: /api
  endpoints:
    - name: SubscribeEmail
      path: /subscribe
      method: POST
      request:
        content_type: application/json
        schema:
          type: object
          required: ["email"]
          properties:
            email:
              type: string
              format: email
      responses:
        201:
          description: Successfully subscribed
          schema:
            type: object
            properties:
              message: { type: string }
        400:
          description: Invalid or duplicate email
          schema:
            type: object
            properties:
              error: { type: string }
examples:
  - input: { "email": "user@example.com" }
    output: { "message": "Subscription successful" }
tests:
  - name: duplicate-email-test
    run:
      method: POST
      path: /api/subscribe
      body: { "email": "user@example.com" }
    expect:
      status: 400
      body: { "error": "Email already subscribed" }

四、GPT-5 基于 Spec 自动生成代码

此阶段使用第二个 prompt（代码生成 agent），GPT-5 自动输出符合规范的代码实现。

app.py

from fastapi import FastAPI, HTTPException, Request
from pydantic import BaseModel, EmailStr
import sqlite3
from datetime import datetime

app = FastAPI(title="EmailSubscriptionService")

DB_PATH = "subscriptions.db"

# ---------- Database Setup ----------
def init_db():
    conn = sqlite3.connect(DB_PATH)
    c = conn.cursor()
    c.execute("""
    CREATE TABLE IF NOT EXISTS subscribers (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        email TEXT UNIQUE NOT NULL,
        created_at TEXT DEFAULT CURRENT_TIMESTAMP
    )
    """)
    conn.commit()
    conn.close()

init_db()

# ---------- Request Schema ----------
class SubscribeRequest(BaseModel):
    email: EmailStr

# ---------- Endpoint ----------
@app.post("/api/subscribe")
async def subscribe(req: SubscribeRequest):
    email = req.email.strip().lower()
    conn = sqlite3.connect(DB_PATH)
    c = conn.cursor()

    # Check for duplicates
    c.execute("SELECT id FROM subscribers WHERE email = ?", (email,))
    if c.fetchone():
        conn.close()
        raise HTTPException(status_code=400, detail="Email already subscribed")

    # Insert new subscriber
    c.execute("INSERT INTO subscribers (email, created_at) VALUES (?, ?)", (email, datetime.utcnow().isoformat()))
    conn.commit()
    conn.close()

    return {"message": "Subscription successful"}

# ---------- Health Check ----------
@app.get("/api/health")
async def health():
    return {"status": "ok"}

运行：

uvicorn app:app --reload

然后测试：

curl -X POST http://127.0.0.1:8000/api/subscribe \
     -H "Content-Type: application/json" \
     -d '{"email":"user@example.com"}'

第一次返回：

{"message": "Subscription successful"}

第二次再发同样请求：

{"detail": "Email already subscribed"}

说明自动生成的代码完美匹配了 Spec 要求。

五、GPT-5 背后的策略说明（生成逻辑）

GPT-5 的 agent 链一般会使用以下结构：

自然语言理解阶段

  • 使用 gpt-5 模型识别需求中的：

    • 实体（service、data type、action）
    • 动词语义（“提交”、“存储”、“防止重复”）
    • 非功能性需求（返回格式、约束）

  • 将这些映射为 Schema 结构元素。

规格模板化阶段

  • 根据内置 Schema 模板（类似 [OpenAPI] + [SpecKit] 语法）自动填充字段。
  • 生成 “可执行规范”：包含接口、数据表、验证、测试示例。

代码生成阶段

  • 将 Spec 解析为 AST（中间表示），然后模板化生成对应语言实现。
  • 代码生成模块会自动选择框架（FastAPI、Flask、Express.js 等）。
  • 自动插入验证逻辑（类型检查 / 去重逻辑）与错误返回。

自验证阶段

  • GPT-5 的 agent 可利用 spec 中的 tests 部分执行虚拟测试（dry-run simulation），验证逻辑一致性。
  • 若发现接口未覆盖所有用例，会自动更新 Spec 并重新生成。

六、Spec 编程与 “vibe coding” 的对比复盘

维度 Spec-Driven（GPT-5 模式） Vibe Coding（传统 prompt 模式）
思维方式 从结构化规范出发 直接从 prompt 生成代码
控制 高度确定性（由 spec 限定） 结果依赖语言模型生成随机性
可维护性 高，可复现、可回放 低，难以复现同一代码
典型工具 OpenAI GPT-5 + SpecKit + CI 验证 ChatGPT IDE、Copilot
最佳用途 企业级、合规、团队开发 创意原型、个人探索

总结

阶段 输入 输出
自然语言需求 “我要一个邮箱订阅接口” —
GPT-5 (Spec Agent) YAML/JSON 结构化规格 ✅ spec.yaml
GPT-5 (Code Agent) 后端实现 + 验证逻辑 ✅ app.py
最终产物 可运行 API + 自动测试 🚀 成功部署
posted @ 2025-10-28 15:30  stardsd  阅读(15)  评论(0)    收藏  举报