从 Prompt Engineering 到 Spec Compilation：AI Coding 时代的软件语义协议

最近半年，Spec-Driven Development（SDD）正在快速成为 AI Coding 世界里的核心范式。

无论是 Claude Code、Cursor、OpenCode、TRAE，还是大量新出现的 AI Native Engineering 工具，都开始强调：

• Spec First
• Structured Intent
• Requirements Before Code
• Human + AI Shared Source of Truth

越来越多人开始意识到：

AI Coding 最大的问题，不是代码生成能力，而是「意图表达能力」。

代码生成本身已经越来越便宜。真正昂贵的，是：

• 如何表达需求
• 如何表达约束
• 如何表达边界
• 如何表达系统语义
• 如何避免 AI 漂移（AI Drift）
• 如何让 AI 在长周期开发中保持一致性

而这，也正是 Spec-Driven Development 出现的原因。

传统 Prompt Engineering 的根本问题

很多团队刚开始使用 AI Coding 时，都会经历一个阶段：

这种方式在小任务里非常高效。但一旦系统复杂度上升，很快就会出现：

• AI 忘记之前的上下文
• 架构逐渐漂移
• 文件结构失控
• API 命名不一致
• 同一模块出现多种实现方式
• 隐式约束丢失
• 边界条件被忽略
• 需求无法验证

社区里很多人把这种模式称为 Vibe Coding。它的核心问题是：

Prompt 是瞬时的，而软件系统是长期演化的。

Prompt 无法形成稳定的软件语义层。

Spec-Driven Development 的本质

越来越多的新框架开始强调：

• Specs, not prompts
• Spec as source of truth
• Living specification
• Typed contracts
• Structured intent

例如：

• OpenSpec
• OpenSDD
• SpecDD
• SpecPrompt
• Spec Native

它们都在强调同一个方向：

AI 不应该直接消费 Prompt。

AI 应该消费结构化 Spec。

这意味着：

Natural Language
   ↓
Typed Spec
   ↓
Planning
   ↓
Task Graph
   ↓
AI Execution
   ↓
Verification

Spec 不再只是文档，而是 Intermediate Representation (IR)——软件意图的中间表示层。

真正的问题：不是如何写 Spec

很多团队开始实践 SDD 后，很快会发现一个更大的问题：

同一个功能，不同人写出来的 Spec 完全不同。

例如，有的人这样写：

实现手机号登录

有的人这样写：

支持 OTP 验证登录

还有的人会写：

feature:
  auth:
    login:
      type: phone

结果是：

• AI 理解不一致
• Spec 无法 Diff
• 无法自动验证
• 无法自动 Patch
• 无法形成长期演化能力
• 无法形成组织级知识

于是会发现：

真正的问题，不是 Spec。

而是「Spec 的语义协议」。

你真正缺少的是 Spec Type System

这和 TypeScript 出现前的 JavaScript 世界非常类似。

在没有 Type System 的时代：

const user = {
  name: 'shawn',
}

所有 object shape 都靠约定。于是：

• IDE 无法推导
• Compiler 无法检查
• Tooling 无法建立
• Refactor 非常困难

直到 TypeScript 出现：

interface User {
  name: string
}

软件工程才真正进入可扩展时代。AI Coding 现在也处于类似阶段。

很多团队写的其实仍然是 Natural Language Spec，而不是 Typed Spec。这会导致：

• AI 无法稳定消费
• 无法形成工具链
• 无法建立验证器
• 无法建立长期演化能力

从「文档」升级为「Schema」

真正有效的 Spec，不应该只是 Markdown，而应该是：

kind: FeatureSpec

feature:
  id: auth.phone-login
  domain: auth
  bounded_context: identity

intent:
  goal:
    - support phone login

contracts:
  input:
    phone:
      type: e164
    code:
      type: otp
  output:
    token:
      type: jwt

constraints:
  security:
    - otp_expire <= 5m
    - rate_limit_required

verification:
  tests:
    - auth.phone-login.success
    - auth.phone-login.expired-code

这里最关键的变化是：以前 AI 在理解文本，现在 AI 在消费 DSL。这是两个完全不同的阶段。

Spec 必须分类（Spec Class）

很多团队失败的另一个原因是：所有内容都写成一种 Spec。这是错误的，因为不同类型的开发对象，其语义结构完全不同。

每一种 Spec 都有固定字段、生命周期、验证器、Prompt Adapter、Ownership 和 Dependency。这本质上已经很像 Kubernetes CRD——软件语义资源定义。

真正决定 AI 稳定性的：Constraint Density

AI Coding 最大的问题其实不是「不会写」，而是乱改。

因此很多 SDD 框架都开始强调：MUST、MUST NOT、NEVER、ONLY、IMMUTABLE、READONLY。

例如 SpecDD 就特别强调：

aggressively use “must not” constraints

因为：

AI 的问题不是缺少创造力，而是缺少边界。

所以未来高质量 Spec 的关键指标之一，很可能是 Constraint Density（约束密度）。

