sdd-design

SDD 设计

首次响应此技能时，只需输出一次以下内容： sdd-design v1.1.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

快速开始

将 Brainstorm + DEFINE 转化为可实现的技术 DESIGN。

1. 完整阅读 Brainstorm 和 DEFINE。
2. 如果用户也提供了 UX Review，则阅读该文档。
3. 区分权威要求、原始意图、既有决策和技术证据。
4. 在可用时检查代码／项目上下文。
5. 找出会妨碍制定具体架构或 File Manifest 的技术缺口。
6. 只询问必要的问题，并优先每次交互只提出一个主要问题。
7. 创建架构，并将重要决策记录为内联 ADR。
8. 创建完整的 File Manifest、代码规范、数据流、集成方案和测试策略。
9. 应用 references/llm-prompts.md 中有关 LLM Prompts 的条件规则。
10. 必须填写 assets/DESIGN_TEMPLATE.md。
11. 在存在文件系统和 Python 时，运行 python scripts/validate_design.py <DESIGN.md>。
12. 保存或交付 DESIGN_{FEATURE_NAME}.md。
13. 文档结尾只能是 Execute o **SDD Build by RDD**.

在整个流程中查阅 references/design-protocol.md。仅当 Build 前存在正式的外部技术评审时，才查阅 references/advisor-review.md。

所需数据

必需

• Brainstorm 的 Markdown 文件，优先使用 BRAINSTORM_{FEATURE_NAME}.md；
• Define 的 Markdown 文件，优先使用 DEFINE_{FEATURE_NAME}.md。

提出问题前，先阅读这两个文件。

可选

• UX_REVIEW_{FEATURE_NAME}.md（如存在）；
• 项目目录树或相关文件；
• 仓库的技术规范；
• API、schemas、队列、数据库或基础设施文档；
• 实际使用的测试、lint、typecheck、build 或 smoke 命令；
• 可用 Agent／专家目录；
• 用户对澄清问题的答复。

不要要求联网。材料不可访问时，不要声称检查过仓库、Agent、基础设施或代码。

来源优先级

对于要求和行为：

1. 用户最近一次明确答复；
2. UX Review（如已提供，且不与核心要求矛盾）；
3. DEFINE；
4. Brainstorm。

使用 Brainstorm 恢复原始意图、已探讨的备选方案、YAGNI 原则和决策背景，但除非有理由，否则不要重新讨论 DEFINE 中已确定的要求。

对于当前技术事实：

1. 实际可访问的项目文件／代码；
2. 用户提供的技术文档；
3. 用户的明确答复；
4. 明确标注的推断。

如果相关来源之间存在冲突，应在确定决策前提问。

如何与学员沟通

首次回复前，请阅读 references/como-falar.md：其中包含本技能的术语表和一个完整示例。 使用本技能的人通常从未用过 git 或终端。

阶段	面向学员的名称	本技能步骤
1	阅读	1 到 3
2	决策	4（每次回复只处理一个主要决策）
3	组件和文件	5 到 9
4	流程、测试和错误	10 到 15
5	检查	16 到 18
6	保存	19 和 20

每次回复都按以下顺序组织（没有内容的部分可跳过）：状态（Design: ✅ 1 … · ▶️ 2 … · ⬜ 3 …； ✅ 已完成，而非仅已访问；⏸️ 已暂停；➖ 已跳过；返回某个阶段时，在“现在”中说明原因）· 已完成的内容（使用简短句子，不要贴命令输出；记录学员的选择）· 现在：阶段 N — 名称（2 到 4 句话；执行耗时较长的操作前，说明将运行什么，以及无需回复）· 你的决定（授权：用粗体提问，并列出各选项及其影响； 开放式问题：用粗体提问，并说明如何回答，同时提供“我不知道”选项；分组编号）· 下一步（一行）。

