规范驱动开发 (SDD / Specification-Driven Development)
规范驱动开发（SDD）提供了一套结构化、规范先行的工程化研发流程体系，将业务需求、架构决策、任务计划与代码实现紧密连接。
SDD 生命周期
[/prd: 需求规格] ──▶ [/adr: 架构决策] ──▶ [/plan: 任务分解] ──▶ [/impl: 编码执行与验证]
│ │ │ │
└────────────────────┴─────────────────────┴─────────────────────────┘
(支持任意阶段起手与自由阶段跳转)/prd [topic]：需求规格说明书 (Product Requirements Document)- 明确问题背景、用户画像、用户故事 (US-xx)、功能需求 (FR-xx)、非功能需求 (NFR)、边界/排除范围 (Out of Scope) 与验收标准 (Given/When/Then)。
- 自动生成并维护在
docs/prd/<topic>.md。
/adr [title]：架构决策记录 (Architecture Decision Record)- 记录技术选型、架构分层、数据模型、API 契约、利弊权衡与决策后果。
- 自动生成并维护在
docs/adr/（支持单层扁平模式与分层模式）。
/plan [topic]：实施计划与任务分解 (Implementation Plan)- 将 PRD 与 ADR 规范细化拆解为原子化、测试驱动的实施阶段与任务清单。
- 自动生成并维护在
docs/plan/<topic>.md。
/impl [task]：编码实现与验证交付 (Implementation & Verification)- 严格依照 Plan、ADR 与 PRD 进行测试驱动编码，遵循 Karpathy 代码质量准则。
- 自动运行单元测试、类型检查 (
tsc) 与质量门禁。
🏛️ ADR：记录具有架构重要性的决策
在 SDD（PRD → ADR → PLAN → IMPL）生命周期中，ADR（架构决策记录）为「改错了代价极高」的决策提供锚点 —— 它是一个自适应阶段，而非每个变更都必须经过的强制关卡：
架构基线 / ADL（架构决策日志）
↕
PRD 或需求
↓
ADR 记录 —— 仅针对具有架构重要性的决策
↓
计划 / 任务 → 编码实现 → 测试验证 → 发布与观察
↓
下一轮演进中的新 ADR、修订或取代（supersede）何时需要编写 ADR —— 以下重大变更应触发 ADR：
- 结构：模块划分、分层架构、服务边界、代码归属
- 质量属性：性能、可伸缩性、可靠性、可观测性
- 依赖：框架、平台、核心第三方库选型
- 接口：API、通信协议、事件契约、数据模型
- 数据：存储引擎、迁移策略、数据保留、一致性模型
- 安全：认证、授权、密钥管理
- 财务/业务规则：计价、佣金、账本不变量
- 难以回退的选择：上线后撤销成本极高的任何决策
琐碎变更（文案调整、无架构影响的局部缺陷修复与重构）可跳过 ADR 阶段，从需求直接进入计划与实现。
该阶段在适用时的价值体现在：
- 不可逆决策的防御屏障（Architecture Defense）：
- 界面文字或局部逻辑随时可以低成本修改，但数据模型、分层通信协议、核心第三方库选型、鉴权机制等架构决策具有极高的重构代价。
- ADR 强制在落子前对备选方案（Options）、技术权衡（Pros/Cons）与改动影响面（Blast Radius）进行论证，把架构风险扼杀在写代码之前。
- 记录「为什么这么做」与「被否决方案」的活化石：
- 翻看 PRD 无法知道技术实现细节，翻看代码无法知道当时为什么不采用方案 B。
- ADR 沉淀了决策背景与被否决的方案（Rejected Alternatives），为未来系统演进、团队接手以及架构替代（
/adr supersede）提供权威的上下文真相源。
- 可选的硬性工程护栏：
- 按需开启（
/adr guard on）的项目可将 Git 提交门禁挂在 ADR 上，使具有架构重要性的feat:/refactor:变更无法在未记录的情况下落地。该门禁是按项目开启的开关，并非 SDD 流程的内置前提。
- 按需开启（
与独立 ADR 治理体系 (adr) 的协同关系
ADR 在工程化体系中具备双重身份：
- 独立架构治理底座 (
adr)：独立运行/adr new、/adr supersede、/adr tree/map、/adr check/lint、单层扁平/三层分层模式，以及 Git 提交门禁 (/adr guard on)。 - SDD 核心架构阶段 (
/adr)：作为 SDD 规范生命周期的第二阶段，自动继承/prd的需求作为决策依据，并作为/plan任务分解的技术架构基石。
SDD 作为「生命周期编排者」，而 adr 作为「专业架构决策引擎」。日常单点技术改动可随时单独使用 /adr，大型特性开发则通过 SDD 四阶段获得全链路规格护航。
核心特性
1. 任意阶段起手
开发者可根据实际任务进展自由从任意阶段切入：
- 从零构思新功能/新业务 →
/prd <feature> - 评估系统架构决策与选型 →
/adr <decision> - 架构明确，需要精细化任务排期 →
/plan <feature> - 紧急修复或已有方案的单点实现 → 直接
/impl <task>
2. 交互式阶段流转提示 (Interactive Stage Transitions)
每个阶段完成时，系统会自动生成规范制品摘要，并通过交互式选项（如 ask_question 或选择菜单）主动询问开发者后续步骤：
- 推荐下一阶段：如
/prd→/adr，/adr→/plan，/plan→/impl。 - 自由跨阶段跳转：对于轻量需求，可直接从
/prd跳转至/impl。 - 回退与调整：在
/plan阶段发现架构漏洞时，可随时回退到/adr或/prd。 - 停留在当前阶段：确认当前产物并结束流转。
3. 会话热上下文与磁盘冷制品的双重协同
推荐在同一个会话中连续流转 SDD 流程：
- 会话内热上下文 (Hot Context)：会话内保留了全部业务潜台词、细微约束与被否决方案（Rejected Alternatives），使得后续
/plan任务拆解与/impl编码实现达到极限精准度，彻底消除割裂会话带来的认知断层与信息衰减。
4. 跨会话暂存与状态交接 (/sdd handoff)
当需要暂停开发、切换任务或会话 Context 过大时，可随时执行 /sdd handoff：
- 自动锁定当前阶段：准确记录当前完成的阶段（如 PRD/ADR 已完成，待执行 Plan）与制品链接。
- 萃取隐式讨论认知：将未写入 Markdown 的被否决方案与约束打包存入 Git 忽略的项目目录（
.ocp/handoffs/）。 - 一键在新会话中无缝恢复：生成一条可直接复制粘贴的开场白（
Read .ocp/handoffs/latest.md...），在新会话中以极简 Token 消耗满血继续流转。
指令速查表
| 指令 | 说明 | 对应产物目录 |
|---|---|---|
/prd [topic] | 创建或维护需求规格说明书 | docs/prd/<topic>.md |
/adr [title] | 创建或废弃/替代架构决策记录 | docs/adr/ |
/plan [topic] | 创建分阶段实施任务计划 | docs/plan/<topic>.md |
/impl [task] | 执行编码实现与自动化测试验证 | 源码文件与测试套件 |
/sdd status | 检查项目内所有 SDD 规范制品清单 | 主对话界面 / TUI |
/sdd handoff [msg] | 暂存当前 SDD 状态与隐式上下文，供新会话接手 | .ocp/handoffs/ |
/sdd help | 显示 SDD 指南与帮助文档 | 主对话界面 / TUI |