真正成熟的体系一定是 Layered Spec

很多团队只有一种 Spec，最后会导致：

• Spec 越来越胖
• Context 越来越长
• AI 越来越混乱
• 修改成本越来越高

成熟体系一定会形成：

Vision
  ↓
PRD
  ↓
Architecture
  ↓
Domain Spec
  ↓
Feature Spec
  ↓
Task Spec
  ↓
Verification Spec

或者按职责分为四层：

Intent Layer
Constraint Layer
Execution Layer
Verification Layer

这是因为软件意图本身就是分层的，Spec 也必须分层。

Canonicalization：真正的关键

真正决定 AI Coding 是否可工程化的，并不是 Prompt，而是 Spec Canonicalization——同类需求，是否能够形成同类语义结构。

例如所有 APISpec 必须统一拥有：

purpose:
contracts:
constraints:
errors:
security:
tests:
ownership:
rollback:

而不是每个人自由发挥。否则：

• 无法比较
• 无法合并
• 无法验证
• 无法自动推导
• 无法自动生成 Task Graph

最终仍然会退回 Prompt Engineering。

Controlled Vocabulary：消灭模糊语言

未来高质量 Spec 一定会大量使用 Controlled Vocabulary（受控语义词汇）。

不要写：

优化性能
提升体验
支持高并发

而是：

latency_p95 < 100ms
must_be_idempotent
readonly_access_only
retry <= 3

Spec 里的形容词越多，AI 漂移概率越高。

Spec Lint 会成为下一代基础设施

未来一定会出现类似 ESLint 的东西：

spec lint

用于检查：

• vague wording
• missing constraints
• missing ownership
• unverifiable acceptance
• implementation leakage
• oversized scope
• undefined contract

这会成为 AI Engineering 时代最核心的基础设施之一。

从 Prompt Engineering 走向 Spec Compilation

未来的软件工程很可能会从 Code-centric 变成 Spec-centric：

Code ← executable artifact
Spec ← source of truth

于是整个软件开发流程会变成：

Spec Layer
   ↓
Planning Layer
   ↓
Execution Layer
   ↓
Verification Layer
   ↓
Governance Layer

而 AI 不再负责「理解需求」，而是负责执行 Spec Compilation。

实践：三层编译流水线

上述理念如何落地？我们提出一套可操作的 三层编译流水线 架构：

┌─────────────────────────────────────────────────────────────┐
│  Layer 1: Product Spec (产品契约)                            │
│  人写给人看：需求背景、用户故事、业务规则、验收标准            │
│  技术无关：产品经理不需要知道 Vue 还是 React                   │
│                                                              │
│  产物: prod-spec.md                                          │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│  Layer 2: Tech Contract (技术契约)                           │
│  人写给 AI 看：Schema、接口契约、校验规则、转换逻辑            │
│  框架无关：不绑定 Vue/React，不绑定 REST/GraphQL             │
│                                                              │
│  产物: tech-contract.md                                      │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│  Layer 3: Tech Spec (技术规范)                               │
│  AI 生成给人审：文件变更、代码实现、测试用例                   │
│  框架相关：Vue 组件、ECharts 配置、API 函数                   │
│                                                              │
│  产物: tech-spec.md (由 Scaffold + Template 推导生成)        │
└─────────────────────────────────────────────────────────────┘

关键设计：为什么 Tech Contract 要独立一层？

Tech Contract 是「业务语义」与「技术实现」之间的 IR（中间表示）。

工作流程

flowchart TB
    subgraph User["👤 人"]
        U1["输入需求"]
        U2["PM 审阅 prod-spec"]
        U3["RD 审阅 tech-contract"]
        U4["RD 审阅 tech-spec"]
        U5["AI+RD 验收代码"]
    end

    subgraph Agent1["🤖 AI Agent: 需求理解"]
        A1["解析用户意图"]
        A2["生成 prod-spec.md"]
        A3["生成 tech-contract.md"]
    end

    subgraph Scaffold["📦 Scaffold + Template"]
        T1["tech-contract-template.md"]
        T2["component-pattern.md"]
        T3["derive-rules.md"]
        T4["项目现状分析"]
    end

    subgraph Agent2["🤖 AI Agent: 技术推导"]
        B1["读取 Schema"]
        B2["应用推导规则"]
        B3["生成 tech-spec.md"]
    end

    subgraph Agent3["🤖 AI Agent: 代码生成"]
        C1["读取 tech-spec"]
        C2["生成代码变更"]
        C3["生成测试用例"]
    end

    U1 --> A1
    A1 --> A2
    A2 --> U2
    U2 -->|确认| A3
    A3 --> U3
    U3 -->|确认| B1

    B1 --> T1
    T1 --> T2
    T2 --> T3
    T3 --> T4
    T4 --> B2
    B2 --> B3
    B3 --> U4
    U4 -->|确认| C1

    C1 --> C2
    C2 --> C3
    C3 --> U5

    style User fill:#e1f5fe
    style Agent1 fill:#fff3e0
    style Scaffold fill:#f3e5f5
    style Agent2 fill:#fff3e0
    style Agent3 fill:#fff3e0