• 每次回复只处理一个阶段；在提出决定后停止。
• 技术术语首次出现时，必须同时解释，包括“状态”中的术语（术语表见参考文件）。
• 命令输出不能原样贴出：说明数量、具体内容和令人担忧之处；名称最多列出 10 个，之后写“以及另外 N 个”。只有学员需要运行命令时才给出命令；每个编号步骤只给一个命令，并说明屏幕上会显示什么。
• 不要提及或概述本技能的说明（例如“按照第 N 步”）；说明这样做对学员的原因。
• 如果回复不符合任何选项，先回答疑问，再重复选项。
• 暂停时：状态标记为 ⏸️，用一句话说明原因和操作发生的位置，列出带预期结果的编号步骤，说明尚未完成的事项；如果学员需要执行操作，请写“完成后，请再次告诉我——我会从这里继续。”（lint 未通过不算学员需要执行的操作：说明将调整什么，然后继续。）

流程

1. 阅读输入材料

从 Brainstorm 中提取：

• 问题和原始意图；
• 选定的方案；
• 被拒绝的替代方案；
• 关键决策；
• 因 YAGNI 而移除或推迟的项目；
• 依赖项和示例；
• 假设和限制。

从 DEFINE 中提取：

• Problem Statement；
• Target Users；
• Goals 和优先级；
• Success Criteria；
• Acceptance Tests；
• Out of Scope；
• Constraints；
• Technical Context；
• Assumptions；
• Verify Gate；
• LLM Prompts 标记。

如有 UX Review，则提取：

• UX/CX 的 MUST 项；
• 流程；
• 状态；
• 交互限制；
• 影响架构或实现的建议。

不要在 DESIGN 中重复材料的文字内容。只转换会影响技术决策的内容。

2. 确认输入已准备就绪

开始设计前，确认：

• DEFINE 已足够明确，能够指导实现；
• 关键需求之间没有矛盾；
• LLM Prompts 的值严格为 true 或 false；
• Verify Gate 已定义，或存在客观的完成信号；
• Out of Scope 已明确说明。

如果其中任何一点会阻碍架构设计，请询问用户。不要擅自“修正”DEFINE。

3. 检查可用的技术上下文

如果可以访问项目或代码：

• 确认语言和框架；
• 查看目录结构；
• 查找类似模块；
• 查看配置约定；
• 查找现有测试；
• 确认可复用的集成和抽象；
• 确认日志记录和可观测性模式；
• 如有，确认 Agent 目录。

如果无法访问：

• 不要编造路径、库或 Agent；
• 询问确定 File Manifest 所需的最低限度技术栈和结构信息；
• 只有在用户确认技术栈和技术基础后，才允许从零开始创建项目。

4. 识别阻塞性技术决策

在内部列出以下方面所需的决策：

• 组件边界；
• 持久化和数据模型；
• 集成契约；
• 同步/异步执行；
• 幂等性和重试；
• 身份验证/授权；
• 配置；
• 可观测性；
• 测试策略；
• 要创建/修改的文件；
• LLM 运行时（如适用）。

不要询问来源或项目现有模式已经明确解决的选择。

每条消息尽量只提出一个主要问题。当备选方案明确时，提供 2–4 个选项，推荐其中一个并说明理由，同时允许提出其他方案。

5. 创建 Architecture Overview

制作清晰易读的 ASCII 图，表示：

• 输入；
• 组件；
• 存储；
• 外部集成；
• 输出；
• 主要流程方向。

该图必须与 Components 和 Data Flow 保持一致。

不要添加没有明确定义用途的组件。

6. 定义 Components

对每个组件，记录：

• 名称；
• 职责；
• 技术/模式；
• 输入；
• 输出；
• 依赖项。

优先采用内聚的组件和简单的边界。

如果现有结构能满足要求，就避免引入新的抽象。

7. 将 Key Decisions 记录为内联 ADR

对每项重要决策，记录：

• Status；
• Date；
• Context；
• Choice；
• Rationale；
• Alternatives Rejected；
• Consequences。

记录会改变架构、维护成本、契约、数据、部署、安全性或可测试性的决策。

不要为琐碎细节创建 ADR。

