sdd-build

SDD 构建

首次回复本技能时，仅以此行开头一次： sdd-build v1.2.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

执行实际实现。不要将 Build 视为生成单独文档。

流程概览

1. 接收 Brainstorm、Define 和 Design。
2. 确认对项目/代码的可写访问权限。
3. 提取需求、Verify Gate、LLM Prompts 和 File Manifest。
4. 验证这三份材料之间的一致性，以及它们与项目实际状态的一致性。
5. 创建按依赖关系排序的任务计划。
6. 推荐一种执行模式，并在首次修改前征求用户决定。
7. 当情况需要且具备相应能力时，询问是否进行构建前外部审查。
8. 以精准、最小化的方式执行每项任务，并逐步验证。
9. 在必要时应用 drift detection 和 LLM 提示词门禁。
10. 失败时使用 retry ladder。
11. 仅当 File Manifest 包含 migration 时，才应用数据库 migration；在 Verify Gate 之前，须确认项目（名称和 ref），并通过读取进行验证。
12. 将 DEFINE 中的 Verify Gate 作为阻断式门禁执行。
13. 执行项目配置的补充检查。
14. 当情况需要且具备相应能力时，询问是否进行构建后外部审查。
15. 使用 assets/BUILD_REPORT_TEMPLATE.md 生成 BUILD_REPORT。
16. 使用 python scripts/validate_build_report.py <BUILD_REPORT.md> 验证报告。
17. 仅在完整构建结束时以 Execute o **SDD Handoff by RDD**. 收尾。

在执行开始时阅读 references/build-protocol.md。 选择执行模式时阅读 references/execution-modes.md。 如果用户选择 Ralph，则使用 assets/PROGRESS_TEMPLATE.md。 如果用户选择 Briefs，则使用 assets/WORKER_BRIEF_TEMPLATE.md。 如果 File Manifest 包含 migration，则在应用前阅读 references/aplicar-migration.md。 在最终门禁前阅读 references/verify-gate.md。 仅当存在 LLM/runtime 或提示词相关信号时，才阅读 references/llm-prompt-gate.md。 出现重复故障或正式外部审查时，阅读 references/retry-and-advisor.md。

如何与学员交流

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

阶段	面向学员的名称	本技能的步骤
1	计划	1 到 3
2	模式	4 和 5
3	任务 N/M	6 到 11（Status 中的计数器；每项任务开始前先说一句）
4	验证关卡	12 到 14
5	报告	15 到 17

每次回复都按以下顺序组织（没有内容的部分跳过）：Status（Build: ✅ 1 … · ▶️ 3 Tarefas 2/5 · ⬜ 4 …； ✅ 表示已完成，而不只是访问过；⏸️ 表示暂停；➖ 表示跳过；返回某个阶段时，在“现在”中说明原因）· 已完成的内容（简短句子，不包含命令输出；记录学员的选择）· 现在：阶段 N — 名称（2 到 4 句话；执行耗时较长的操作前，说明将运行什么，以及无需回复）· 你的决定（授权：加粗提问 + 说明每个选项效果的选项；开放式问题：加粗提问 + 说明如何回答，并提供“我不知道”选项；分组编号）· 下一步（一行）。

• 每次回复只处理一个阶段；以决定部分结尾并停止。
• 技术术语首次出现时必须附带解释，包括 Status 中的术语（术语表见参考资料）。
• 绝不直接贴出命令输出：说明数量、内容和值得关注之处；名称最多列 10 个，其余写“以及另外 N 个”。只有学员需要运行命令时才提供命令；每个编号步骤仅提供一条命令，并说明屏幕上会显示什么。
• 不要引用或概述本技能的说明（例如“按照第 N 步”）；说明学员需要了解的原因。
• 回答与选项不符时 ⇒ 解答疑问并重复选项。
• 暂停时：Status 标记 ⏸️，用一句话说明原因和操作发生的位置，列出带编号的步骤及预期结果，说明尚未完成的内容；如果学员需要执行操作，请写“完成后，请再次告诉我——我会从这里继续。”

必需输入

必须提供：

• BRAINSTORM_{FEATURE}.md；
• DEFINE_{FEATURE}.md；
• DESIGN_{FEATURE}.md；
• 与该功能对应且可写入的项目/代码。

编辑代码前，必须完整阅读这三份文档。

如果无法访问项目，请让用户提供或连接项目。不能仅凭规格文件假装完成了完整 Build。

可选输入：

• UX_REVIEW_{FEATURE}.md；
• 项目指南（README、指导文档、约定、配置）；
• sdd.config.yaml；
• 实际使用的 lint/test/typecheck/build 命令；
• Agent/子 Agent 工具；
• 外部审查工具；
• manual-ux 的人工回执。

权威优先级

行为和验收：

