Apostle Sdd

SDD工作流

本skill基于apostle-artifacts-loops：继承其"文档先行"原则，基于Spec-Driven Development规范。为一个组件写代码前先发散思考，再为这个组件按要求写一份独立的SPEC.md，便于用户理解和后期维护。

零引用：本 SKILL.md 即全部内容，不附带任何参考文件、脚本或模板；SPEC.md属于项目工作区，请你按代码结构整理文档结构。

动笔之前先确保项目文档在你的上下文中：AGENTS.md、权威文档（如 "CONTEXT.md"、 "ARCHITECTURE.md"）、ADR、相邻模块的文档与代码，沿用其中的词汇与约定。

你应用 "组件名+SPEC.md" 防止同一目录下有过多SPEC.md无法区分，你只应为项目中需合并的代码（即不需要为测试、prototype和demo等）编写SPEC.md，并在实现有SPEC.md的代码时只在必要时写极简风的注释。

当你工作涉及的代码存在现有的SPEC.md时应先完整读一遍，优化、增减改动和debug都应先修改SPEC.md再写代码。

执行纪律

• SPEC.md写完再写代码；代码实现必须不多不少地遵守SPEC.md，偏离时要么改代码，要么先更新SPEC.md并说明原因。
• 代码完成时对照SPEC.md自查：每一步的实现应当符合文档中的决策理由，发现更优做法先和用户更新文档。
• 代码完成时按SPEC.md的测试章节验证并简要记录结果。
• 完成时对照"文档同步"节，提醒用户更新所有列出的文档，把实际验证结果写清楚。
• 如果你遇到了必须由用户审核或澄清的部分，请你交付SPEC.md或代码后停下来用用户喜欢的表达方式与其对齐。

SPEC.md的章节顺序

SPEC.md须用数字列表与下方所列顺序同步，采用精准、清晰、易读的风格和多级标题等进行结构化创作：

1. 需求拆解——精确定位需求，把它拆成可独立完成、可独立验收的最小单元。
2. 验收标准——穷举每个单元可观察、可检验的完成定义并排列为完整的清单，确保基于清单可以完成测试编写和功能验收。
3. 假设与歧义——列出需求中的歧义点与你的假设，优先在权威信源一节查证。
4. 现状分析——若涉及现有代码，先做分析：一手看代码逻辑，一手看时间、内存等性能表现。
5. 权威信源——尽可能引用官方文档或项目文档等权威信源，确认设计意图、沿用相同的概念与风格，并确定精确的变量名和所需引用的内容，链接相关文档。
6. 命名统一——模块、类型与变量的命名沿用项目词汇表与领域文档，不自造同义词。
7. 模块边界——清晰划分模块边界、依赖关系与数据流。
8. 接口先行——先设计公开接口与类型签名，用类型让非法状态不可表示，而不是靠运行时检查兜底。
9. 工作流程——自上而下地分析这个模块从入口到出口的完整工作流程。
10. 实现逻辑——按开发工作流把实现分成几步，逐步解释每步要做什么、为什么这样做：关键决策与权衡、复杂度与性能考量、为何优于替代方案，让读者能据此判断代码质量。
11. 边界枚举——枚举极端输入、异常路径与并发冲突。
12. 错误处理——定义每类错误的处理策略：谁捕获、如何传播、以什么形式呈现给调用方或用户。
13. 依赖选型——引入任何新的外部依赖，说明选型理由、替代方案与维护成本。
14. 硬编码声明——如果要硬编码任何内容，解释其意图和后续影响。
15. 影响面——列出本次改动会波及的调用方、数据与配置，标注需要回归验证的路径。
16. 测试与约束——列出这个模块正常运行需要哪些测试，以及必须满足的约束。
17. 文档同步——列出完成后必须同步修改的文档，确保后续修改人员可以方便理解且不会遗漏需要修改的代码。