它为什么突然火了

早期使用 AI 编程时人们习惯直接在聊天框里说一句“给登录页加个验证码”，接下来让模型开始改代码。这种方式很快，也很刺激，所以被称为 Vibe Coding。但项目稍微复杂一点，问题就出现了：模型不知道哪些行为不能破坏。不记得十轮之前确认过什么也分不清一句需求是在描述业务目标还是暗示技术方法。它可能飞快地交付一套完整实现，只是实现了错误的东西。

使用者痛点：缺乏上下文记忆导致需求漂移，模型频繁产生误解。

SDD 正是针对这种失控感出现的。它的基本主张并不复杂：不要让 Agent 收到一句模糊指令就立刻写代码，先把要做什么写清楚。 一套常见流程大致如下：

1. 把产品目标、使用者场景、需求边界和验收条件整理成 Spec。
2. 让 Agent 根据 Spec 调研代码库并生成技术设计。
3. 把设计拆成可执行的任务列表。话说回来，
4. 由 Agent 逐项实现。再是否符合预期，
5. 某些流派在交付后继续保留 Spec。后续功能变化时先更新 Spec，再修改代码。怎么说呢，

不同工具给这些文件起了不同名字。但结构大同小异，Kiro 常见的是 requirements.md → design.md → tasks.md；GitHub spec‑kit 会生成 Spec、计划、研究和任务等一组文件；OpenSpec 则用 proposal、delta spec、design、tasks 组织一次变更，并在归档时把增量需求合并进长期 Spec。

它的出发点是合理的。Coding Agent 的能力越强，理解偏差的破坏力越大。人手写错十行代码，评审时往往能看出来；不过，Agent 在错误前提上一次生成几十个文件。表面上却可能结构完整、测试齐全。先明确目标、约束和验收条件，可以让人和模型在付出实现成本之前发现分歧。

使用者痛点：缺少统一的需求表达导致反复返工，团队难以追踪谁负责哪些信息。

SDD 也顺应了一个很有吸引力的想象：既然大模型已经能把自然语言翻译成代码。开发者是否可以从代码细节中进一步抽身，转而维护更高层的业务意图？Spec 成为人和 AI 的共同语言，代码退化为可生成的“最终一公里”。需求变了就改 Spec，Agent 自动传播到设计、任务、测试和实现。不再围绕代码展开，而是围绕意图展开。

This narrative hits several real pains in AI coding: context loss across chat turns,ambiguous prompts yielding random results,need for task decomposition,multi‑person review,and verification of agent output. After tools like GitHub spec‑kit。AWS Kiro,OpenSpec,Tessl appeared,SDD quickly morphed from a prompt‑organization trick into a touted new development paradigm.

使用者痛点：团队缺乏可复用的高层意图文档，使得每次迭代都要重新解释需求。

问题也恰好出在这里。 "编码前把需求写清楚"是一个朴素而正确的建议。但它并不能自然推出"Spec 应该成为长期事实来源"，更不能推出"多数项目都需要一套 SDD 工作流”。

使用者痛点：S​pec 的维护成本与收益之间缺乏明确衡量标准。其实，

每隔一段时间。软件领域都会重新发明一次“只要把需求写得足够清楚，代码就会自然出现”。以前叫 CASE、MDD、DSL、低代码，现在叫 Spec‑Driven Development。新故事里的关键角色从确定性代码生成器换成了大模型，旧问题却一个没少：谁来保证描述正确。谁来维护描述与实现的一致，需求变化后谁负责同步，还有这份描述究竟给谁看。 说起来，

使用者痛点：治理责任模糊导致文档与实现脱钩。

我的判断很直接：Spec‑first 在部分任务中有价值；Spec‑anchored 需要极强的治理能力；Spec‑as‑source 对多数业务项目仍接近一场昂贵的信仰实验。把三者统称为 SDD，再把最理想化的收益宣传给所有项目，是问题所在。

都没说清楚

Birgitta Böckeler 是 Thoughtworks 的杰出工程师，拥有二十多年的软件开发、架构与技术领导经验。不过， 她在 Martin Fowler 的个人网站发表《Understanding Spec-Driven-Development: Kiro。spec-kit,and Tessl》，结合对 Kiro、spec-kit 和 Tessl 的实际试用，对 SDD 的定义与现实适用性提出了程序质疑。怎么说呢，她把当前简单讲 SDD 分成了三层：

1. Spec-first: 编码前先写一份当前任务的 Spec。任务结束后可以删除，
2. Spec-anchored: Spec 在功能交付后继续保留，后续演进持续更新。
3. Spec-as-source: Spec 才是主要源文件。人只修改 Spec，代码只是生成物。老实说，

This three‑tier view looks like degrees of commitment but actually represents three fundamentally different engineering contracts.

• User Pain: Teams often start with low‑bar Spec-first and later are forced into high‑overhead Spec-as-source without realizing jump.
• Spec-first: a contextual prompt;cheap to try.
• Spec-anchored: a long‑term documentation governance regime.
• Spec-as-source: akin to model‑driven development – it reshapes code ownership。debugging,review and release pipelines.

S​pec 本身也没有稳定定义。它可能是使用者故事、验收标准、PRD、技术设计、接口契约、任务清单、领域规则…一个词同时装下“为什么做、做什么、怎么做、如何验证”。得到的不是统一语言，而是一只没有所有者的文档泥潭。

