SuperAPI AI 工具集

design

编程与开发

查看项目

更新于 10-17 16:13

技能介绍

用途:将已保存且状态为 validated 的 PRD 转化为同样经过验证的技术设计文档,为后续规划步骤提供输入。技能不修改生产代码,也不做提交,只读取仓库以保留现有接口、约束、约定和验证接缝。

输入要求:需要一份 artifact 为 prd、status 为 validated 的 PRD,完整读取并收集所有 FR-、NFR-、AC-* 标识,所有 Q-* 条目及其负责人,被否决的选项及其出处(如有),以及仓库假设和 PRD 基线。在设计的 frontmatter 中记录该 PRD 文件的 SHA-256 哈希。遇到未解决的用户负责问题即停止;设计负责的问题以 ADR 形式解决。若设计过程中暴露出新的产品需求,赋予临时 FR-D* 标识、记录缺口并请用户修订 PRD,而不是悄悄改变范围;在所有 FR-D* 被纳入 PRD 并具备正常验收追踪或从设计中移除之前,不得验证设计。需重新检查仓库证据,若重大漂移与已验证 PRD 矛盾,应展示证据并先询问用户。

产物与流程:使用 assets/design-spec-template.md,保存到 docs/agentic-engineering/specs/<YYYY-MM-DD>/<subject>.md。若存在匹配草稿,先提供续写选项,并在续写前比对当前精确文件的 PRD SHA-256 与 prd_sha256。初始文档以 status: draft、checkpoint: scope 保存。检查点依次为 scope、contracts、behavior、decisions、traceability、awaiting-validation、complete。写入失败时报告并停止。验证前再次比对 PRD 与 prd_sha256,不匹配或仍有 FR-D* 即停止。以 checkpoint: awaiting-validation 呈现完整草稿及 ADR 决策,按请求修改直至批准,然后设为 status: validated、checkpoint: complete。不得静默覆盖已验证设计;PRD 修订后设计变为过期,需重新检查范围与追踪。

章节规则:按 Scope → Design Rules → Contracts → Architecture → Components → Behavior → Failure Model → ADRs → Traceability → Deferred 顺序填写模板。先定义契约再定义组件,组件消费或产出具名契约而非自行解释共享数据。范围与 PRD 联动需列出全部 FR-、NFR-、AC-,明确未覆盖或临时需求。设计规则写四到六条按优先级排序、源自 NFR 的取舍规则,仅保留实现者无需解释即可应用的规则。契约定义外部共享的 schema、格式、接口、版本、归属与不变量,每个契约只有一个写入方。架构概览用一个简单图并命名组件及其间契约。组件设计说明功能、刻意不做的功能以及外部有意义的接口,仅命令行接口需包含退出码。行为描述重要流程与状态转换,仅在存在相关持久写入时包含写入顺序与突然停止恢复。失败模型覆盖与本系统相关的失败、检测器、响应与验证标识,不为不存在这些问题的系统编造可选依赖、损坏路径或持久化失败。ADR 解决每个设计负责的 Q- 及每个新的重要技术选择,记录背景、选项、决策、理由与接受的后果;涉及产品范围、公共兼容性、安全策略、成本或不可逆数据行为的决策须先询问用户。追踪与验证映射将每个 FR-、NFR-、AC-* 映射到设计章节与可观测验证,每个 F-* 也需对应验证行。延期与范围外记录延期项及将其提升的触发条件。

自检:验证前确保每个 FR-、NFR-、AC-* 均出现在范围与追踪中;无残留 FR-D*;每个设计负责的 Q-* 均有 ADR 且无用户负责问题残留;每个契约有唯一写入方、版本与不变量;每个组件有刻意不做的功能;适用的持久写入对具备可恢复顺序分析;每个相关失败有可观测验证行;每个设计元素可追溯到需求、验收标准、失败或既定仓库约束;仓库与技术选择属于既有约束或已记录决策;除用户要求标准英语外,行文遵循 STE 规则。

下游契约:to-plan 消费已验证设计及关联的已验证 PRD,必须把每个 FR-、NFR-、AC-* 带入可独立验证的实现任务。

限制:不修改生产代码、不做提交;不替代 PRD 修订;遇到未解决的用户负责问题、PRD 哈希不匹配或残留临时需求时停止。