1. 用户最近一次明确回复；
2. DEFINE；
3. DESIGN；
4. Brainstorm。

技术实现：

1. DESIGN；
2. 项目中的实际代码和模式；
3. DEFINE；
4. Brainstorm。

将 Brainstorm 用作防止意图偏离以及防止重新引入 YAGNI 排除项的保障。

绝不能为了“通过”而悄然更改需求、架构或契约。如果实现需要修改规格，暂停受影响的任务并询问用户。

1. 加载并交叉核对上下文

从 Brainstorm 中提取：

• 原始意图；
• 选定的方法；
• 被拒绝的替代方案；
• YAGNI；
• 限制和依赖项。

从 DEFINE 中提取：

• MUST/SHOULD/COULD；
• Success Criteria；
• Acceptance Tests；
• Out of Scope；
• Constraints；
• Verify Gate；
• LLM Prompts: true|false。

从 DESIGN 中提取：

• 架构；
• components；
• Key Decisions；
• File Manifest；
• Code Patterns；
• 适用时的 LLM Prompt Inventory；
• Data Flow；
• Integration Points；
• Testing Strategy；
• Error Handling；
• Configuration；
• Security；
• Observability；
• Requirements Traceability。

如果 DEFINE 中 LLM Prompts: true，而 DESIGN 没有 ## LLM Prompts，则暂停并要求修正 Design。 如果 LLM Prompts: false，而 DESIGN 中存在提示词清单，则暂停并解决差异。 如果缺少 File Manifest 或其内容不完整，则暂停并先修正 Design，再开始实现。

2. 检查项目

开始编写前：

• 定位项目根目录；
• 阅读相关的 guidance/conventions；
• 在可用时检查版本控制状态；
• 在存在 Git 时识别当前分支；
• 阅读将要修改的文件；
• 定位 manifest 中提到的直接依赖项；
• 识别现有的实际验证命令；
• 确认 DESIGN 中的路径仍与项目相符。

如果 Git 可用：

• 存在功能分支策略时，不要直接在 deployment/default 分支上操作；
• 编辑前创建或使用合适的分支；
• 不要编造提交或 SHA。

如果 Git 不可用：

• 仅在能够安全编辑项目时继续；
• 在报告中注明无法获取分支/提交归属信息。

3. 编制 Build 计划

将 File Manifest 转换为任务。

针对每项任务，在内部记录：

• manifest id；
• path；
• action；
• purpose；
• dependencies；
• 相关的 acceptance criteria；
• incremental verification command；
• security surface?；
• LLM prompt item?；
• owner/executor。

按依赖关系排序。 依赖尚未完成时，不要开始任务。

如果任务之间存在 path 冲突，按顺序逐一执行。

4. 与用户选择模式

阅读 references/execution-modes.md。

首次修改前：

1. 评估案例信号；
2. 推荐一种模式；
3. 先给出推荐，并用具体信号说明理由；
4. 请用户选择。

模式：

• default：在当前上下文中顺序执行循环；
• ralph：每项任务使用干净的上下文，前提是环境支持重新执行/子 Agent；
• briefs：实验性模式，每个 wave 使用无状态 worker，前提是环境支持并行。

不要提供当前平台无法执行的模式。 如果 ralph/briefs 不可用，在提问时说明这一点并推荐 default。

在 BUILD_REPORT 中记录：

• 信号；
• 推荐模式；
• 用户决定；
• 平台限制（如有）。

5. 决定是否进行 build 前审查

正式的外部审查为可选项，取决于是否有可用工具/能力。

在以下情况推荐进行：

• 涉及 3 个或更多文件的新架构；
• 安全相关改动；
• 公开/缓存路由；
• 关键合约变更。

对于不涉及合约变更的 1–2 个文件的简单调整，推荐不进行。

由用户决定。

如果不具备外部审查能力，不要假装进行过审查；记录 Not available。

如果进行正式审查，遵循 references/retry-and-advisor.md，并将每条意见记录为 APPLIED 或 REBUTTED。

6. 执行每项任务

遵守以下五项不变量：

1. 假设变成问题：遇到实质性歧义 → 提问。
2. 简洁：只做 manifest 要求的内容。
3. 精准修改：除非必要，不重构相邻代码。
4. 先定标准再写代码：编写前明确如何验证。
5. 证据：未执行验证，不得宣称成功。

针对每个条目：

1. 重新阅读所需的最少上下文；
2. 执行 drift detection；
3. 在适用时执行 prompt gate；
4. 仅创建/修改/删除预定路径；
5. 保持现有风格和抽象；
6. 执行增量验证；
7. 记录命令、退出码和相关输出；
8. 只有具备证据时才将任务标记为完成。

每项任务开始前，向学员说明一句话：当前任务（N/M）、将运行什么，以及无需回复——并在 Status 中显示计数器。