合格工程产物必须回答的问题
谁编写。谁审批，谁维护， 它描述意图、当前行为还是目标行为？不过， 它对人、对模型还是对自动化工具负责？ 与代码、测试、PRD、ADR 冲突时谁有裁决权？ 它什么时候失效，需要删除？ 如何证明它完整、新且内部一致？

If se questions remain unanswered,“Spec is single source of truth” is just a marketing slogan.

二 、 它卡在上下文工程与传统产出物之间，两边都不讨好

如果 Spec 是上下文工程，它本质上仍是提示词

A one‑off spec that only serves current Coding Agent and can be discarded after task is essentially a templated Prompt. Structured format brings clarity—fixed goals,constraints and acceptance criteria—but does not magically grant factual authority.

• User Pain: Treating prompts as “specs” gives a false sense of rigor while still suffering from model hallucination.

The more honest approach is “planning-with-files”: #task_plan.md。#findings.md,#progress.md. These files record **state** rar than **truth**,can be archived or deleted once irrelevant,and avoid building an unnecessary parallel knowledge base.

如果 Spec 是传统研发产出物，它多半只是 PRD 的再包装

If a spec is intended to live long term for product & engineering review—defining business behavior and acceptance—n it overlaps with existing artifacts:

• P​​RD/Requirement docs for product intent.
• A​DRs for architectural decisions.
• I​nterface contracts for API boundaries.
• T​ests / contract tests for verifiable behavior.

The core question becomes: **Who is this spec for?**

• If it’s for humans → keep it short,stable and decision‑focused;话说回来，no implementation details.
If it’s for models → verbose & self‑contained but quickly becomes noisy.
• If it’s for machines → formal syntax + validator required;natural language fails.

三、“单一事实来源”最容易制造多个事实来源

A mature codebase already has many knowledge carriers: PRDs,ADRs,code,tests,schemas,monitoring/logs。Issues & Git history .

Add a long‑living spec on top of m and you don’t replace anything—you create an extra artifact that must be kept in sync. Every change now asks “Which documents need updating?” increasing risk of divergence.

User Pain: Document drift multiplies maintenance effort without improving safety.

1. The original gap 娱乐ween code & requirements motivates creating a spec.
2. Manual specs drift → desire auto‑generated/spec-maintained by agents.
3. If agents maintain both code **and** spec simultaneously。spec becomes just anor inference artifact—not an independent evidence source.

If first inference is wrong,subsequent cycles reinforce mistake across both docs—a classic “context corruption”. Code still benefits from compilers & tests;natural language specs lack such automatic checks.

User Pain: The verification bottleneck shifts from compile errors to human review of lengthy natural language documents.

四 、 历史项目不是 SDD 的沃土，而是它最危险的压力测试

The difficulty in legacy systems isn’t lack of description—it’s contradictory existing artifacts. Code may reflect outdated requirements;tests protect accidental behaviours;comments may be years old;configuration may have diverged from source control;话说回来，veterans remember exception rules after incidents.

If you ask an agent to reverse engineer a full spec from such a system you face an unsolvable semantic problem: Is generated text describing **business intent** or merely **current behaviour**?

User Pain: The risk of “documenting away” technical debt by reclassifying quirks as official requirements.

An effort to backfill Specs across millions of lines equals re‑understanding entire system—a costly digital archaeology exercise that rarely yields ROI. Even when tools like OpenSpec advocate incremental delta Specs instead of full backfills,y still inherit core contradictions:

• Only parts touched by recent changes get documented → gaps remain unknown.
• Partial coverage creates uncertainty about what “unspecified” means.
• Delta merges reduce edit conflicts but don’t guarantee baseline correctness.

User Pain: The team ends up with some specs y trust too much while ignoring large undocumented zones.

五 、 新项目也未必适合：不确定性最高时 文档最容易贬值

User Pain: Overinvesting in detailed specs creates “documentation tax”。slowing iteration.

If tomorrow’s decision flips today’s written proposal/spec/design/tasks — you’ve just wasted effort on paperwork rar than learning from experiments. Teams eir become bogged down maintaining specs or abandon m entirely – ending up with stale “source of truth” artifacts that nobody trusts.

• Tiny tasks = hammering a nut with a sledgehammer.
• Large ambiguous tasks = mass documenting guesses.
• Clear stable tasks = traditional PRDs/ADRs/tests already suffice.

User Pain: The “formal context” gives illusion of control while actual risk migrates into hard-to-verify natural language.

七 、 真正值得长期维护的，不是“统一 Spec”，而是少量高价值事实

内容	合适载体	原因
当前任务目标/计划/发现/进度	planning-with-files 或类似任务文件	服务当前执行，可恢复，可删除，不冒充永久真相
产品目标与验收边界	PRD / Issue / 使用者故事	有明确业务 Owner，可随产品决策演进
关键且长期技术决策	ADR	记录背景、“为什么”、代价及备选方案
API / 数据跨服务契约	/OpenAPI,Protobuf,Schema,类型
稳定业务行为	;自动化测试 / 合约测试 / 示例	;可执行，失败即给出明确反馈
当前实现 & 实际调用链	;代码 / 运行结果 / 日志 / Tracing	;证明程序现在真的做了什么
临时假设与探索结论	;对话稿件 / findings.md

User Pain: Lack of explicit rationale makes future teams repeat past mistakes or make uninformed changes.

八 、 什么时候可以用 SDD

/Stable requirement boundaries with high failure cost – need pre‑aligned acceptance criteria.< / Li> < Li> /Cross‑team or cross-repo collaboration requiring shared behavioural contracts.

---