📒 学霸笔记：02｜核心引擎——AI 原生开发第一性原理：规范驱动开发

Top Student Notes: 02 | Core Engine — The First Principle of AI-Native Development: Spec-Driven Development

课程 / Course: AI 原生开发工作流实战 / AI-Native Development Workflow in Practice
讲师 / Instructor: Tony Bai
模块 / Module: 概念篇 / Concepts
主题 / Topic: 规范驱动开发（SDD, Spec-Driven Development）
核心关键词 / Keywords: spec.md / plan.md / tasks.md / Single Source of Truth / 编译意图 / Spec → Generate → Validate

🎯 一、这一讲到底在回答什么问题？

What Question Does This Lecture Answer?

中文

上一讲我们讲清楚了一个核心结论：

在 AI 原生开发时代，工程师的核心价值正从“编码实现”上移到“规范设计”和“工作流编排”。

那么自然会产生一个追问：

为什么“规范设计”是第一位的？
为什么不是“Prompt 更会写”或者“工具更会用”？

这一讲的答案是：

因为在 AI 原生开发里，规范（Specification）是整个工作流的起点、约束和真理之源。

English

The previous lecture established a key conclusion:

In the AI-native era, the core value of engineers is shifting upward from coding implementation to specification design and workflow orchestration.

That raises the next question:

Why is specification design the first priority?
Why not simply “writing better prompts” or “using tools better”?

This lecture answers:

Because in AI-native development, the specification is the starting point, constraint system, and source of truth for the entire workflow.

🧠 二、传统软件开发的根本问题：失落的翻译

The Fundamental Problem of Traditional Development: Lost in Translation

1. 传统流程 / Traditional Flow

业务构想 / Business Idea
    ↓
PRD（产品文档 / Product Requirement Document）
    ↓
技术设计文档 / Technical Design
    ↓
代码实现 / Code Implementation

中文

传统软件开发不是直接从“意图”到“实现”，而是经过多轮“人脑翻译”：

1. 产品经理把业务想法翻译成 PRD
2. 架构师/开发者把 PRD 翻译成技术方案
3. 开发者再把技术方案翻译成代码

每一次翻译都会带来：

• 信息损耗 / information loss
• 语义歧义 / semantic ambiguity
• 主观臆断 / subjective interpretation
• 文档与代码脱节 / docs drifting away from code

English

Traditional software development does not go directly from intent to implementation. It goes through multiple rounds of human translation:

1. PM translates a business idea into a PRD
2. Architects/developers translate the PRD into a technical design
3. Developers translate the design into code

Each translation introduces:

• information loss
• semantic ambiguity
• subjective assumptions
• documentation-code drift

2. “失落的翻译”例子 / Example of Lost Translation

原始需求 / Original Requirement

“界面需要响应迅速。”
“The interface should feel responsive.”

被翻译后的不同理解 / Possible Translations

• 有人理解成 API 响应时间 < 500ms
• Someone interprets it as API response time < 500ms
• 有人理解成前端需要骨架屏
• Someone interprets it as frontend needs skeleton loading
• 有人压根忽略了
• Someone ignores it entirely

学霸理解 / Top-Student Insight

问题不只是“写错代码”，而是：

在代码写出来之前，意图已经丢失了一部分。

The real problem is not merely “wrong code,” but:

part of the original intent has already been lost before the code is even written.

🔄 三、SDD 的第一性原理：权力的反转

The First Principle of SDD: Reversal of Authority

这是本讲最重要的一句话。
This is the most important sentence of the lecture.

1. 传统范式 / Traditional Paradigm

文档服务于代码
Documentation serves code
代码才是真理
Code is the truth

中文

传统模式默认：

• 文档只是辅助材料
• 代码才是最终的真实系统

一旦项目进入迭代，文档很容易过时，最终：

Code becomes the only truth, but a truth that is hard to understand.

2. SDD 范式 / SDD Paradigm

代码服务于规范
Code serves the spec
规范才是真理之源
The spec becomes the Single Source of Truth

中文

在规范驱动开发（SDD）中：

• 规范（specification）成为唯一真理之源
• 代码只是规范在某个技术栈中的“渲染结果”或“编译产物”

English

In Spec-Driven Development (SDD):

• the specification becomes the Single Source of Truth
• code becomes a rendered or compiled result of the spec in a specific tech stack

3. 权力反转后的三个变化 / Three Consequences of the Reversal

① 维护软件的核心改变了

• 传统：修改代码
• SDD：演进规范

Traditional: modify code
SDD: evolve the spec

② 调试 Bug 的核心改变了

• 传统：修复错误代码
• SDD：修正导致错误生成的规范或方案

Traditional: fix wrong code
SDD: fix the faulty spec or plan that produced the wrong code

