AI Skills
spec-driven-implementation

spec-driven-implementation

热门

驱动以规范为先的工作流程，用于实现重要功能：在实现前编写 PRODUCT.md，必要时编写 TECH.md，并在实现过程中保持两份规范更新。适用于开始一个重大功能、规划由智能体驱动的实现，或用户希望将产品和技术规范纳入版本控制时使用。

124Star
0Fork
更新于 2026/7/10
获取 Skill源代码

相关 Skills

design11万algorithmic-art15万frontend-ui-engineering7.7万
SKILL.md
readonly只读
name
spec-driven-implementation
description

驱动以规范为先的工作流程，用于实现重要功能：在实现前编写 PRODUCT.md，必要时编写 TECH.md，并在实现过程中保持两份规范更新。适用于开始一个重大功能、规划由智能体驱动的实现，或用户希望将产品和技术规范纳入版本控制时使用。

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/ 目录下应仅包含以工单命名的子目录作为直接子项。不要在其中创建以工程师命名的子目录或功能别名目录。

如果相关的 Linear 问题尚不存在，请在编写规范前创建一个。直接使用 Linear MCP 工具：

  • list_teams 查找合适的团队
  • list_issue_labels 检查预期的标签/标记
  • save_issue 使用合适的团队和标签创建问题

如果从请求和上下文无法明确合适的团队或标签，请使用 ask_user_question 进行澄清，而不是猜测。

这些规范应主要由智能体编写，而非手动编写，并且应纳入版本控制，以便审查并与代码保持同步。

何时需要规范

当变更重大时，强烈建议使用规范，例如：

  • 产品或架构存在歧义
  • 预期实现规模约 1k+ 行代码
  • 涉及深层或跨栈的变更
  • 风险较高的行为变更，回归成本高
  • 更清晰的输入将显著提升智能体质量的工作

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

  • 小型、局部的错误修复
  • 直接的重构
  • 歧义较少的简单 UI 调整

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

工作流程

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

评估功能的规模、歧义和风险。如果规范不会显著改善执行或审查，则跳过，专注于验证。

2. 首先编写产品规范

在实现之前，创建 PRODUCT.md 描述期望的用户面向行为。

使用 write-product-spec 技能生成。产品规范应定义：

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

如果功能涉及 UI 或交互设计，询问是否存在 Figma 原型。如果没有原型，继续但需在产品规范中明确说明。

当存在 Linear 问题时，在规范中引用它。由于规范存放在 specs/<linear-ticket-number>/... 下，这通常很直接。

3. 在必要时编写技术规范

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

以下情况优先使用技术规范：

  • 实现涉及多个子系统
  • 架构或可扩展性重要
  • 存在需要记录的重要权衡
  • 审查者从审查计划中获益多于原始代码

如果端到端原型能带来更准确的实现计划，可以在原型之后编写技术规范。当实现细节仍过于不确定时，不要强行提前编写技术规范。

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 密集型工作，使用截图或视频

最佳实践

  • 务实高于一切。
  • 编写规范是为了提高智能体的输入质量，而非形式主义。
  • 保持产品规范面向行为，少涉及实现细节。
  • 保持技术规范面向实现，并基于当前代码库模式。
  • 当规范引用相关代码块时，尽可能在文件引用中包含检查的提交 SHA，并将引用链接到 GitHub 的精确 blob/<sha>/...#Lx-Ly 行。
  • 利用审查时间验证规范和行为，而非过度关注代码风格细节。

相关技能

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