5 人 7 天干完 20 人数周的活：Spec-Driven Development 如何重新定义 AI 编程

这是 2026 年的第 58 篇文章

（本文阅读时间：约 20 分钟）

前言：「5 人 7 天」实验

本文通过一个案例展示高效开发的奇迹：5 人团队仅用 7 天，借助 Qoder 开发出 QoderWork，完成了传统模式下需 20 人数周的工作量。其核心时间线复盘如下：

DAY 0：零代码，全 Spec

团队全天聚焦四件事：定义 MVP 边界、拆解模块、撰写模块 Spec、汇入 Repo Wiki。这一天虽无代码产出，却奠定了后续六天的基石。

DAY 1-2：架构与容器并行开发

全员化身"Spec 工程师”，定义代码形态。通过 Skill 驱动与 Quest 模式并行执行任务，两天内系统骨架成型。

DAY 3-4：Spec 迭代与增量需求

面对新需求或 BUG，无需排期，立即撰写增量 Spec 并委派 Quest 执行。AI 自动编码提交 PR，人工负责 Review 与合并，单人日均处理多个 PR，效率显著提升。

DAY 5-6：打磨与 Dogfooding

利用 QoderWork 早期版本测试自身，发现问题即写 Spec 修复，形成自举式正反馈循环。

DAY 7：正式发布上线

七天从零到可用产品落地。

该案例的震撼之处不在于"AI 写代码快”，而在于5 人如何驾驭 AI 并行推进大量任务而不失控。答案在于 DAY 0 产出的 Spec，这套方法论被称为：Spec-Driven Development（SDD，规格驱动开发）。

01 SDD 是什么：代码只是 Spec 的副产品

1.1 一句话定义

Spec-Driven Development：将规格说明（Specification）作为唯一真实来源（Single Source of Truth），代码作为其派生产物。

简言之，即先定义 WHAT，再让 AI 做 HOW。SDD 是专为 AI 编程时代设计的工程方法。在传统开发中，Spec 影响沟通效率；而在 AI 编程中，Spec 质量直接决定代码质量。因为 AI 不会追问边界情况，模糊的指令会导致推断错误进而产生 Bug。

1.2 时代的汇聚而非单一发明

SDD 是 2025 年多个方向收敛的结果，反映了 AI 编程发展的结构性需求：

• Karpathy 的 Vibe Coding：暴露了“不管代码只管感觉”的弊端，倒逼社区思考约束机制；
• GitHub Spec Kit：提供 Agent 无关的 SDD 工具链；
• AWS Kiro：首个内置 SDD 工作流的 IDE；
• Fission-AI OpenSpec：探索轻量级迭代路线；
• 阿里 QoderWork：通过 Quest 模式实践 SDD 规模化执行。

1.3 Microsoft 的评价

"SDD is version control for your thinking."

传统版本控制管理代码演变，SDD 管理思考的演变：为何做此功能、边界何在、成功标准为何。当代码可被 AI 秒级重写时，背后的决策逻辑才是核心价值。

02 SDD 完整流程拆解

2.1 四阶段模型

SDD 标准流程分为四个阶段：

Specify（规格定义）-> Plan（方案规划）-> Implement（代码实现）-> Validate（验证确认）

阶段	主导者	核心产出	关键动作
Specify	人	spec.md	定义问题、边界、成功标准
Plan	人 + AI	plan.md	架构选型、模块划分、接口定义
Implement	AI	代码 + 测试	按 plan 逐任务实现
Validate	人 + AI	测试报告	自动化测试 + 人工 Review

人机分工核心原则：人定义 WHAT，AI 实现 HOW。实践中，Specify 与 Plan、Implement 与 Validate 之间存在多轮迭代循环。

2.2 三文件体系：Spec Kit 的核心设计

GitHub Spec Kit 提出了简洁的三文件体系：

spec.md —— 需求规格

