Sdd

SDD 五步流程

详设文档 → feature 清单与 spec 规范 → 代码 → 本地场景验证 → 复盘。

①解析 ──→ ②规范 ──→ ③实现(逐功能循环)──→ ④测试 ──→ ⑤复盘
        清单确认          spec确认                交付确认(每个功能)

铁律:先看状态,再行动

每次会话/每轮工作开始,第一条命令永远是:

python <本skill目录>/scripts/sdd_state.py <specs目录> state

它输出状态机 JSON:每个 feature 的状态、下一动作(nextAction)、整条流水线的下一步(pipelineNext)、未关闭的高阻塞 Q。你该做什么以 state 的报数为准,不靠记忆和推断。按报数跳对应手册:

编号速查(数据里会出现的字母)

命令速查

python scripts/sdd_state.py <specs> state                       # 状态机报数(永远第一条)
python scripts/sdd_state.py <specs> ready                       # 就绪探测:现在能派发谁(事件驱动)
python scripts/sdd.py <specs> --stage env                       # 环境预检:工具链/网络/端口(放行前必跑,无 MISS)
python scripts/sdd.py <specs> --stage parse                     # ①解析对账
python scripts/sdd.py <specs> --stage list --strict             # ①清单确认检查(建议 --strict)
python scripts/sdd_state.py <specs> approve-list --by <谁>       # ①清单确认回写
python scripts/sdd.py <specs> --stage spec  --strict            # ②spec 确认检查
python scripts/sdd.py <specs> --set-status <F> --status 已确认 --by <谁>   # ②spec 回写
python scripts/sdd.py <specs> --stage start --strict            # ②开工放行
python scripts/sdd.py <specs> --stage begin <F>                 # ③开工登记
python scripts/sdd.py <specs> --stage deliver <F>               # ③交付自查
python scripts/sdd.py <specs> --stage report <F>                # ③交付确认呈报(自动生成)
python scripts/sdd.py <specs> --stage set-status <F> --status 实现中|已交付 --by <谁>
python scripts/sdd.py <specs> --stage done                      # ④收尾检查

功能状态值只有四个:草案 → 已确认 → 实现中 → 已交付。

总控规则(全程生效,各手册不得违反)

1. 门口检查由脚本守门:推进前必须跑对应 --stage 全绿;确认类检查建议带 --strict。脚本红着找用户视为违规。
2. spec 是唯一依据:实现只读 spec.md/json + openapi.yaml + constitution.md + guard-tests-setup.md,禁止翻详设另起炉灶;详设里 spec 没吸收的内容不许出现在代码里。
3. 禁止编造:spec 没写清的业务逻辑登记 Q(open-questions.json),产物与代码中以 [Q编号] 占位;字段口径偏离详设必须登记 Q 留痕(三部曲:详设定口径→spec 引用→迁移落地)。
4. 产物边界:只写 specs/ 下文件;唯一例外守卫测试落地源码树,须用户同意。
5. 规则落点留痕:每条 R 编号至少一处 F<xxx>-R<n> 标注贴在实现的代码旁;编译/测试必须实跑并记录退出码。
6. 并行分级:派发节奏与冲突契约以 step3「事件驱动派发」为唯一口径(ready 探测即就即派);并行数量按候选 feature 两两比对 tables[] 交集与改动目录定级——无交集且目录不重叠可 3~4 个并行;目录重叠最多 2 个;共享表串行。worktree 并行按 references/parallel-worktrees.md 纪律执行(common 先串行 install 一次、副本禁 install/禁起服务/禁连库)。
7. 委托模式:specs/_work/gate-delegation.json 存在时,各确认点按其配置由 AI 自裁或呈报不阻塞;自裁结论必须追加 specs/_work/gate-decisions.md,不落档视同未确认。 开工前主动询问:首次解析前,若开关文件不存在,必须向用户说明并询问是否开启。询问话术要点——

   「是否开启委托模式?开启后:清单确认、各批 spec 确认、交付确认这些流程关口不再停下来等你,由 AI 按规范自行裁决,但每一次自裁都会落档到 gate-decisions.md 供你事后追溯;未决技术取舍也会先做再登记留痕。以下五类情况仍会无条件停下等你:高阻塞问题待裁决、spec 与详设/现有代码矛盾、同一问题修 3 轮仍不收敛、守卫挡路且实现没错、其他 AI 无权拍板的事项。不开则每个关口都会等你确认,节奏慢但步步可控。」 用户明确同意后才创建开关文件;拒绝或未表态则全程走人工确认。 中途开启/关闭均可:开关即文件存不存在,任何时候用户说"开启委托"即创建文件、自下一个关口起生效(此前已人工确认的记录不追溯重裁);说"关闭委托"即删文件、自下个关口恢复人工确认。用户中途说出意图类表述(如"后面不用问我了""接下来的你自己定")时,AI 应确认一句"是否即开启委托模式"后照此办理。

8. 委托红线(不可自裁):高阻塞 Q 待裁决、spec 与详设/现有代码矛盾、评审同一问题 3 轮仍报、测试同一问题修 3 次仍红、守卫挡路且实现没错——五类一律停,呈用户裁决。
9. 双文件纪律:有 json twin 的产物先写 json 再派生 md,脚本做同源校验;状态回写一律走命令(hook 会拦截手工改 status)。
10. 过程目录:specs/_work/ 是过程件家(计划、抽取件、日志、委托档),开工放行前不得删除,完成后保留追溯。

目录

• references/step1~5-*.md — 五步手册,细则只在手册里,本文件不重复
• references/pipeline-philosophy.md — 流水线编排思想说明(非操作指导):质量/顺序/并行/红线的机制分工
• references/guard-tests.md、implementation-rules.md、parallel-worktrees.md — 守卫/实现/并行三份参考
• references/casebook.md — 事故案例库:手册与报错文案里的"先例 Qxxx/案例"指针都指到这里;新增案例须同时指认催生的机制条目
• scripts/sdd.py — 守门引擎;scripts/sdd_state.py — 状态机;schemas/、templates/ — 机器 twin 与模板
• 过程件契约(无 schema 的三个):templates/gate-delegation.template.json(委托开关)、templates/q-range-lock.template.json(并行 Q 编号锁)、templates/pipeline.template.json(并行派发表);均落 specs/_work/
• templates/detail-design.example.json — 详设输入格式示例(真实取值,禁止照抄);填写规则见 templates/detail-design.template.md

适用范围与环境依赖

• 守门引擎与状态机栈无关(只依赖文件契约);守卫参考(guard-tests.md)与章程模板以 Spring Boot 单体/微服务 + Vue3 为基线,其他栈替换这两份即可,流程与脚本不动
• "确定性纪律由 hook 强制"依赖项目 .claude/hooks/ 下的 sdd 三件套;复制本 skill 到其他仓库时需一并携带,未装时状态回写纪律降级为自觉遵守