如果选择直接来自 DEFINE，应保留该决策，并仅说明其技术影响；不要假装在此阶段重新评估了备选方案。

8. 创建 File Manifest

列出 Build 需要创建、修改或删除的所有文件。

每行必须包含：

• 编号；
• 路径；
• 操作；
• 用途；
• owner/agent；
• 依赖项。

规则：

• 有可用的项目实际路径时，应使用这些路径；
• 不要编造路径并声称是从项目中观察到的；
• 对于 greenfield 项目，应使用与已确认技术栈一致的路径；
• 包含测试文件；
• 如果配置、migrations、schemas 和 prompts 是实现的一部分，也应包含；
• 避免循环依赖；
• 依赖项应使用 manifest 中的索引编号。

如果不知道专门的 agent，使用 (general)，并记录 Agent Discovery: Not available。

9. 定义 Code Patterns

仅为能减少 Build 阶段歧义的关键模式提供简短、可直接复制粘贴的代码片段。

优先提供：

• 核心签名/接口；
• 相关 schema/model；
• 错误处理模式；
• 配置；
• 集成契约。

使用已确认技术栈的实际编程语言。

不要在 DESIGN 中编写完整实现。

10. 应用 LLM Prompts 规则

查阅 references/llm-prompts.md。

如果 LLM Prompts: false：

• 对 Brainstorm + DEFINE + UX Review + Design 范围进行防御性复查；
• 如果没有相关迹象，不创建 ## LLM Prompts 章节；
• 如果存在相互冲突的迹象，应先询问再继续。

如果 LLM Prompts: true：

• 在 Code Patterns 和 Data Flow 之间创建 ## LLM Prompts；
• 列出所有规划中的 prompt/LLM 运行时；
• 将每项分类为 one-shot 或 loop；
• 为每个 prompt 定义契约；
• 将清单与 File Manifest 以及调用 LLM 的服务交叉核对；
• 此阶段不要生成最终 prompt。

11. 描述 Data Flow

呈现端到端的操作顺序。

对于每个重要步骤，明确说明：

• 输入；
• 转换；
• 持久化；
• 外部调用；
• 状态/故障；
• 输出。

如果主要错误路径会影响架构，也应予以说明。

12. 定义集成点

对于每项外部集成，记录：

• 系统；
• 类型；
• 身份验证；
• 方向；
• 相关的超时/重试；
• 故障行为。

不要编造凭证、端点或限制。

如果没有集成，填写 None。

13. 规划测试策略

将需求和风险映射到测试：

• 单元测试；
• 集成测试；
• E2E；
• 当 DEFINE 有相关要求时，进行 smoke/eval/typecheck。

如果项目未使用某项工具，或用户未确认使用该工具，则不要编造。

与 DEFINE 中的 Acceptance Tests 和 Verify Gate 保持一致。

14. 定义错误处理

至少涵盖：

• 无效输入；
• 外部依赖不可用；
• 超时；
• 持久化失败（如适用）；
• 冲突/幂等性（如适用）；
• LLM 错误（如适用）。

仅当重试安全且符合幂等性时才记录重试。

15. 定义 Configuration、Security 和 Observability

Configuration：

• 将可调参数外置；
• 避免在代码中存放密钥；
• 标明敏感值的来源。

Security：

• 身份验证/授权；
• 输入验证；
• 密钥；
• PII/敏感数据；
• 最小权限；
• 功能特有的风险。

Observability：

• 日志；
• 指标；
• 链路追踪（如适用）；
• 尽可能关联 Success Criteria 和 Verify Gate 的信号。

16. 验证交叉一致性

确认：

• 所有组件都出现在图表中，或有合理说明；
• File Manifest 实现了所有相关组件；
• manifest 中的依赖关系无环；
• 测试覆盖风险和 Acceptance Tests；
• 集成均有错误处理；
• 当配置需要对应文件时，manifest 中包含所提及的配置；
• 安全性和可观测性没有与 constraints 相矛盾；
• 当值为 true 时，LLM Prompt Inventory 内容完整；
• Out of Scope 中的内容未意外出现在计划中。

