SuperAPI AI 工具集

spec-driven-implementation

编程与开发

查看项目

更新于 10-16 06:15

技能介绍

用途:用于需要书面规格才能提升实现质量、减少歧义或便于评审的较大功能。需务实判断,并非所有改动都需要规格。

规格位置:通常存放于 specs/<linear-ticket-number>/PRODUCT.md 与 specs/<linear-ticket-number>/TECH.md,例如 specs/APP-1234/PRODUCT.md。specs/ 下只允许以工单命名的目录作为直接子项,不得创建以工程师或功能 slug 命名的子目录。若相关 Linear 问题不存在,须先创建,可使用 Linear MCP 工具:list_teams 查找团队、list_issue_labels 查看标签、save_issue 创建问题;团队或标签不明确时用 ask_user_question 澄清,而非猜测。规格主要由智能体编写并提交到源码控制,便于评审并随代码更新。

何时需要:产品/架构歧义、预计实现规模约 1k+ LOC、深度或跨栈改动、回归代价高的风险行为变更、更清晰输入能显著提升智能体质量的工作。小型局部修复、简单重构、歧义少的 UI 微调通常无需。纯 UI 改动常只需产品规格,技术规格可能不必。

工作流:1) 判断是否需要规格;2) 先写产品规格 PRODUCT.md,使用 write-product-spec 技能,定义问题、期望体验、不变量与边界情况、成功标准、验证方式;有 UI/交互设计时索取 Figma 稿,无稿则继续但须在产品规格中明确指出;引用 Linear 问题;3) 在需要时用 write-tech-spec 写技术规格,适用于跨多个子系统、架构或可扩展性重要、存在重要权衡、审阅计划优于审阅原始代码的情况;可先做 e2e 原型再写技术规格;4) 规格获批后用 implement-specs 依据 PRODUCT.md 与 TECH.md 实现;实现常可与产品和技术规格放同一 PR,迭代期间保持规格、代码、测试同 PR;大型功能可选提供 PROJECT_LOG.md 与 DECISIONS.md,但非必需;5) 实现中若偏离规格须更新规格,用户行为、成功标准、UX 细节变化更新 PRODUCT.md,实现方式、架构边界、风险依赖或验证计划变化更新 TECH.md,检入的规格应描述实际发布的功能;6) 完成前对照规格验证,优先采用符合仓库惯例的单元测试与回归覆盖、关键用户流的集成测试、loom 走查或等价演示,UI 较重时可附截图或视频。

最佳实践:务实为上;规格用于提升智能体输入质量而非仪式;产品规格重行为、轻实现,技术规格重实现并贴合当前代码库模式;评审时间用于验证规格与行为,而非过度关注代码风格。相关技能:implement-specs、write-product-spec、write-tech-spec。