SuperAPI AI 工具集

write-product-spec

编程与开发

查看项目

更新于 10-16 07:17

技能介绍

用途:为 Warp 中重要的用户可见功能撰写 PRODUCT.md 产品规格,使目标行为足够明确,便于代理正确实现并避免回归。规格纯粹从使用者视角描述:看到什么、做什么、体验到什么,以及必须保持的不变量;不写实现细节(内部类型、状态布局、模块边界、数据流、算法)。这里的“使用者”不限于 Warp 终端用户:UI/UX 功能指使用 Warp 的人;数据模型指读写该模型的代码;API、协议或库指调用方(其他服务、客户端代码、插件或代理);CLI 或面向开发者的界面指调用它的开发者。

主要能力:产出分两阶段,第一步写 PRODUCT.md,第二步由 write-tech-spec 生成同一功能的 TECH.md;产品规格应写到能直接据此撰写技术规格。文件路径为 specs/<id>/PRODUCT.md,<id> 可为 Linear 工单号(如 specs/APP-1234/PRODUCT.md)、加 gh- 前缀的 GitHub issue id(如 specs/gh-4567/PRODUCT.md)或短横线命名的小写功能名(如 specs/vertical-tabs-hover-sidecar/PRODUCT.md);specs/ 下只能有以 id 命名的目录作为直接子项。工单/issue 引用可选,若用户没有则询问功能名作为目录;仅当用户明确要求时才用 Linear MCP 或 gh CLI 新建工单。

结构:必需 Summary(1–3 句)与 Behavior(核心,穷尽式英文行为描述,写成编号、可测试的不变量);可选 Problem、Goals/Non-goals、Figma、Open questions,无内容则整段省略,不写“None”占位。不包含 Validation、Success criteria 或 Testing,验证与测试计划归 TECH.md。若功能有 UI 或交互设计,起草 Behavior 前应询问是否存在 Figma 稿并附链接(Figma: <链接>)或明确写 Figma: none provided;纯后端功能跳过并省略该节。

使用方式与限制:写作前只收集必要上下文(目录 id、功能摘要、目标用户、关键行为、边界情况、验证方式),缺失时用 ask_user_question 询问而非猜测。Behavior 应覆盖默认行为与正常流程、所有可见状态及转换、全部输入与响应、空/错误/加载/取消状态、易被忽略的边界(权限拒绝、离线、超时、状态竞态、多实例、陈旧或缺失数据、交互中失焦、与相邻功能的交互)、键盘与无障碍和焦点预期、必须始终保持的不变量。规模上,微小改动不写规格;小功能约 30–60 行,中型约 80–150 行,复杂功能篇幅更长,且大部分应集中在 Behavior。实现演变时,若面向用户的行为或 UX 细节变化,应在同一 PR 中更新 PRODUCT.md;大型功能可选维护 DECISIONS.md。相关技能:implement-specs、write-tech-spec、spec-driven-implementation。