---
id: gh-spec-driven-implementation
name: "spec-driven-implementation"
url: https://skills.yangsir.net/skill/gh-spec-driven-implementation
author: warpdotdev
domain: ai-dev-tools-workflow
tags: ["spec-first", "workflow", "documentation", "software-development", "agent-driven"]
install_count: 28600
rating: 4.60 (120 reviews)
github: https://github.com/warpdotdev/common-skills/tree/main/.agents/skills/spec-driven-implementation
---

# spec-driven-implementation

> 此技能通过编写产品和技术规范，驱动重大功能的规范优先开发流程。它在实施前明确需求和设计，减少歧义，提升开发质量。适用于规划代理驱动的复杂功能实现。

**Stats**: 28,600 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 缩短功能审查周期

**Before**:

在缺乏明确产品和技术规范的情况下，重大功能审查常因需求模糊和设计不确定性，导致反复沟通和长时间的修改，平均耗时240分钟。

**After**:

采用规范优先流程，产品和技术规范在实施前已明确，审查能快速聚焦于代码质量和实现细节，平均耗时缩短至60分钟。

| Metric | Before | After | Change |
|---|---|---|---|
| 审查时长 | 240分钟 | 60分钟 | -75% |

## Readme

# spec-driven-implementation

Drive a spec-first workflow for substantial features in 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.

## 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.

## Workflow

### 1. Decide whether the feature needs specs

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

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.

### 3. Write the tech spec when warranted

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.

### 4. Implement approved specs

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.

### 5. Keep specs current during implementation

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.

### 6. Verify behavior against the spec

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

## 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.

## Related Skills

- `implement-specs`
- `write-product-spec`
- `write-tech-spec`


---
*Source: https://skills.yangsir.net/skill/gh-spec-driven-implementation*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-spec-driven-implementation/markdown*