Back to Details

spec-driven-implementation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

spec-driven-implementation

规格驱动的实现

Drive a spec-first workflow for substantial features in Warp.
针对Warp中的大型功能采用规格先行的工作流。

Overview

概述

Use this skill for significant features where a written spec will improve implementation quality, reduce ambiguity, or make review easier. Be pragmatic: not every change needs specs.
Specs should usually live in:
  • specs/<linear-ticket-number>/PRODUCT.md
  • specs/<linear-ticket-number>/TECH.md
For example:
  • specs/APP-1234/PRODUCT.md
  • specs/APP-1234/TECH.md
specs/
should contain only ticket-named directories as direct children. Do not create engineer-named subdirectories or feature-slug directories there.
If a relevant Linear issue does not already exist, create one before writing specs. Use the Linear MCP tools directly:
  • list_teams
    to find the appropriate team
  • list_issue_labels
    to inspect the expected labels/tags
  • save_issue
    to create the issue with the appropriate team and labels
If the correct team or labels are not obvious from the request and surrounding context, use 
ask_user_question
to clarify rather than guessing.
These specs should largely be written by agents, not by hand, and should be checked into source control so they can be reviewed and kept current with the code.
当开发重要功能时，若书面规格文档能提升实现质量、减少歧义或简化评审流程，可使用此技能。务实判断：并非所有变更都需要规格文档。
规格文档通常应存放于：
  • 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
澄清，切勿猜测。
这些规格文档应主要由Agent编写，而非手动撰写，并需纳入版本控制，以便进行评审并与代码保持同步。

When specs are required

何时需要规格文档

Strongly prefer specs when the change is substantial, such as:
  • product or architectural ambiguity
  • expected implementation size around 1k+ LOC
  • deep or cross-cutting stack changes
  • risky behavior changes where regressions would be expensive
  • work where agent quality will improve materially from clearer inputs
Specs are often unnecessary for:
  • small, local bug fixes
  • straightforward refactors
  • narrow UI tweaks with little ambiguity
For pure UI changes, the product spec is often useful while the tech spec may be unnecessary.
当变更规模较大时，强烈建议编写规格文档，例如：
  • 产品或架构存在歧义
  • 预期实现代码量约1k+ LOC
  • 需要进行深度或跨栈的架构变更
  • 行为变更存在风险，回归修复成本高昂
  • 更清晰的输入能显著提升Agent的工作质量
以下场景通常无需规格文档：
  • 小型局部Bug修复
  • 简单的代码重构
  • 歧义性低的局部UI调整
对于纯UI变更，产品规格文档通常有用，而技术规格文档可能并非必需。

Workflow

工作流程

1. Decide whether the feature needs specs

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

Evaluate the size, ambiguity, and risk of the feature. If specs will not meaningfully improve execution or review, skip them and focus on verification instead.
评估功能的规模、歧义性和风险。若规格文档无法切实提升执行或评审效率，则跳过，专注于验证工作。

2. Write the product spec first

2. 先编写产品规格文档

Before implementation, create 
PRODUCT.md
describing the desired user-facing behavior.
Use the 
write-product-spec
skill to produce it. The product spec should define:
  • what problem is being solved
  • the desired user experience
  • invariants and edge cases
  • success criteria
  • how the behavior will be validated
If the feature has UI or interaction design, ask for a Figma mock if one exists. If there is no mock, continue but call that out explicitly in the product spec.
Reference the Linear issue in the spec when one exists. Because specs live under 
specs/<linear-ticket-number>/...
, this should usually be straightforward.
开发前创建
PRODUCT.md
，描述期望的用户端行为。
使用
write-product-spec
技能生成文档。产品规格文档应明确：
  • 要解决的问题
  • 期望的用户体验
  • 约束条件与边缘场景
  • 成功标准
  • 行为验证方式
若功能涉及UI或交互设计，询问是否存在Figma原型。若无原型，继续编写文档并在产品规格中明确说明这一点。
若存在Linear工单，请在规格文档中引用。由于规格文档存放于
specs/<linear-ticket-number>/...
下，通常可直接关联。

3. Write the tech spec when warranted

3. 必要时编写技术规格文档

Use the 
write-tech-spec
skill for substantial or ambiguous implementation work.
Prefer a tech spec when:
  • the implementation spans multiple subsystems
  • architecture or extensibility matters
  • there are meaningful tradeoffs to document
  • reviewers will benefit more from reviewing the plan than the raw code