不要用 TODO/FIXME 代替需求。

7. 漂移检测

在每个任务开始前执行。

询问：

• 路径或内容是否引入了尚未记录的运行时提示词/大模型？
• 实现是否需要未列出的文件？
• 所需代码是否会改变架构决策？
• 是否出现了范围之外的要求？
• 是否正在重新引入因 YAGNI 而移除的内容？
• 项目的实际约定是否与 DESIGN 冲突？

如果存在漂移：

• 停止受影响的任务；
• 说明差异；
• 向用户提供选项；
• 如果变更具有实质性，先更新规范；
• 在 BUILD_REPORT 中记录该事件。

绝不要在代码中默默“消化”漂移。

8. 大模型提示词门禁

在以下情况下阅读 references/llm-prompt-gate.md：

• LLM Prompts: true；或
• 漂移检测发现运行时提示词/大模型。

不要臆造 Design 本应已确定的 provider、model、最终 prompt 或 output schema。

如果 DESIGN 要求使用 prompt engineering 或 loop-specification 技能，而该技能不可用：

• 不要临时编造提示词；
• 询问并记录此依赖；
• 仅阻塞受影响的大模型任务。

9. 重试阶梯

任务验证失败时，使用 references/retry-and-advisor.md：

• 第一次失败：如果是局部或简单错误，在同一上下文中修复；
• 第二次失败：作为新任务重新执行，不带入之前的假设，仅使用失败的标准、错误信息和必要输入；
• 第三次失败：停止并记录阻塞项；不要绕过该标准。

如果平台不支持在全新上下文中重新执行：

• 使用最少上下文模拟 FIX brief；
• 说明这一限制；
• 不要假装创建了新上下文。

10. 增量验证

使用针对任务最具体的实际命令，例如：

• 对应的单元测试；
• 模块类型检查；
• 文件 lint；
• import/compile 检查；
• 本地 smoke 测试。

不要臆造命令。 如果不存在可用命令，仅当项目或 Design 有依据时才推导出可观察的验证方法；否则应询问。

逐项记录结果。

11. 在数据库中应用 migration

仅当 File Manifest 包含 migration（*.sql、migrations/ 目录，或操作说明为 migration）时才执行。 没有 migration 时，跳过且不要提及数据库。

阅读 references/aplicar-migration.md——完整流程都在其中。规则概述如下：

1. **无需询问即可查明：**工具（PATH 中的 Supabase CLI · 会话中的 Supabase MCP · 无工具 ⇒ 手动使用 SQL Editor）、关联的项目（supabase/.temp/project-ref、.env、项目列表——config.toml 中的 project_id 是本地名称，不是 ref）、本地数据库还是远程数据库。
2. **项目不一致时先暂停一切：**如果文件指向一个项目，而 CLI/MCP 连接到另一个项目，请展示两者（名称和 ref），在学员选择之前不要应用任何内容。
3. **只确认一次：**确认内容必须包含项目名称和 ref、所有待处理 migration 的完整 SQL；如果存在破坏性 DDL，或目标是唯一的数据库（生产环境），则须突出警告。
4. 在 Verify Gate 之前应用——每次只执行一步：应用、读取结果、验证，然后才能进入门禁。
5. 通过读取进行验证（information_schema、pg_proc、pg_policies、migration list）；命令退出码为 0 不构成验证。已应用的 migration 不得重复应用——应记录为“已于 <日期> 应用”。
6. **记录：**在 sdd/ambiente.md 中添加 - banco: 键，并在 BUILD_REPORT 中添加 ## Migrations aplicadas 一节（当 Files Changed 列出 .sql/migrations/ 时，验证器会要求该节）。

绝不要为了绕过服务器的确认（declined）而重写 migration；绝不要应用学员尚未查看过的 SQL。

12. 运行阻塞式 Verify Gate

阅读 references/verify-gate.md。

DEFINE 的 Verify Gate 是权威依据。运行前，用一句话告诉学员将运行什么，并说明无需回复。

仅当 gate 的 cmd 是真实、安全且可用的命令时才运行，并根据 pass_when 评估：

• exit 0（常见情况）：0 表示 green → 继续；任何其他代码（包括 pytest 的 4 和 5）都表示 red → Build 不能完成；修复代码并重试；
• exit N 或 contains: TEXT：只有退出代码匹配，或输出中包含该文本时才是 green；否则为 red；
• 输出表明工具未运行（找不到命令、缺少依赖）：结果不确定 → 解决工具/基础设施问题；不得标记为 green；
• kind: manual-ux（cmd: "N/A (manual-ux)"）：展示检查清单并等待人工确认凭据。