作为「唯一真实来源」，回答“做什么”和“为什么”，不涉及“怎么做”。

# Feature: 用户权限管理模块
## Problem Statement
当前系统缺乏细粒度的权限控制。所有用户要么是管理员（全部权限），
要么是普通用户（只读权限）。产品团队需要支持至少 5 种角色，
以满足不同部门的差异化需求。
## Success Metrics
- 支持自定义角色，每个角色可配置不少于 20 种独立权限
- 权限校验 API 响应 P95 < 50ms
- 权限变更实时生效，无需用户重新登录
- 向后兼容：现有管理员/普通用户的权限行为不变
## User Stories
1. 作为系统管理员，我可以创建自定义角色并分配权限组合
2. 作为部门主管，我可以将部门成员批量分配到指定角色
3. 作为普通用户，我的权限变更后无需重新登录即可生效
## Acceptance Criteria
- [ ] RBAC 模型支持角色继承（最多 3 层）
- [ ] 单用户可拥有多个角色，权限取并集
- [ ] 提供权限变更审计日志，保留 90 天
- [ ] 权限校验支持通配符匹配（如 `resource:*:read`）
## Non-Goals
- 本期不实现跨组织的权限委托
- 不支持基于时间段的临时权限
- 不涉及 UI 层的权限管理界面（由前端团队单独出 Spec）
## Constraints
- 必须兼容现有的 OAuth2.0 认证流程
- 权限数据存储使用现有 PostgreSQL 实例，不引入新的存储组件
- 权限模型设计需参考 AWS IAM Policy 语法规范

好 Spec 的特征：

• 成功标准可测试：如"P95 < 50ms"而非“系统很快”；
• Non-Goals 明确边界：告诉 AI“不要做什么”；
• Constraints 约束选型：防止 AI 擅自引入新组件。

plan.md —— 架构方案

基于 spec.md 生成的技术方案，通常由 AI 起草，人工审核。

# Plan: 用户权限管理模块
## Architecture Decision
采用 RBAC (Role-Based Access Control) 模型，使用 Casbin 作为权限引擎。
## Module Breakdown
1. `permission-model` - 权限模型定义与 Casbin 适配层
2. `permission-api` - RESTful API 层
3. `permission-cache` - Redis 缓存层（解决 P95 < 50ms 要求）
4. `permission-audit` - 审计日志模块
## Interface Contracts
### POST /api/v1/roles
### GET /api/v1/users/{userId}/permissions
### PUT /api/v1/roles/{roleId}/permissions
（接口详细定义省略）
## Risk Assessment
- 风险：角色继承层级过深可能导致权限计算性能下降
- 缓解：限制最大继承深度为 3 层，权限结果做预计算缓存

tasks.md —— 任务清单

将 plan 拆解为可执行的原子任务，对应独立交付物。

# Tasks
## Task 1: 数据库 Schema 设计
- 创建 roles、permissions、role_permissions、user_roles 四张表
- 支持角色继承的 parent_role_id 字段
- 验证：migration 脚本可在空库上成功执行
## Task 2: Casbin 适配层
- 实现 RBAC 模型的 Casbin 配置
- 支持通配符匹配
- 验证：单元测试覆盖率 > 90%
## Task 3: 权限校验 API
- 实现 GET /api/v1/users/{userId}/permissions
- 集成 Redis 缓存
- 验证：压测 P95 < 50ms
（后续任务省略）

2.3 constitution.md：不可变的项目原则

Spec Kit 引入 constitution.md 作为项目“宪法”，定义所有 Spec 必须遵守的不可违背约束。

