SDD 指南
与 Agent 协作时，需求通常从几句对话开始，再随着方案讨论和实现不断补充。目标、边界、约束和验收标准散落在多轮对话中，Agent 和开发者很难始终基于同一套信息推进工作。因此，需要把这些内容整理成可持续更新的规格，为后续设计、实现和验收提供稳定依据。
什么是 SDD
这种以规格为共同依据、先明确要求再推进开发的方式，就是 SDD（Spec-Driven Development，规格驱动开发）。SDD 通常覆盖以下信息：
这些信息不必一一对应独立文档，具体组织方式取决于工具。无论采用哪种目录结构，SDD 都从澄清规格开始，再进入技术设计、任务拆解、实现和交付：
OpenSpec
OpenSpec 是一个开源的 SDD 工具，以变更为单位组织需求、规格、设计和任务，并在完成后归档相关产物，使变更过程和历史都可追踪。
安装与初始化
全局安装：
进入项目并初始化：
初始化后，项目里会出现 openspec/ 目录：
specs/ 是已经生效的能力规格，是系统当前行为的事实来源，按领域组织，例如 specs/auth/、specs/payments/。changes/ 是正在设计或实现的变更，每个变更一个目录，相关的设计文档和规格增量都放在里面。增量规格可以在归档前手动同步，也可以在归档过程中按提示合入主规格。
核心产物
每个变更目录包含四类核心产物：
常用命令
默认的 core profile 包含以下命令：
切换到自定义 profile 后，还可以启用以下扩展命令：
需要扩展命令时，执行 openspec config profile 选择工作流，再在项目中执行 openspec update。
变更流程
下面以“增加密码重置功能”为例，走一遍变更的创建、实现、验证和归档。在 Codex 中，输入 $ 选择对应的 OpenSpec skill，例如 $openspec-propose；在 Claude Code 中，使用 /opsx:* 命令。下文以 Claude Code 的写法为例。
提出变更
OpenSpec 会根据描述生成变更名，并在信息不足时继续确认需求。生成的变更目录可能如下：
实施变更
apply 会读取变更产物，按 tasks.md 逐项实现，并同步更新任务状态。
验证变更
如果已启用扩展工作流，可以在归档前执行 verify：
verify 会从完整性、正确性和一致性三个维度检查实现，并将问题分为 CRITICAL、WARNING、SUGGESTION。它不会阻止归档，但应先处理 CRITICAL，并评估 WARNING。
归档变更
归档会检查产物和任务的完成状态，在规格增量尚未同步时询问是否合入主规格，然后把变更移到 openspec/changes/archive/YYYY-MM-DD-<change-id>/。
调整变更
沿用前面的密码重置变更。实现中发现重置链接的有效期尚未明确，需要先澄清取舍、更新产物，再继续实现。
梳理方案
先梳理安全性与使用体验之间的取舍：
更新产物
确定有效期为 15 分钟后，更新受影响的产物：
update 会修改 specs/password-reset/spec.md，并根据影响范围同步更新 design.md 和 tasks.md。
继续实施
确认产物一致后，继续执行：
Superpowers
Superpowers 是一套面向编码 Agent 的开发方法，由一组可组合的 skill 构成，用于约束 Agent 从需求澄清到分支收尾的整个开发流程。
安装
在 Codex 中，可以从官方插件市场搜索 Superpowers；在 Claude Code 中，可以执行：
安装后，Agent 会根据任务场景自动触发相应的 skill，通常只需说明目标和当前阶段。
完整 skill 列表
Superpowers 包含以下 14 个 skill：
核心开发流程
新功能开发通常沿以下主路径推进：
OpenSpec vs Superpowers
OpenSpec 和 Superpowers 解决的是 SDD 中的不同问题：
两者可以组合使用：OpenSpec 提供可追踪的变更上下文和验收依据，Superpowers 据此推进实现、评审和验证。
协作原则
- 人负责判断方向：确认需求价值、产品边界、工程取舍和验收标准。Agent 可以提供建议，但关键决策仍由人确认；
- Agent 负责推进执行：根据目标、范围和验收标准搜索代码、拆解任务、修改实现并运行验证；
- 按复杂度选择流程：涉及多处联动或关键取舍时先写规格；明确的局部修改直接实现并验证即可。