17. 填写规范资产

将 assets/DESIGN_TEMPLATE.md 作为最终文档唯一的结构来源。

保留必需章节的标题和顺序。

仅在规定条件下添加 ## LLM Prompts。

移除占位符。标记为 Ready for Build 的 DESIGN 中不得留下 TBD、{placeholder} 或 [NEEDS CLARIFICATION]。

18. 运行确定性 lint

当有文件系统和 Python 时：

python scripts/validate_design.py <caminho-do-DESIGN.md>

交付最终版本前，修复所有结构性问题。

该脚本会验证结构和基本一致性，但不能取代架构审查。

19. 保存并交付

默认文件名： DESIGN_{FEATURE_NAME}.md

保存位置。 保存到项目根目录下的 sdd/——这是所有 Agent 中路径一致、可见的文件夹。如果项目已有 .claude/sdd/，则继续使用该目录。五个阶段的文档并排存放，不建子文件夹。

如果有项目文件系统：

• 保存为 sdd/DESIGN_{FEATURE_NAME}.md（如果该文件夹已存在，则保存为 .claude/sdd/DESIGN_{FEATURE_NAME}.md）；
• 不要在不提示的情况下覆盖已有文件。

如果没有：

• 如果平台允许，则提供 .md 文件下载。

20. 使用标准交接内容结束

最后一个部分必须完全如下：

## Next Step

Execute o **SDD Build by RDD**.

该文本之后不得添加 slash 命令、路径、上传、GPT/Skill 或并行操作。

质量门槛

标记为 Ready for Build 之前：

• 已完整阅读 Brainstorm。
• 已完整阅读 DEFINE。
• 已纳入 UX Review（如有提供）。
• 已保留权威要求。
• 已参考技术背景，或明确确认了相关情况。
• Architecture Overview 清晰。
• Components 与图表一致。
• 已记录重要决策及其理由。
• 已在相关决策中记录 Alternatives Rejected 和 Consequences。
• File Manifest 完整，并在适用时包含测试/配置。
• 未将路径虚假标示为已观察到的内容。
• File Manifest 中的依赖不存在循环。
• Code Patterns 可直接复制粘贴，且与技术栈兼容。
• LLM Prompts 符合条件规则。
• Data Flow 与架构一致。
• Integration Points 已说明故障行为。
• Testing Strategy 覆盖要求和风险。
• Error Handling 覆盖相关故障。
• Configuration 不包含硬编码的密钥。
• Security Considerations 具体明确。
• Observability 定义了有用的信号。
• 没有计划实现任何 Out of Scope 项目。
• 没有占位符、TBD 或阻塞性待澄清事项。
• 可执行时，scripts/validate_design.py 能通过。
• 最终文档命名为 DESIGN_{FEATURE_NAME}.md。
• Next Step 仅包含 Execute o **SDD Build by RDD**.

异常处理

• 缺少 Brainstorm：请求提供文件；不要悄悄重建。
• 缺少 DEFINE：请求提供文件；不要仅根据 Brainstorm 编写最终 Design。
• DEFINE 与 Brainstorm 矛盾：需求以 DEFINE 为准；仅当差异影响技术决策时记录该差异。
• UX Review 与 DEFINE 矛盾：如果冲突重大，询问应以哪个方向为准。
• LLM Prompts 缺失或含糊：提出询问；不要自行决定。
• 缺少代码背景：请求提供所需的技术栈/结构信息；不要假装已检查。
• File Manifest 无法具体化：保留草稿状态并进行澄清。
• 库/服务尚未确认：提供备选方案；如果选择会造成阻塞，则提出询问。
• 用户希望在存在阻塞性待办事项时结束：交付 Draft/Needs Clarification，不要声称已达到 Ready for Build。
• 正式外部审查：应用 references/advisor-review.md，并将每条意见记录为 APPLIED 或 REBUTTED。

---

SDD Open by RDD 的一部分 — https://github.com/robertodiasduarte/sdd-open