阶段一：需求编译（人 → AI）

AI Agent 解析用户意图，生成 prod-spec.md 和 tech-contract.md。人审确认后进入下一阶段。

阶段二：技术推导（AI → AI）

AI 读取 tech-contract.md，结合项目对应的 tech-contract-template.md 和 derive-rules.md，自动推导生成 tech-spec.md。

阶段三：实现与验证（AI → 人）

AI 根据 tech-spec.md 生成代码变更和测试用例，人审后验收。

变更管理：Living Specification

当需求发生变更时，传统方案需要重写大量文档。我们的方案：

flowchart LR
    subgraph Change["📝 需求变更"]
        direction TB
        CH1["场景 A: 时间范围<br/>3个月 → 6个月"]
        CH2["场景 B: 新增字段<br/>yoy_rate"]
    end

    subgraph Layer1["Layer 1: Product Spec"]
        direction TB
        P1["prod-spec.md"]
        P2["BR-02: 近六个月"]
        P3["新增同比规则"]
    end

    subgraph Layer2["Layer 2: Tech Contract"]
        direction TB
        T1["tech-contract.md"]
        T2["Schema 不变"]
        T3["Schema 变更:<br/>+ yoy_rate?"]
    end

    subgraph Layer3["Layer 3: Tech Spec"]
        direction TB
        S1["tech-spec.md"]
        S2["AI 推导:<br/>标题改「6个月」"]
        S3["AI 推导:<br/>新增同比折线"]
    end

    CH1 --> P2
    CH2 --> P3

    P2 --> T2
    P3 --> T3

    T2 --> S2
    T3 --> S3

    style Change fill:#ffebee
    style Layer1 fill:#e8f5e9
    style Layer2 fill:#e3f2fd
    style Layer3 fill:#fff3e0

场景 A：时间范围从「近3个月」改为「近6个月」

# prod-spec.md
- BR-02: 展示相对近三个月平均的比例
+ BR-02: 展示相对近六个月平均的比例

# tech-contract.md —— 无需变更！
# Schema 不变，只是后端查询范围变化

# tech-spec.md —— AI 自动推导更新
# 图表标题从「近3个月」改为「近6个月」

场景 B：新增「同比去年」数据字段

# tech-contract.md
  interface FlowWaveItem {
    monday: string
    rate: number
+   yoy_rate?: number  // 同比去年，可选
  }

# tech-spec.md —— AI 自动推导
# - API 函数更新
# - 图表 option 新增第二条线
# - Tooltip formatter 更新

Scaffold Template 机制

每个技术栈对应一个 Template，包含推导规则：

scaffold/
├── vue3-vite/
│   ├── tech-contract-template.md    # Tech Contract 必须包含哪些字段
│   ├── component-pattern.md         # Vue 组件最佳实践
│   ├── api-pattern.md               # API 封装模式
│   ├── chart-pattern.md             # ECharts 配置模式
│   └── derive-rules.md              # Tech Contract → Tech Spec 的推导规则
│
├── react-next/
│   ├── tech-contract-template.md
│   ├── component-pattern.md
│   ├── api-pattern.md
│   └── derive-rules.md
│
└── go-micro/
    ├── tech-contract-template.md
    ├── handler-pattern.md
    ├── model-pattern.md
    └── derive-rules.md

核心原则

1. 人只写「变」的部分，不写「不变」的部分

tech-contract.md 只定义 Schema 和业务规则，不写 Vue 组件怎么写——那是 Template 的事。

2. AI 只推导「确定」的部分，不猜测「模糊」的部分

tech-contract.md 没定义的字段，AI 不会自己加。推导失败时回退到人审。

3. Template 只封装「最佳实践」，不限制「灵活性」

derive-rules 可以覆盖，特殊情况在 tech-spec.md 中人工标注。

与传统方案的对比

未来真正重要的不是 AI Model

而是组织内部的软件语义协议。

因为未来模型能力会越来越接近，真正决定组织 AI 开发效率的，将是：

• Spec Taxonomy
• Spec Type System
• Constraint System
• Verification System
• Semantic Canonicalization
• Organizational Ontology

这会像 API Design、Database Schema、Type System、Compiler IR 一样，成为新的软件工程基础设施。

一个非常重要的认知变化

过去的软件工程：代码是核心资产。

未来的软件工程：意图才是核心资产。

代码会越来越像 build artifact，而 Spec 会成为真正的软件源代码。

References

• OpenSpec
• OpenSDD
• SpecDD
• SpecPrompt
• Spec Native
• SpecToCode
• Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants — Deepak Babu Piskala, 2026
• Constitutional Spec-Driven Development: Enforcing Security by Construction in AI-Assisted Code Generation — Srinivas Rao Marri, 2026