结果为 red 或不确定时，绝不可宣告成功。 对于 manual-ux，报告必须注明：验证人、日期和结果。 自动 runner 有自己的退出代码约定，属于 SpecGate/sdd-open — 参见 references/verify-gate.md；原始 cmd 的退出代码不遵循该表。 如果 manifest 中包含 migration，在排查其他原因之前，red 和不确定都应首先假设：migration 尚未应用，或已应用到其他项目 — 先通过阅读第 11 节重新验证，再修改代码。

13. 补充验证

完成 gate 后，在已配置的情况下运行：

• lint；
• typecheck；
• 相关 test suite；
• build/compile；
• gate 未覆盖的 smoke 检查。

这些检查用于补充，不能替代 Verify Gate。

如果补充验证失败，在解决问题或明确标记 blocker 前，Build 仍未完成。

14. Build 后审查

如果有可用的外部工具，以下情况建议进行 Build 后审查：

• 修改了安全相关内容；
• 修改了公开路由/缓存路由；
• 跨文件逻辑较为微妙；
• 使用了 ralph/briefs 模式。

微小修复不建议审查。

如果发现问题：

• 接受前先在代码中核实 HIGH/MED 级问题；
• 将每条备注记录为 APPLIED/REBUTTED；
• 应用 HIGH 级问题后，重新运行 Verify Gate。

15. 生成 BUILD_REPORT

使用 assets/BUILD_REPORT_TEMPLATE.md 作为报告唯一的结构来源。

报告必须以已执行的证据为依据，不能把估算写成事实。

包含：

• metadata 和来源；
• Mode Selection；
• summary；
• task execution；
• 创建/修改/删除的文件；
• 已应用的 migrations（当 manifest 包含 migration 时，注明文件、项目名称和 ref、日期/时间、读取验证凭据）；
• 适用时生成/重构的 prompts；
• drift；
• Verification Results；
• Verify Gate receipt；
• Acceptance Test Verification；
• 进行过审查时的 Advisor Ledger；
• issues/deviations/blockers；
• Final Status。

如果 Build 受阻：

• 使用 Status: Blocked；
• 不得将 Release 交接内容作为已完成内容插入；
• 说明解除阻塞所需的操作。

如果已完成：

• 使用 Status: Complete；
• Final Status 使用 COMPLETE；
• 插入标准最终章节。

16. 验证 BUILD_REPORT

运行：

python scripts/validate_build_report.py <caminho-do-BUILD_REPORT.md>

该脚本会验证报告的结构和基本一致性。

交付前修复所有错误。

17. 保存 outputs

代码：

• 保存到 File Manifest 中的 paths。

报告：

保存位置。 将报告写入项目根目录下的 sdd/ — 文件夹对所有 Agent 均可见且位置一致。如果项目已有 .claude/sdd/，则继续使用该目录。五个阶段的文档并排存放，不建子文件夹。

• 保存为 sdd/BUILD_REPORT_{FEATURE}.md；
• 如果项目已使用 .claude/sdd/（包括其中已有 reports/ 的情况），则遵循现有结构。

未经告知用户，不得覆盖历史产物。

完成质量门槛

在声明 Build 完成之前：

• 已阅读 Brainstorm。
• 已阅读 DEFINE。
• 已阅读 DESIGN。
• 可访问并已修改真实项目。
• 已选择并记录用户选择的模式。
• 已处理 File Manifest 中的所有项目。
• 未经明确决定，未修改 manifest 之外的内容。
• 已记录 Drift。
• 已执行增量验证并提供证据。
• 已遵守 Retry ladder。
• LLM Prompts=true 的 inventory 中每个项目都有 receipt。
• 未将安全项目委派给低成本 worker。
• 含 migration 的 Manifest：已由学员确认项目（名称和 ref）并应用 migration，或已记录为已应用。
• 含 migration 的 Manifest：提供读取证明，并在报告中包含 ## Migrations aplicadas 章节。
• 含 migration 的 Manifest：已在 sdd/ambiente.md 中写入键 - banco:。
• Verify Gate 为 green（0），或 manual-ux 有人工 receipt。
• 适用的补充检查均已通过。
• Acceptance Tests 有证据。
• Advisor findings（如有）均已标记为 APPLIED/REBUTTED。
• 未使用 TODO/FIXME 作为待完成的实现。
• 已通过 asset 生成 BUILD_REPORT。
• validate_build_report.py 已通过。
• 完整的 Next Step 仅包含 Execute o **SDD Handoff by RDD**.

完整 Build 的交接

完整 BUILD_REPORT 的最后一节必须恰好为：

## Next Step

Execute o **SDD Handoff by RDD**.

此文本后不得添加 slash command、路径、上传说明、对 GPT/Skill 的提及或并行任务。

---

摘自 SDD Open by RDD — https://github.com/robertodiasduarte/sdd-open