③ 技术重构的核心改变了

• 传统：迁移大规模代码
• SDD：基于同一规范重新生成不同技术栈实现

Traditional: migrate large amounts of code
SDD: regenerate implementation from the same spec in a different stack

🏗️ 四、AI 在 SDD 中的新角色：编译意图

AI’s New Role in SDD: Compiling Intent

核心隐喻 / Core Metaphor

中文

在 SDD 中，AI 不只是“写代码工具”，而是一个多阶段编译器。
它所编译的，不再只是编程语言，而是：

人类意图（Intent）

English

In SDD, AI is not just a “code-writing tool,” but a multi-stage compiler.
What it compiles is not merely programming language, but:

human intent

多阶段编译链 / Multi-Stage Compilation Chain

模糊的人类想法
Vague Human Intent
        ↓
[需求编译器 / Requirement Compiler]
        ↓
spec.md
        ↓
[方案编译器 / Planning Compiler]
        ↓
plan.md
        ↓
[任务编译器 / Task Compiler]
        ↓
tasks.md
        ↓
[代码生成器 / Code Generator]
        ↓
可运行的软件 / Running Software

AI 在各阶段扮演的角色 / Roles of AI in Each Stage

学霸理解 / Top-Student Insight

传统意义上的编译器是：

源代码 → 机器码

而在 AI 原生开发里，编译器链变成了：

意图 → 规范 → 方案 → 任务 → 代码

Traditional compilers transform:

source code → machine code

In AI-native development, the compiler chain becomes:

intent → spec → plan → tasks → code

📦 五、SDD 的三大核心产物

The Three Core Artifacts of SDD

1. spec.md：定义 WHAT 和 WHY

spec.md: Defines WHAT and WHY

中文

spec.md 是需求规范，核心职责是：

• 定义做什么 / what to build
• 定义为什么做 / why it matters
• 定义成功标准 / success criteria
• 不涉及技术实现 / no implementation details

典型内容 / Typical Contents

• 用户故事 / user stories
• 功能需求 / functional requirements
• 验收标准 / acceptance criteria
• 边界条件 / edge cases

关键原则 / Key Principle

只讲业务意图，不讲技术实现。
Business intent only, no technical implementation.

2. plan.md：定义 HOW

plan.md: Defines HOW

中文

plan.md 是技术方案，核心职责是：

• 在 spec.md 约束下决定如何实现
• 结合技术栈、项目架构、工程规范
• 明确模块划分、数据模型、接口契约、部署方式等

典型内容 / Typical Contents

• 技术选型 / tech stack
• 架构设计 / architecture
• 模块边界 / module boundaries
• API 定义 / API contracts
• 数据模型 / data models

关键原则 / Key Principle

plan 是 spec 在技术世界中的映射。
The plan is the technical projection of the spec.

3. tasks.md：定义 ACTIONS

tasks.md: Defines ACTIONS

中文

tasks.md 是任务清单，核心职责是：

• 把 plan.md 拆成原子任务
• 明确任务间依赖关系
• 标记哪些任务可以并行执行
• 让 AI 可以直接按步骤执行

典型内容 / Typical Contents

• 任务编号 / task IDs
• 原子任务描述 / atomic task descriptions
• 依赖关系 / dependencies
• 并行标记（如 [P]）/ parallel markers

关键原则 / Key Principle

tasks 是给 AI 执行的“字节码”。
Tasks are the “bytecode” for AI execution.

🔁 六、SDD 的四阶段通用工作流

The Four-Stage Generic Workflow of SDD

阶段 1：意图定义 / Stage 1: Intent Definition

目标 / Goal

澄清 做什么（WHAT） 和 为什么做（WHY）

输入 / Input

• 模糊自然语言需求 / vague natural-language idea

核心活动 / Core Activities

• 人机协作头脑风暴 / human-AI brainstorming
• 澄清模糊点 / clarify ambiguity
• 挖掘边缘场景 / surface edge cases
• 设计验收标准 / define acceptance criteria

输出 / Output

• spec.md

阶段 2：技术规划 / Stage 2: Technical Planning

目标 / Goal

确定 如何做（HOW）

输入 / Input

• spec.md
• 技术栈约束 / tech constraints
• 团队宪法 / project constitution

核心活动 / Core Activities

• 技术选型 / choose tech stack
• 模块划分 / split modules
• API 设计 / define APIs
• 数据模型设计 / design data models

输出 / Output

• plan.md
• 附属设计文档（如 api-spec.json、data-model.md）

阶段 3：任务分解 / Stage 3: Task Decomposition

目标 / Goal

将 HOW 变成可执行 ACTIONS

输入 / Input

• plan.md
• 所有设计文档 / supporting design docs

