用途:用于规模较大、存在产品/架构歧义或回归风险较高的功能,通过先写规格提升实现质量、减少含糊并便于评审。小型局部修复、直接重构和无歧义的界面微调通常无需规格;纯界面改动往往只需产品规格。
规格位置:specs/<linear-ticket-number>/PRODUCT.md 与 specs/<linear-ticket-number>/TECH.md,例如 specs/APP-1234/PRODUCT.md。specs/ 下只能有以工单编号命名的直接子目录,不要建工程师名或功能名目录。若尚无相关 Linear 工单,先用 Linear MCP 工具 list_teams、list_issue_labels、save_issue 创建;团队或标签不明确时用 ask_user_question 澄清。规格应主要由智能体撰写并纳入版本控制。
流程:先写产品规格,使用 write-product-spec 技能,说明要解决的问题、期望用户体验、不变量与边界情况、成功标准及验证方式;有界面设计时索取 Figma 稿,没有则在规格中明确说明。实现跨度大、架构重要或有取舍时,用 write-tech-spec 技能写技术规格;也可在端到端原型后再写。规格获批后用 implement-specs 技能实现,实现常与规格放在同一 PR 中。大型功能可选提供 PROJECT_LOG.md 记录探索路径与检查点,DECISIONS.md 记录决策。
保持更新与验证:用户行为、成功标准、体验细节变化时更新 PRODUCT.md;实现方式、架构边界、风险依赖、测试计划变化时更新 TECH.md,尽量与代码改动同 PR。完成前用单元测试、回归测试、关键流程集成测试以及演示、截图或视频等验证产品行为,并映射回规格。
限制:资料未提供收费、价格、平台或效果信息;规格本身不是必做的仪式,需按规模与风险务实取舍。