spec-driven-implementation

spec-driven-implementation

在 Warp 中采用规格优先的工作流来推进重要功能。

概述

对于重要功能，如果编写规格有助于提升实现质量、减少歧义或简化评审，请使用此技能。务必务实：并非每项变更都需要规格。

规格通常应放在以下位置：

• specs/<linear-ticket-number>/PRODUCT.md
• specs/<linear-ticket-number>/TECH.md

例如：

• specs/APP-1234/PRODUCT.md
• specs/APP-1234/TECH.md

specs/ 的直接子项只能是以工单命名的目录。不要在其中创建以工程师姓名或功能 slug 命名的子目录。

如果尚无相关的 Linear issue，请先创建一个，再编写规格。直接使用 Linear MCP 工具：

• 使用 list_teams 查找合适的团队
• 使用 list_issue_labels 查看预期的标签
• 使用 save_issue 创建 issue，并设置合适的团队和标签

如果无法根据请求和上下文判断正确的团队或标签，请使用 ask_user_question 澄清，而不要猜测。

这些规格应主要由 Agent 编写，而不是手动编写，并且应提交到源代码管理中，以便评审并与代码保持同步。

何时需要规格

对于重要变更，应优先考虑编写规格，例如：

• 产品或架构存在歧义
• 预计实现规模约为 1k+ LOC
• 深层或跨领域的技术栈变更
• 回归代价高昂的高风险行为变更
• 输入更清晰后，Agent 的工作质量会显著提升

以下情况通常不需要规格：

• 范围小且局部的 bug 修复
• 直接明了的重构
• 歧义很少的局部 UI 调整

对于纯 UI 变更，产品规格通常很有用，而技术规格可能没有必要。

工作流

1. 判断功能是否需要规格

评估功能的规模、歧义和风险。如果规格无法显著改善执行或评审流程，就跳过规格，专注于验证。

2. 首先编写产品规格

开始实现前，创建 PRODUCT.md，描述面向用户的预期行为。

使用 write-product-spec 技能编写产品规格。产品规格应明确：

• 要解决的问题
• 期望的用户体验
• 不变量和边缘情况
• 成功标准
• 如何验证该行为

如果功能包含 UI 或交互设计，请询问是否有 Figma 设计稿。如果没有设计稿，可以继续，但要在产品规格中明确说明。

如果存在 Linear issue，请在规格中引用。由于规格位于 specs/<linear-ticket-number>/... 下，通常很容易引用。

3. 适时编写技术规格

对于重要或存在歧义的实现工作，请使用 write-tech-spec 技能。

以下情况应优先考虑编写技术规格：

• 实现涉及多个子系统
• 架构或可扩展性很重要
• 存在值得记录的权衡
• 评审计划比评审原始代码更有价值

如果先完成 e2e 原型能让实现计划更准确，也可以之后再编写技术规格。当实现细节仍不明确时，不要强行过早编写技术规格。

4. 实现已获批准的规格

规格获批后，使用 implement-specs 技能，根据已批准的 PRODUCT.md 和 TECH.md 进行实现。

实现通常可以与产品规格和技术规格一起提交到同一个 PR 中。工程师迭代时，应将 PRODUCT.md、TECH.md、代码变更和测试都保留在同一个 PR 中，确保评审反映即将实际发布的功能。

对于大型功能，实现者还可以选择提供：

• PROJECT_LOG.md，用于跟踪已探索的路径、检查点和当前实现状态
• DECISIONS.md，用于记录设计和实现过程中做出的具体产品及技术决策

这些都是可选的辅助文档，并非必需产出。

5. 在实现过程中保持规格文档为最新

如果实现与规格文档不一致，请更新规格文档，而不是让其过时。

在以下情况下更新 PRODUCT.md：

• 面向用户的行为发生变化
• 成功标准发生变化
• UX 细节或边缘情况发生变化

在以下情况下更新 TECH.md：

• 实现方案发生变化
• 架构边界发生调整
• 风险、依赖项或发布细节发生变化
• 测试或验证计划发生变化

提交到代码库的规格文档应描述实际发布的功能，而不仅仅是最初的意图。只要条件允许，请在同一个 PR 中一并提交相关代码更改和规格文档更新。

6. 根据规格文档验证行为

在认为工作已完成之前，请确保验证内容与规格文档相对应。优先采用能直接验证产品行为的测试和产物：

• 遵循代码库本地测试惯例的单元测试和回归测试
• 针对关键用户流程的集成测试
• 适用时使用 Loom 演示或同等的功能演示
• 对 UI 工作较多的改动，在有帮助时提供截图或视频

最佳实践

• 务必务实。
• 编写规格文档应提升 Agent 的输入质量，而不是流于形式。
• 产品规格应以行为为导向，尽量少涉及实现细节。
• 技术规格应以实现为导向，并立足于当前代码库的模式。
• 如果规格文档引用了相关代码片段，请尽可能在文件引用中注明已检查的 commit SHA，并将引用链接到精确的 GitHub blob/<sha>/...#Lx-Ly 行。
• 利用审查时间验证规格文档和行为，不要过度纠结代码风格上的小问题。

相关技能

• implement-specs
• write-product-spec
• write-tech-spec