核心活动 / Core Activities

• 拆分原子任务 / split into atomic tasks
• 识别依赖 / identify dependencies
• 标记并行点 / mark parallelizable tasks

输出 / Output

• tasks.md

阶段 4：自动化实现 / Stage 4: Automated Implementation

目标 / Goal

根据任务列表完成实现

输入 / Input

• tasks.md

核心活动 / Core Activities

• 逐项执行 / execute task by task
• 创建文件 / create files
• 生成代码 / generate code
• 运行测试 / run tests
• 修复问题 / iterate on failures

输出 / Output

• 源代码 / source code
• 测试 / tests
• 文档 / docs
• 可运行产物 / working software

四阶段总图 / Four-Stage Summary Diagram

[模糊想法 / Vague Idea]
          ↓
1. 意图定义 / Intent Definition
          ↓
      spec.md
          ↓
2. 技术规划 / Technical Planning
          ↓
      plan.md
          ↓
3. 任务分解 / Task Decomposition
          ↓
     tasks.md
          ↓
4. 自动化实现 / Automated Implementation
          ↓
   Running Software

🛠️ 七、真实世界实现：GitHub spec-kit

Real-World Implementation: GitHub spec-kit

spec-kit 是 SDD 思想的一个很典型的工程化实现。
spec-kit is a representative engineering implementation of SDD.

用 Slash Commands 固化工作流

Workflow Solidified with Slash Commands

一句话理解 / One-Line Understanding

spec-kit 本质上是在把：

SDD 的理念 → 标准化、可执行、可重复的工程流程

spec-kit turns:

the philosophy of SDD → into a standardized, executable, repeatable engineering workflow

🔄 八、开发循环的根本变化

Fundamental Change in the Development Loop

传统循环 / Traditional Loop

Code → Test → Refactor

中文

这个循环以代码为中心，适合局部优化和持续重构。
但当需求大变时，往往需要跳出循环，回到上游重新设计。

English

This loop is code-centered and works well for local optimization and continuous refactoring.
But when requirements change significantly, you often have to step out of the loop and go back upstream.

AI 原生循环 / AI-Native Loop

Spec → Generate → Validate

中文

这个循环提升到了“意图层”：

1. 修改规范 / evolve the spec
2. 重新生成实现 / regenerate implementation
3. 审查并验证输出 / validate the output

English

This loop operates at the intent level:

1. evolve the spec
2. regenerate implementation
3. validate the output

对比总结 / Comparison

🚀 九、为什么 SDD 是 AI 原生开发的未来？

Why SDD Is the Future of AI-Native Development

1. 它解决 AI 的“模糊性”问题

It Solves AI’s Ambiguity Problem

中文

大模型擅长理解语言，但天然带有概率性。
如果输入模糊，输出就会不稳定。

SDD 的作用就是：

把模糊自然语言，转化为结构化、机器可执行的规范。

English

LLMs are powerful at language understanding, but they are inherently probabilistic.
If the input is vague, the output becomes unstable.

SDD addresses this by:

transforming vague natural language into structured, machine-executable specifications.

2. 它大幅加速迭代

It Greatly Accelerates Iteration

中文

传统开发里，需求变更 = 大量手工改代码。
SDD 里，需求变更 = 改 spec.md，然后重新生成。

English

In traditional development, requirement changes mean manually rewriting lots of code.
In SDD, requirement changes mean updating spec.md and regenerating the implementation.

3. 它释放并行潜力

It Unlocks Parallelism

中文

tasks.md 里的依赖与并行标记，让多个 AI Agent 可以协作实现不同模块。
这正是 AI 原生“规模化开发”的基础。

English

Dependency and parallel markers in tasks.md enable multiple AI agents to work on different modules simultaneously.
This is the basis of scalable AI-native development.

4. 它创造“活文档”

It Creates Living Documentation

中文

文档不再是“写完就腐烂”的说明书，
而是：

能持续驱动实现生成的活文档。

English

Documentation is no longer a manual that rots after being written.
It becomes:

living documentation that continuously drives implementation generation.

5. 它把工程师从低价值重复劳动中解放出来

It Frees Engineers from Low-Value Repetitive Work

中文

SDD 把工程师从机械重复的翻译劳动中解放出来，让人类回到更高价值的位置：

• 业务建模 / business modeling
• 边界定义 / boundary definition
• 架构设计 / architectural thinking
• 质量治理 / quality governance

English

SDD frees engineers from repetitive translation work and moves them toward higher-value roles:

• business modeling
• boundary definition
• architecture
• quality governance

⚠️ 十、我们也要理性：SDD 今天的挑战

Be Realistic: SDD’s Challenges Today

