第一篇  SDD初探
第1章  为什么你的软件项目总是延期	2
1.1  软件项目的三大顽疾	3
顽疾一：需求漂移	3
顽疾二：实现偏差	4
顽疾三：沟通成本	5
1.2  传统开发流程的困境	5
瀑布模型：完美的计划，残酷的现实	5
敏捷开发：解决了流程，没解决规格	6
产品需求文档的根本问题	7
1.3  AI编程时代的范式转变	7
AI不是银弹	7
范式转变：从“怎么写”到“写什么”	8
1.4  SDD是什么	9
SDD的核心原则	9
3个递进层次	10
SDD的工作方式	11
一个Spec长什么样	11
1.5  本书学习路线图	12
你将构建的系统	12
本书各章对应的功能实现	13
如何使用本书	14
第2章  认识OpenSpec——你的AI编程规范搭档	15
2.1  OpenSpec的设计哲学	15
Fluid not Rigid（灵活不僵化）	15
Iterative not Waterfall（迭代而非瀑布）	16
Simple not Complex（简单不复杂）	16
Brownfield-first（存量优先）	17
2.2  核心概念速览	17
Spec——系统的“行为真相源”	17
Change——“我想改什么”	18
Delta Spec——“和现在的有什么不同”	18
Artifact——Change的组成部分	18
2.3  OpenSpec项目的目录结构	19
2.4  两种工作流模式	20
默认：Core Profile（5个命令）	21
可选：Expanded Workflow（11个命令）	21
选择指南	22
2.5  OpenSpec的能力边界	22
擅长的事	22
不擅长的事	22
2.6  OpenSpec与Spec-Kit的对比	23
概况对比	23
设计哲学对比	23
命令体系对比	24
Artifact机制对比	24
选型建议	24
2.7  环境准备	25
安装Node.js	25
安装Claude Code	25
安装Codex CLI	26
本章小结	27
第3章  快速上手——安装、配置与实现第一个Change	29
3.1  环境确认	29
3.2  安装OpenSpec	30
3.3  初始化项目	30
3.4  编写项目配置	32
这个配置如何工作	32
几个配置技巧	33
让OpenSpec用中文撰写内容	33
3.5  实现你的第一个Change	34
执行命令	34
AI做了什么	35
看看AI生成了什么	36
3.6  CLI常用命令速查	38
3.7  动手：OpenSpec基本操作	41
本章小结	42
第二篇  OpenSpec基础
第4章  从需求到规格——编写高质量Spec	44
4.1  需求≠规格	44
需求的本质是“愿望”	44
规格的本质是“契约”	45
一个“血的教训”	45
4.2  Spec文件结构解剖	46
Purpose——一句话定义模块边界	47
Requirement——系统必须做到的事	48
Scenario——可验证的实例	49
4.3  GIVEN、WHEN、THEN编写指南	50
3层覆盖原则	50
5个常见错误及修正	52
Scenario质量自检表	54
4.4  Delta Spec详解	55
为什么需要Delta Spec	55
ADDED——追加需求	55
MODIFIED——替换现有需求	56
REMOVED——删除需求	57
Delta Spec的归档合并过程	58
动手：创建add-dark-mode（练习MODIFIED操作）	58
4.5  Lite Spec与Full Spec：渐进式严谨	61
Lite Spec——日常功能开发	62
Full Spec——高风险变更	62
选择决策树	63
4.6  动手：为Team KB创建用户认证功能Spec	64
环境确认	64
第一步：创建Change	65
第二步：创建Proposal	65
第三步：手动创建Spec（核心步骤）	66
第四步：检查你的Spec	69
第五步：验证	69
第六步：实施	70
4.7  写好Spec的7个习惯	71
习惯一：先写Scenario，再归纳Requirement	71
习惯二：把Scenario当作6个月后的测试用例	71
习惯三：异常路径至少占Scenario总数的30%	71
习惯四：用具体的值，拒绝笼统的描述	72
习惯五：Spec是活文档，实现中随时更新	72
习惯六：给复杂功能画状态机	72
习惯七：Spec审查胜过Spec编写	73
4.8  常见问题与排查	73
Q：应该为一个功能写多少Scenario	73
Q：Spec应该多详细	73
Q：发现Spec写错了怎么办	73
本章小结	74
第5章  设计决策与任务拆解	75
5.1  何时需要Design	75
决策框架	75
不写Design时	76
5.2  Design的结构与要素	77
Context——背景	77
Goals/Non-Goals——目标与非目标	77
Decisions——技术决策	78
Data Flow——数据流	80
Risks/Trade-offs——风险与权衡	81
5.3  编写可执行清单	81
好的任务长什么样	81
任务排序原则	82
完整的任务示例	83
5.4  Fast-Forward模式与Continue模式的选择	85
深入理解两种模式	85
选择的实战准则	85
5.5  动手：为Team KB设计文章CRUD功能	86
第一步：创建Change（用Fast-Forward模式）	86
第二步：审查并完善Design	90
第三步：审查并完善Tasks	91
第四步：验证	91
第五步：实施	91
5.6  Design的常见反模式	94
反模式一：Design变成了“操作手册”	94
反模式二：过度设计	94
反模式三：没有写“为什么”	95
5.7  实战技巧：Artifact迭代的节奏	95
“三轮迭代”模式	95
何时该更新Artifact	95
本章小结	96
第6章  让AI写出符合规格的代码	97
6.1  /opsx:apply的工作原理	97
完整的执行流程	97
3种状态的处理	98
AI如何理解代码库	99
6.2  Claude Code apply实战	99
先应用前置Change	99
创建add-search Change	100
前置准备	102
启动实现	103
启用SQLite FTS5全文搜索扩展	105
实现搜索API	106
前端搜索组件	108
实现完成的总结	110
6.3  Codex apply实战对比	110
命令格式的差异	110
执行流程一致	111
实际对比	111
核心结论	112
6.4  实现中的迭代修正	112
场景一：设计时发现不可行	112
正确的处理方式	113
场景二：Spec遗漏了场景	113
6.5  并行工作与中断恢复	114
场景：因紧急Bug打断开发	114
tasks.md作为进度标记的原理	115
6.6  动手：实现Team KB的搜索功能	116
第一步：确保Change就绪	116
第二步：启动实现	116
第三步：观察并参与	116
第四步：实现过程中的决策	116
第五步：验证实现	116
常见问题排查	117
6.7  apply过程中的常见问题	117
Q：AI生成的代码不符合我的代码风格怎么办	117
Q: 一个任务太大，AI在中途暂停了吗	118
Q：我能在apply过程中手动修改代码吗	118
Q：AI实现的功能和Spec不一致怎么办	118
本章小结	118
第7章  验证、同步与归档——完成一次完整迭代	120
7.1  为什么需要验证	120
3个真实的风险	120
/opsx:verify就是为这3个风险设计的	121
7.2  /opsx:verify三维检查详解	121
启动验证	121
解读验证结果	123
7.3  修复验证时发现的问题	124
路径A：修正代码（当Spec正确时）	124
路径B：修正Spec（当Spec不合理时）	124
关键原则	125
7.4  /opsx:sync——将Delta Spec合并进主Spec	125
同步的3个行为	125
4种需要单独执行/opsx:sync的场景	126
7.5  /opsx:archive——完成闭环	126
第一步：将Delta Spec合并进主Spec中	126
第二步：移动到归档目录	126
第三步：保留完整上下文	127
归档的价值	127
7.6  完整的迭代闭环演示	127
完整的时间线	127
完整的闭环图	128
7.7  以CLI方式归档	128
7.8  动手：完成用户认证的完整闭环	129
第一步：确认add-user-auth的Artifact完整	129
第二步：实现	129
第三步：验证	129
第四步：根据验证结果行动	129
第五步：归档	130
第六步：确认归档结果	130
本章小结	130
第8章  探索模式与渐进式开发	132
8.1  需求模糊是常态	132
面对现实	132
不要过早进入Spec	133
8.2  /opsx:explore探索模式详解	133
探索模式是什么	133
启动探索	134
探索模式下的AI行为	134
探索模式的立场	136
8.3  从探索到变更的无缝转换	136
转换过程	137
探索结论如何影响Artifact质量	137
8.4  增量式构建：MVP优先，逐步迭代	138
从“大而全”到“小而精”	138
增量式开发与大爆炸式开发的对比	138
8.5  动手：探索并实现Team KB的权限系统	139
第一步：启动探索	139
第二步：观察AI的探索过程	139
第三步：从探索到创建Change	140
第四步：创建并实现	140
完成后的Team KB全貌	142
8.6  探索模式的哲学	143
本章小结	144
第三篇  OpenSpec进阶
第9章  团队协作与工作流定制	146
9.1  自定义Schema工作流	146
为什么需要自定义Schema	146
复刻现有Schema	147
复刻Artifact详解	147
编辑Schema：添加review.md	151
创建新Artifact的模板	152
从零创建Schema	152
验证、设置和使用	153
9.2  Config深度定制	153
context是AI的项目认知窗口	153
rules按Artifact生效	154
验证配置是否生效	154
9.3  多工具协作	155
安装多工具支持	155
多工具命令格式对照	155
团队协作场景	156
9.4  团队Change管理最佳实践	157
Change的粒度	157
命名规范	157
归档纪律	157
9.5  跨角色应用——产品经理、测试工程师、设计师、技术负责人如何用好
OpenSpec	158
产品经理的OpenSpec用法	158
测试工程师的OpenSpec用法	159
设计师的OpenSpec用法	161
技术负责人的OpenSpec用法	162
跨角色协作全景	163
9.6  动手：为Team KB创建自定义工作流	163
本章小结	164
第10章  源码透视——OpenSpec核心命令与Skill架构解析	165
10.1  架构总览	165
10.2  依赖图引擎	166
Schema中的依赖声明	166
拓扑排序与状态判定	167
三态状态机	167
openspec status的JSON解读	167
10.3  Skill指令机制	168
以propose为例	168
为什么Skill用Markdown而不是硬编码	168
指令注入机制	169
10.4  Skill与Command的双轨制	169
10.5  3个核心Skill的执行逻辑对比	170
propose——基于DAG的增量创建	170
apply——有状态的逐任务循环	172
explore——没有固定步骤的思考伙伴	173
三者对比	173
10.6  从Legacy到OPSX的演进	174
10.7  源码文件系统布局	174
本章小结	177
第11章  最佳实践、常见陷阱与未来展望	178
11.1  OpenSpec的10个最佳实践	178
11.2  7个常见陷阱	180
陷阱一：把Spec写成了实现指南	180
陷阱二：MODIFIED只写了变化的部分	180
陷阱三：任务粒度过粗或过细	180
陷阱四：Spec只有正常路径	180
陷阱五：忘记同步、直接归档	181
陷阱六：context太长或太短	181
陷阱七：在多个并行Change中修改同一个Spec	181
11.3  Team KB项目的完整回顾	181
系统演进全景	181
最终的openspec/目录	182
关键数字	182
11.4  版本演进路线	183
已发布版本	183
社区现状	183
未来版本路线图	184
11.5  OpenSpec的生态与未来	184
当前能力	184
社区Schema	184
CI/CD集成方向	185
11.6  你的下一步	185
刚学完本书	185
在团队中推广	185
持续学习	185
本章小结	186
附录A  OpenSpec CLI命令速查	187
附录B  Slash Command速查	189
附录C  Team KB Change索引	191
附录D  术语表	192
附录E  实践案例——智能书城	193