# Project Constitution
## Immutable Principles
### 1. API Design
- 所有 API 遵循 RESTful 规范，版本化路径（/api/v1/...）
- 错误响应统一使用 RFC 7807 Problem Details 格式
- 所有 API 必须有 OpenAPI 3.0 文档
### 2. Security
- 所有用户输入必须经过校验和清洗
- 敏感数据（密码、Token）禁止出现在日志中
- 数据库查询必须使用参数化查询，禁止字符串拼接
### 3. Code Quality
- 单元测试覆盖率不低于 80%
- 所有公共方法必须有文档注释
- 禁止引入未经安全审计的第三方依赖
### 4. Infrastructure
- 所有服务必须支持优雅关闭（Graceful Shutdown）
- 配置项通过环境变量注入，禁止硬编码
- 日志格式统一使用结构化 JSON

constitution.md 将技术决策固化为 AI 的「潜意识」，避免每个 Spec 重复声明基础约束。

03 Spec 怎么写：好 Spec 与坏 Spec 的生死线

Spec 写作是 SDD 最关键环节。DAY 0 投入整天时间，正是因为Spec 质量直接决定后续效率。

3.1 好 Spec 的六要素

要素	作用	示例
Problem Statement	定义 "为什么做"	"当前系统不支持细粒度权限控制"
Success Metrics	定义 "做到什么程度算完"	"P95 < 50ms，覆盖 20+ 权限类型"
User Stories	定义 "谁在什么场景下用"	"作为管理员，我可以创建自定义角色"
Acceptance Criteria	定义 "怎么验证"	"单用户多角色，权限取并集"
Non-Goals	定义 "什么不做"	"本期不做跨组织权限委托"
Constraints	定义 "技术约束"	"必须兼容现有 OAuth2.0 流程"

3.2 好 Spec vs 坏 Spec：一组对比

坏 Spec：

系统需要一个快速的搜索功能。搜索结果应该相关且准确。
界面要美观易用。

致命问题：1. 模糊（“快速”无量化标准）；2. 遗漏边界（搜索范围不明）；3. 缺乏理由（未说明解决何问题）；4. 混入 HOW（界面美观属 UI 范畴）。

好 Spec：

## Problem Statement
用户反馈在 10,000+ 文档的知识库中找到目标文档平均需要 3 分钟。
目标是将查找时间缩短到 10 秒以内。
## Success Metrics
- 搜索 API 响应时间 P95 < 200ms
- 搜索结果 Top-5 相关性准确率 > 85%（基于人工标注测试集）
- 支持中英文混合查询
## Non-Goals
- 不实现语义搜索（本期仅关键词匹配 + 分词）
- 不支持搜索附件内容（仅搜索文档标题和正文）

差异本质：好 Spec 是可测试的，坏 Spec 是可解释的。“系统应该很快”给 AI 无限解释空间，而"P95 < 200ms"是硬约束。

3.3 粒度控制：实用的检验标准

Spec Kit 提出检验标准：“换一种技术栈实现，Spec 是否仍然有效？”

若 Spec 规定“使用 Redis ZSET"，则耦合了 HOW；若规定“排行榜实时更新延迟<1 秒”，则无论底层用 Redis 还是 PostgreSQL 均成立，这才是正确的 WHAT 粒度。

3.4 淘特团队的实战经验

实践发现：Spec 编写需 3-5 次迭代才合格。第一版 Spec 常存在边界遗漏或标准模糊。通过"Spec -> Plan -> Review Spec ->修改”的循环，可将传统开发中“中途发现需求问题”的代价前移至成本最低阶段。

04 工具生态全景

SDD 已形成快速发展的工具生态，主要工具对比如下：

维度	Spec Kit (GitHub)	OpenSpec (Fission-AI)	Kiro (AWS)	QoderWork (阿里)
定位	Agent-agnostic 框架	轻量迭代工具	SDD-native IDE	Qoder Quest 执行引擎
Agent 支持	8+ Agent	25+ 工具	内置 Agent	Qoder 生态
核心特点	三文件体系 + constitution	轻量、快速迭代	完整 IDE 集成	Spec + Quest 并行执行
适用场景	通用项目	小型快速迭代	AWS 生态项目	阿里生态项目
学习曲线	中	低	中	中（需理解 Quest）
核心理念	Spec 即文档	Spec 即对话	Spec 即工作流	Spec 即任务单

