SDD 工作流

DotCraft 以 spec-first 方式构建：协议与跨模块行为先写成规范（spec），实现随后对齐这份规范。需求变化时，先改规范，再让代码回到一致。本页说明为 DotCraft 贡献大型功能时使用的工作流。

工作准则

• 先规范，后代码。 改动 specs/ 中定义的协议设计或跨模块流程时，先更新规范再实现。
• 在规范层面解决冲突。 改动与现有规范冲突时，先在规范层面解决，再动代码。
• 一致性测试对齐规范。 依赖协议的代码带有与规范对齐的测试，偏离会以测试失败的形式暴露。
• 文档跟随行为。 行为变化时，同步更新面向用户的中英文档。
• 规范描述契约而非实现。 规范写"必须为真的事项"，保持足够高层以经受实现迭代。

主规范与里程碑规范

工作流的核心是一份主规范和一组临时里程碑规范之间的版本关联：

• 主规范是完整功能的持久契约，放在 specs/ 下、遵循项目既有的规范格式。行为、架构或工作流要变，先改它。
• 里程碑规范是开发期的拆分产物，默认放在仓库根的 references/ 目录，永不提交。每份都通过元数据表（Version、Status、Date、Parent Spec）关联回主规范，只写该里程碑的目标、边界与验收标准，不写具体实现步骤。

工作流

1. 调研与定界。 先读相关代码、既有规范、测试与历史，厘清目标、成功标准与非目标。重大不确定性要在设计定稿之前解决。
2. 拆分。 起草主规范，从它推导里程碑大纲与各里程碑契约，一并交付评审。评审确认之前不开始实现。
3. 逐个里程碑实现。 每次只做一个：先给出仅针对该里程碑的实现计划，再实现。发现行为需要变化时，修改顺序是主规范 → 未实现的里程碑规范 → 实现计划 → 代码。
4. 验证与验收。 同时对照里程碑规范和主规范检查结果，交付证据并停下等待验收。验收通过才进入下一个里程碑。
5. 合入。 全部里程碑验收后，把持久的最终行为与决策合并回主规范，核对主规范与实现一致，然后删除全部临时里程碑文件。

里程碑是开发期的协调机制，不是产品概念。里程碑编号与阶段叙事不进产品代码、测试、文档和提交信息。

工具

这套工作流由两个官方插件承载，启用后 Agent 会代劳全流程（安装见插件与工具）：dotcraft 插件提供 DotCraft 专属的规范位置与格式约定，harness-workflow 插件的 $feature-workflow 实现上述流程——"规划一个新功能"这类请求会触发它。

参见

• 架构总览——这些规范所描述的运行时。
• 插件与工具——安装并启用 dotcraft 与 harness-workflow。