权力反转

代码服务于规范，前提是规范是可被机器精确理解和执行的

image-20251128170719686

编译意图

由 AI 驱动，将高层级、模糊的、非结构化的人类意图，逐步转换、细化，并最终固化为低层架、精确的、结构化的机器可执行指令

Stage Desc
需求编译器 将用自然语言描述的模糊想法，编译成一份结构化的、无歧义的需求规范 spec.md
方案编译器 将需求规范与技术约束相结合，编译成一份详尽的技术实现蓝图 plan.md
任务编译器 将技术蓝图，编译成一份带依赖关系的，原子化的任务指令集 tasks.md
代码生成器 最终，根据任务指令集，生成最终的可执行代码

SDD - 为 AI 的多阶段编译过程提供高质量的源代码（规范），并监督每一步编译的结果

工作流

阶段 1 - 意图定义

Key Value
目标 澄清并固化做什么（WHAT）和为什么做（WHY）
输入 开发者或产品经理提出的高层级、模糊的自然语言想法
核心活动 人机协作进行头脑风暴，挖掘边缘场景，澄清模糊地带，定义验收标准
输出产物 spec.md 需求规范
与技术实现完全解耦，只关心用户故事、功能需求和成功标准
spec.md 是后续所有阶段的唯一输入和宪法

阶段 2 - 技术规划

Key Value
目标 决定如何做（HOW）
输入 spec.md + 开发者提供的技术栈约束
核心活动 AI Agent 基于 spec.md，结合自身的工程知识和项目已有的 constitution.md
进行技术选型、架构设计、模块划分、API 契约定义等高层设计
输出产物 plan.md 以及其附属文档，将 spec.md 精确映射到技术实现上

阶段 3 - 任务分解

Key Value
目标 将 HOW 分解成 ACTIONS
输入 plan.md 及其附属设计文档
核心活动 AI Agent 分析 plan.md，将其拆解成一系列具体的、原子化的、可执行的开发任务
关键：需要识别任务之间的依赖关系和可并行点
输出产物 tasks.md，是 AI Agent 的 TODO List，其格式和内容必须是机器友好的

阶段 4 - 自动化实现

Key Value
目标 完成所有任务，生成最终产物
输入 tasks.md
核心活动 AI Agent 严格按照 tasks.md 指令，逐一执行任务，包括创建文件、编写代码、运行测试等
开发者在此阶段的核心职责是监督、审批高风险操作，以及对最终结果进行验收
输出产物 可运行的软件代码、测试用例、文档等

这四个阶段，构成了一个从抽象意图到具体实现的完整逻辑链条

GitHub spec-kit

spec-kit 是 SDD 的一个杰出实现（通过一系列标准化的 Slash Commands 实现），而 Claude Code 等 AI Agent 正是执行 SDD 的理想工具

image-20260103152923525

照片相册应用 - spec.md（产品经理） -> plan.md（架构师） -> tasks.md（技术组长），最后交给 AI Agent（程序员）实现

步骤 描述
意图输入 - /speckit.specify 向 AI Agent 输入一个自然语言的想法：Build an application that can help me organize my photos…
编译成规范 - spec.md AI Agent 扮演产品经理的角色，与你互动（或基于内置模板），将你的模糊想法编译成一份结构化的 spec.md
同时，AI Agent 会为你创建一个新的 Git 分支，如 001-photo-albums
技术选型 - /speckit.plan 进入技术决策阶段，告诉 AI：The application uses Vite…vanilla HTML, CSS, and JavaScript…SQLite database.
编译成方案 - plan.md AI Agent 扮演架构师的角色，将技术选型与 spec.md 的需求结合，生成一份详尽的 plan.md
生成任务列表 - /speckit.tasks 下达指令，不需要额外参数
编译成字节码 - tasks.md AI Agent 扮演技术组长的角色，读取 plan.md，将其分解为上百个具体的带依赖关系和并行标记的原子任务，生成 tasks.md
执行执行 - /speckit.implement 下达最终执行指令
执行字节码 - Code AI Agent 像一个勤奋的程序员，严格按照 tasks.md 的指令列表
逐一完成编码、测试、创建文件等所有工作，最终交付可运行的应用程序

spec-kit 框架将 SDD 的通用思想，固化为一套可执行、可重复的工程实践

开发范式

SDD 的引入，不仅仅是改变了项目的启动流程，更是从根本上重塑了日常的开发迭代循环

传统开发循环 - 以代码为中心

敏捷开发：Code -> Test -> Refactor

image-20260103160450366

  1. 循环非常高效，但半径很小，始终围绕着实现层面
  2. 当需求发生较大变更时，该循环会别打破，需要回到更上游的设计阶段，成本很高

AI 原生开发循环：以规范为中心

在 SDD 范式下，开发循环被提升到了一个更高的维度，变成了一个以规范为中心的 Spec -> Generate -> Validate 循环

image-20260103160859045

在该新循环中，开发者的主要工作不再是直接编写和重构海量代码，而是

工作 描述
演进规范 思考并修改 spec.md 来响应需求变化
触发生成 指挥 AI Agent 基于新的规范重新生成实现
审查验证 验收 AI Agent 的产出是否符合规范的意图
  1. 该循环的半径更大，直接作用于意图层面
  2. 其优势在于，迭代的成本大大减低了
    • AI Agent 接管了最耗时、最容易出错的代码翻译环节
    • 可以用前所未有的速度、实现不同的需求、不同的架构、甚至不同的技术栈

SDD - AI 原生开发的未来

SDD 是与 AI Agent 能力天然契合、相辅相成的核心引擎

  1. SDD 有助于解决 AI 的模糊性难题
    • LLM 本质上基于统计的，对模糊指令的理解存在不确定性
    • SDD 通过结构化的规范，将模糊的自然语言，转换为 AI 可以精确执行的“机器语言”，极大地提升了输出的可靠性
    • SDD 通过 一份严谨的规范来精确地编程 AI 的行为
  2. SDD 加速了软件的迭代循环
    • 在传统模式下，需求变更意味着昂贵的人工代码修改成本
    • 在 SDD 模式下，业务逻辑的核心被固化在更高层次的 spec.md 中
    • 当需求变化时，只需要修改规范，然后快速地重新编译整个实现
    • 软件开发的迭代速度，从周/天级别，提升到小时/分钟级别，使得真正的敏捷（快速响应变化），成为可能
  3. SDD 释放了 AI 的并行潜力
    • tasks.md 中的并行标记 [p]，为多个 AI Agent 协同工作，或单个 AI Agent 并行执行任务提供了可能
    • 这突破了人类开发者线性工作的瓶颈，为实现真正的 10 倍效能打开了大门
  4. SDD 创造了真正的活文档
    • 当文档（规范）成为驱动代码生成的唯一源头时，文档与代码不一致这个问题，将被彻底解决
    • 规范即文档，文档即代码，代码即实现
  5. SDD 最终赋能开发者
    • SDD 将开发者从繁琐、重复的实现细节中解放出来 - CRUD
    • 让我们能将更多的智慧和精力，投入到更高价值的业务建模、架构设计和工作流优化中去

局限性

  1. 在今天，要实现一套完全无缝、100% 自动化的 SDD 流程，仍然存在一定的门槛和挑战
  2. 主要受限于
    • 当前 LLM 在超长链条、复杂逻辑推理上的稳定性
    • 以及像 Claude Code 这类客户端智能体工具在具体任务执行的鲁棒性和上下文环境感知深度上的局限

当下是系统性学习和实践 SDD 的最佳时机