4.1 各工具的差异化选择建议

• 追求通用性：选 Spec Kit。不绑定特定 Agent，支持主流模型，社区认可度高。
• 追求轻量和速度：选 OpenSpec。理念为"Spec 在对话中迭代”，适合小型项目。
• AWS 生态内：选 Kiro。SDD 工作流内嵌 IDE，省心省力。
• 规模化执行：QoderWork 的 Quest 模式最贴合 SDD，Spec 写完即委派执行，自动完成编码、PR 与测试。

05 实战数据：成功与失败都摆上台面

5.1 成功案例的硬数据

API 变更效率提升：arXiv 论文显示，金融领域 SDD 实践使 API 变更周期缩短75%。

代码错误率下降：研究表明，人工精炼 Spec 可将 LLM 代码错误减少50%，消除了 AI 的“猜测空间”。

Stripe 的规模化实践：通过 Harness Engineering 方法（含 SDD），Stripe 交付了1300 个 AI PR且未引发系统性问题，证明了可控性。

5.2 失败案例的警示数据

无 Spec 约束的安全灾难：Veracode 2025 报告揭示，45% 的 AI 生成代码包含安全漏洞（无 Spec 约束时）。明确定义安全约束可大幅降低漏洞率。

场景	关键指标
无 Spec 约束的 AI 编程	45% 代码含安全漏洞
有 Spec 约束的 AI 编程	代码错误减少 50%

代码重复率的隐性成本：GitClear 研究发现，AI 编程时代代码重复率 4 年增长4 倍。SDD 通过 constitution.md 规范和 plan.md 模块化设计可缓解此问题。

06 SDD vs Vibe Coding：一场必须正面交锋的辩论

6.1 什么是 Vibe Coding

Andrej Karpathy 提出的概念，主张“忘掉代码存在”，用自然语言描述需求，报错即扔给 AI 修复。适用于快速原型或个人脚本，但不可持续。

6.2 "三个月墙"：Vibe Coding 的生死劫

社区观察到「三个月墙」现象：

阶段	时间	状态	典型表现
兴奋期	1-3 个月	高产出	"AI 太神了！一天搞定一个功能！"
平台期	4-9 个月	停滞	"为什么新功能总是破坏旧功能？"
衰退期	10-15 个月	崩溃	"这坨代码没人能维护了，不如重写"

撞墙原因：Vibe Coding 是零上下文编程。项目膨胀后，AI 上下文窗口无法容纳全貌，基于局部信息的决策易与其他模块冲突。SDD 的 Spec 作为代码的压缩表示，让 AI 能理解全局约束后再动手。

6.3 核心差异对比

维度	Vibe Coding	SDD
核心假设	AI 能理解你的意图	AI 需要明确的规格才能正确执行
启动速度	极快	较慢（需先写 Spec）
可维护性	差（无文档、无约束）	好（Spec 即文档）
可协作性	差（只有作者知道 "vibes"）	好（Spec 是共享语言）
安全性	差（45% 安全漏洞）	较好（Spec 约束安全边界）
适用规模	小项目（< 1000 行）	中大型项目
天花板	三个月墙	取决于 Spec 体系质量

6.4 判断：不是非此即彼

Vibe Coding 与 SDD 是光谱两端。务实策略是混合模式：

1. 探索阶段用 Vibe Coding 快速试错；
2. 决定要做时立刻补 Spec，固化发现；
3. 正式开发后严格 SDD，变更先改 Spec。

07 SDD 与 Harness Engineering 的关系

AI 编程方法论演进链：Prompt Engineering -> Context Engineering -> Harness Engineering。

• Prompt Engineering：关注指令写法；
• Context Engineering：关注上下文精准度；
• Harness Engineering：关注系统性框架约束。