Tony 并没有把 SDD 讲成一个“今天已经完美落地”的银弹，这点很重要。
Tony does not present SDD as a perfect silver bullet already fully mature today — and that is important.

当前挑战 / Current Challenges

1. 大模型长链路稳定性有限

• 复杂多阶段推理会累积误差
• Complex long chains of reasoning accumulate errors

2. Agent 工具鲁棒性还不够强

• 执行环境感知不总是稳定
• Environment awareness is not always robust

3. 100% 自动化仍有门槛

• 尤其是开放世界、模糊需求、异常恢复场景
• Especially in open-ended, ambiguous, failure-prone scenarios

但为什么现在反而是学习它的最好时机？

Then Why Is Now the Best Time to Learn It?

因为 SDD 定义的是：

未来 AI 原生软件工程的人机协作接口

Because SDD defines:

the future human-AI collaboration interface for software engineering

今天学的每一项能力——

• 写清晰规范
• 设计 AI 可执行流程
• 构建验证闭环

都是在为未来 L4 自主开发铺路。
Every skill learned today is a foundation for future L4 autonomous engineering.

🧭 十一、本讲与上一讲、下一讲的关系

How This Lecture Connects to Previous and Next Ones

与上一讲的关系 / Connection to Lecture 01

上一讲讲的是：

为什么开发者价值正在从“编码实现”迁移到“规范设计 + 工作流编排”

这一讲则回答：

规范设计具体是什么，以及它为什么成为 AI 原生开发的第一性原理

与下一讲的关系 / Connection to the Next Lecture

下一讲会继续扩展视野：

除了 Claude Code，还有哪些命令行 AI Agent 工具值得关注？
Why is Claude Code chosen as the main vehicle of the course?

也就是说：

• 这一讲解决“方法论”
• 下一讲解决“工具载体”

This lecture solves the methodology.
The next lecture addresses the tooling vehicle.

📊 十二、本讲核心总表

Master Summary Table

✅ 十三、学霸自检题 / Self-Check Questions

基础题 / Basic

1. 什么是“失落的翻译”问题？
2. SDD 中“权力反转”指的是什么？
3. spec.md、plan.md、tasks.md 各自解决什么问题？

进阶题 / Advanced

4. 为什么说 AI 在 SDD 中扮演的是“多阶段编译器”？
5. 为什么 spec.md 必须与技术实现解耦？
6. tasks.md 为什么可以看作 AI 的“字节码”？

思辨题 / Reflective

7. 你最近开发的一个功能，如果用 SDD 拆解，它的 spec.md 会写什么？
8. 你目前团队里的哪些文档已经“腐烂”？如果让它们重新成为“活文档”，需要什么条件？
9. 你更习惯 Code → Test → Refactor，还是能接受 Spec → Generate → Validate？阻力在哪里？

🧾 十四、学霸总结 / Top-Student Summary

中文

这一讲的核心是：规范驱动开发（SDD）是 AI 原生开发的第一性原理。

传统软件开发的问题，不只是“写代码效率低”，而是从需求到实现之间存在多轮“失落的翻译”，导致意图不断损耗，文档与代码持续脱节。
SDD 通过一次“权力反转”，让规范取代代码，成为唯一真理之源，而代码只是规范在某个技术栈下的编译产物。

在这个新范式中，AI 扮演的是多阶段“意图编译器”：

• 从模糊想法生成 spec.md
• 从规范生成 plan.md
• 从方案生成 tasks.md
• 从任务生成最终代码

于是，传统以代码为中心的 Code → Test → Refactor 循环，被提升为以规范为中心的 Spec → Generate → Validate 循环。
这让开发者的主要工作从“手写大量实现”转向“定义意图、设计规范、编排流程、验证结果”。

English

The core of this lecture is that Spec-Driven Development (SDD) is the first principle of AI-native development.

The real problem in traditional software development is not only “slow coding,” but the repeated loss in translation between intent and implementation. Intent gets diluted, and documentation drifts away from code.
SDD reverses this relationship: the specification becomes the single source of truth, while code becomes a compiled artifact of that specification within a specific tech stack.

In this new paradigm, AI acts as a multi-stage intent compiler:

• vague ideas → spec.md
• spec.md → plan.md
• plan.md → tasks.md
• tasks.md → final code

As a result, the traditional Code → Test → Refactor loop is elevated into a specification-centered Spec → Generate → Validate loop.
This shifts the developer’s role from manually writing large amounts of code to defining intent, designing specs, orchestrating workflows, and validating results.

💡 十五、一句话记忆 / One-Sentence Memory Hook

传统开发是在“翻译意图写代码”，AI 原生开发是在“编译规范生代码”。
Traditional development translates intent into code; AI-native development compiles specifications into code.