It is acceptable to write the tech spec after an e2e prototype if that leads to a more accurate implementation plan. Do not force a premature tech spec when the implementation details are still too uncertain.
对于规模较大或存在歧义的开发工作，使用
write-tech-spec
技能。
在以下场景优先编写技术规格文档：
  • 实现涉及多个子系统
  • 架构或扩展性至关重要
  • 存在需要记录的重大权衡决策
  • 评审人员通过评审计划比直接评审代码获益更多
若先完成端到端原型能制定更准确的实现计划，也可在原型完成后再编写技术规格文档。当实现细节仍不确定时，切勿强行提前编写技术规格。

4. Implement approved specs

4. 根据已批准的规格文档进行开发

After the specs are approved, use the 
implement-specs
skill to build from the approved 
PRODUCT.md
and 
TECH.md
.
The implementation can often be pushed in the same PR as the product and tech specs. As the engineer iterates, keep 
PRODUCT.md
, 
TECH.md
, code changes, and tests in that same PR so the review reflects the feature that will actually ship.
For large features, the implementer may optionally offer:
  • PROJECT_LOG.md
    to track explored paths, checkpoints, and current implementation state
  • DECISIONS.md
    to capture concrete product and technical decisions made during design and implementation
These are optional aids, not required outputs.
规格文档获批后，使用
implement-specs
技能基于已批准的
PRODUCT.md
和
TECH.md
进行开发。
实现代码通常可与产品及技术规格文档提交至同一个PR中。工程师迭代过程中，需将
PRODUCT.md
、
TECH.md
、代码变更及测试放在同一个PR内，确保评审内容与最终交付的功能一致。
对于大型功能，开发者可选择添加：
  • PROJECT_LOG.md
    ：记录探索路径、检查点及当前实现状态
  • DECISIONS.md
    ：记录设计与开发过程中做出的具体产品及技术决策
这些为可选辅助文档，并非必需产出。

5. Keep specs current during implementation

5. 开发过程中持续更新规格文档

If implementation changes from the spec, update the spec rather than leaving it stale.
Update 
PRODUCT.md
when:
  • user-facing behavior changes
  • success criteria change
  • UX details or edge cases change
Update 
TECH.md
when:
  • the implementation approach changes
  • architectural boundaries move
  • risks, dependencies, or rollout details change
  • the testing or validation plan changes
The checked-in specs should describe the feature that actually ships, not just the initial intent. Keep those spec updates in the same PR as the related code changes whenever practical.
若实现与规格文档不符，请更新规格文档，避免其过时。
出现以下情况时更新
PRODUCT.md
：
  • 用户端行为变更
  • 成功标准变更
  • UX细节或边缘场景变更
出现以下情况时更新
TECH.md
：
  • 实现方案变更
  • 架构边界调整
  • 风险、依赖或发布细节变更
  • 测试或验证计划变更
已提交的规格文档应描述最终交付的功能，而非仅初始设想。只要可行，规格文档的更新应与相关代码变更提交至同一个PR中。

6. Verify behavior against the spec

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

Before considering the work complete, make sure verification maps back to the specs. Prefer tests and artifacts that validate the product behavior directly:
  • unit tests and regression coverage that follow the repository's local testing conventions
  • integration tests for critical user flows
  • loom walkthroughs or equivalent feature demonstrations when appropriate
  • screenshots or videos when useful for UI-heavy work
在完成工作前，确保验证工作与规格文档一致。优先采用直接验证产品行为的测试及成果：
  • 遵循仓库本地测试规范的单元测试与回归覆盖
  • 针对关键用户流程的集成测试
  • 必要时使用loom演示或等效的功能展示
  • 对于UI密集型工作，可提供截图或视频

Best Practices

最佳实践

  • Be pragmatic above all else.
  • Write specs to improve input quality for agents, not as ceremony.
  • Keep product specs behavior-oriented and implementation-light.
  • Keep tech specs implementation-oriented and grounded in current codebase patterns.
  • Use review time to validate specs and behavior, not to over-index on code style nits.
  • 始终秉持务实原则。
  • 编写规格文档是为了提升Agent的输入质量，而非走形式。
  • 产品规格文档应聚焦行为，尽量减少实现细节。
  • 技术规格文档应聚焦实现，基于当前代码库模式。
  • 利用评审时间验证规格文档与行为，而非过度关注代码风格细节。

Related Skills

相关技能

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