SDD 位于 Context 与 Harness 的交叉地带。Spec 是结构化上下文，constitution/spec/plan/tasks 四层组合构成了完整的「AI 驾驭框架」。Stripe 的 1300 个 AI PR 正是 HE 方法论的典型案例。

08 五大陷阱与局限性：诚实面对 SDD 的阴暗面

陷阱一：过度规格化（Over-Specification）

症状：Spec 比代码长，细节定死。后果：退化为自然语言伪代码。缓解：使用粒度检验标准，确保 Spec 不包含具体实现方案（HOW）。

陷阱二：规格腐烂（Spec Rot）

症状：代码迭代多版，Spec 仍停留在 V1。后果：Spec 与代码脱节，AI 基于过时 Spec 生成冲突代码。缓解：同步更新 Spec，将其作为日常操作。

陷阱三：规格官僚化（Spec Bureaucracy）

症状：微小变更也走全流程。后果：团队绕过流程。缓解：区分重大变更与微小变更，仅影响其他模块的行为才需 Spec。

陷阱四：虚假信心（False Confidence）

症状：因有 Spec 而放松审查。后果：Spec 不能保证实现正确安全。缓解：Spec 替代需求文档，但不替代 Code Review，Validate 阶段至关重要。

陷阱五：工具复杂性（Tool Overhead）

症状：引入过多工具链。后果：配置耗时超过写 Spec。缓解：从最简单方案开始（一个 spec.md + 一个 AI Agent）。

回应批评：「SDD 是 Markdown 版的瀑布模型」

批评认为 SDD 是先定义后实现的瀑布模型。事实上，SDD 的 Spec 是活的，支持增量更新。其迭代粒度是单个功能模块（Spec-Plan-Implement-Validate），而非整个项目，这与敏捷 Sprint 理念兼容，只是将 User Story 升级为结构化的 Spec。

09 SDD 的未来：三级光谱模型

SDD 正沿三级光谱演进：

级别	名称	当前状态	特征	代表实践
L1	Spec-First	当前主流	编码前写 Spec，但可能漂移	Spec Kit, 大多数团队
L2	Spec-Anchored	先进实践	Spec 与代码持续同步，测试强制一致性	Kiro 内置工作流
L3	Spec-as-Source	未来愿景	人只编辑 Spec，代码完全由 AI 生成维护	尚无成熟实践

L1 Spec-First

大多数团队现状。Spec 初期有价值，但随项目推进易与代码漂移，缺乏自动化强制一致机制。

L2 Spec-Anchored

先进团队探索方向。核心是用自动化测试锚定一致性：从 Acceptance Criteria 自动生成测试，代码变更必须通过测试，否则 CI 拒绝合并。

L3 Spec-as-Source

终极愿景：代码是被「编译」的。人类只编辑 Spec，AI 负责将变更自动反映到代码中。Thoughtworks 技术雷达已将其列入 Assess 环，正向 Trial 环迁移。

10 结语：DAY 0 是最贵的一天，也是最值的一天

回到"5 人 7 天”案例。表面奇迹发生在 DAY 1-6 的 AI 高效执行，但真正的关键在于DAY 0。

DAY 0 将人类的思考（需求边界、成功标准、技术约束）结构化固化到 Spec 中。这些 Spec 成为导航系统，让 5 人能驾驭 AI 并行任务而不失控。

SDD 的本质价值：它不让 AI 变聪明，它让 AI 变可控。

在 AI 能力飞速进化的今天，人们真正需要操心的是：当 AI 越来越强大时，能不能驾驭它？SDD 给出的答案是：把精力放在定义「WHAT」上，那是人类永远的领地。

从今天开始，试着在下一个功能需求前先写一个 spec.md。不需要完美，3-5 次迭代后会变好；不需要复杂工具链，一个 Markdown 文件足矣。

DAY 0 是最「贵」的一天，也是最「值」的一天。

欢迎留言一起参与讨论~