规范驱动开发 (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 体系中最关键的核心枢纽？
在整个 SDD（PRD → ADR → PLAN → IMPL）生命周期中，ADR（架构决策记录）是整个工程化架构的定海神针与核心枢纽，其关键意义体现在以下四个维度：
┌──────────────────────────────┐
│ PRD：解决「做什么」(What) │
│ 业务诉求 · 用户故事 · 验收标准 │
└──────────────┬───────────────┘
│
┌──────────────▼───────────────┐
│ ⭐ ADR：解决「怎么架构」(How) │ ◄───【核心枢纽：架构防腐、选型裁决、契约基准】
│ 技术选型 · 数据模型 · API 契约 │
└──────────────┬───────────────┘
│
┌──────────────▼───────────────┐
│ PLAN：解决「怎么排期」(When) │
│ 原子任务 · 依赖顺序 · 改动路径 │
└──────────────┬───────────────┘
│
┌──────────────▼───────────────┐
│ IMPL：解决「怎么编码」(Code) │
│ 测试驱动 · 代码落地 · 质量验收 │
└──────────────────────────────┘- 跨越业务与代码鸿沟的唯一桥梁：
PRD关注业务价值与用户体验，Plan与Impl关注文件路径与代码函数。- 如果缺乏
ADR直接从 PRD 跨入编码，由于缺少系统设计、数据模型、状态机与接口契约的严谨论证，AI 生成的代码极易陷入“局部可用但整体架构畸形”的陷阱。ADR 是将抽象业务诉求翻译为坚固软件架构的唯一转换器。
- 不可逆决策的防御屏障（Architecture Defense）：
- 界面文字或局部逻辑随时可以低成本修改，但数据模型、分层通信协议、核心第三方库选型、鉴权机制等架构决策具有极高的重构代价。
- ADR 强制在落子前对备选方案（Options）、技术权衡（Pros/Cons）与改动影响面（Blast Radius）进行论证，把架构风险扼杀在写代码之前。
- 记录「为什么这么做」与「被否决方案」的活化石：
- 翻看 PRD 无法知道技术实现细节，翻看代码无法知道当时为什么不采用方案 B。
- 只有 ADR 沉淀了决策背景与被否决的方案（Rejected Alternatives），为未来系统演进、团队接手以及架构替代（
/adr supersede）提供了唯一权威的上下文真相源。
- 硬性工程护栏与质量闭环底座：
- 在所有规范阶段中，ADR 是唯一直接接入 Git 提交硬门禁（
/adr-guard on）的环节，确保团队在引入重大特性（feat:）或架构重构（refactor:）时，架构决策永不缺席。
- 在所有规范阶段中，ADR 是唯一直接接入 Git 提交硬门禁（
与独立 ADR 治理体系 (adr-guard) 的协同关系
ADR 在工程化体系中具备双重身份：
- 独立架构治理底座 (
adr-guard)：独立运行/adr new、/adr supersede、/adr tree/map、/adr check/lint、单层扁平/三层分层模式，以及 Git 提交门禁 (/adr-guard on)。 - SDD 核心架构阶段 (
/adr)：作为 SDD 规范生命周期的第二阶段，自动继承/prd的需求作为决策依据，并作为/plan任务分解的技术架构基石。
SDD 作为「生命周期编排者」，而 adr-guard 作为「专业架构决策引擎」。日常单点技术改动可随时单独使用 /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 忽略的项目目录（
.opencode/handoffs/）。 - 一键在新会话中无缝恢复：生成一条可直接复制粘贴的开场白（
Read .opencode/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 状态与隐式上下文，供新会话接手 | .opencode/handoffs/ |
/sdd help | 显示 SDD 指南与帮助文档 | 主对话界面 / TUI |