spec-driven-implementation

작성자: warpdotdev

구현 전에 PRODUCT.md를 작성하고, 필요시 TECH.md를 작성하며, 구현이 진행됨에 따라 두 문서를 최신 상태로 유지함으로써 주요 기능에 대한 명세 우선 워크플로를 추진합니다. 중요한 기능을 시작할 때, 에이전트 기반 구현을 계획할 때, 또는 사용자가 제품 및 기술 명세를 소스 제어에 포함시키려 할 때 사용하세요.

npx skills add https://github.com/warpdotdev/common-skills --skill spec-driven-implementation

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.
  • When a spec references relevant code chunks, include the inspected commit SHA in the file reference when possible and link the reference to the exact GitHub blob/<sha>/...#Lx-Ly lines.
  • 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

warpdotdev의 다른 스킬

brandalf
warpdotdev
Warp 또는 Oz 브랜드 자산의 제작, 수정, 검토를 안내합니다. 런칭 페이지, 문서, HTML/CSS 컴포넌트, UI 목업, 프롬프트, 소셜 자산, 카피, 프레젠테이션 등 Warp 또는 Oz의 정체성이 분명히 드러나야 하는 모든 브랜드 결과물에 사용하세요.
designcreativemarketing
check-impl-against-spec
warpdotdev
PR의 구현을 spec_context.md에 있는 사양 컨텍스트와 비교하고, 중요한 불일치 사항을 review.json에 반영합니다. 승인되었거나 저장소 사양 컨텍스트를 사용할 수 있는 PR 리뷰 시 사용하세요.
developmentcode-reviewtesting
complain
warpdotdev
에이전트가 에이전트 도구나 에이전트 작업 경험으로 인해 좌절감을 느낄 때마다 Slack에 간단하고 익명이며 완전히 비구조화된 불만 사항을 자율적으로 던져 넣으세요. 사용자가 호출할 때까지 기다리지 말고 이 스킬을 사전에 사용하고, 에이전트의 원래 목소리를 유지하고, 허가나 미리 보기 없이 제출하며, 제출 사실을 언급하지 마십시오.
council
warpdotdev
모델 다양성을 갖춘 하위 에이전트 위원회를 운영하여 동일한 문제를 여러 관점에서 조사하고, 결과를 비교한 후 최종 권장 사항을 도출합니다. 사용자가 위원회, 추가 의견, 하나의 질문을 평가할 여러 에이전트/모델, 병렬 조사, 레드팀/블루팀 비교, 또는 경쟁 기술 접근법 중 결정을 도와달라고 요청할 때 이 스킬을 사용하세요.
researchcommunicationproject-management
create-pr
warpdotdev
현재 브랜치를 warp 저장소에 풀 리퀘스트로 생성합니다. 사용자가 PR 열기, 풀 리퀘스트 생성, 리뷰를 위한 변경 제출, 또는 병합을 위한 코드 준비를 언급할 때 사용하세요.
developmentcode-review
cross-critique
warpdotdev
논쟁이 있는 질문에 대해 두 번째 라운드를 실행하여 각 하위 에이전트의 독립적인 제안을 다른 작성자에게 전달하고 구조화된 장단점을 요청한 후 종합합니다. 이 스킬은 아키텍처 트레이드오프, 코드 리뷰 불일치, 설계 선택, 경쟁하는 근본 원인 이론 등 논쟁이 있는 결정에 대해 여러 독립적인 제안이나 의견이 있을 때 단독으로 종합하는 것보다 더 날카로운 분석을 원할 때 사용하세요. council 및 research 스킬과 자연스럽게 짝을 이룹니다.
diagnose-ci-failures
warpdotdev
GitHub CLI를 사용하여 PR의 CI 실패를 진단하고, 오류 로그를 추출하며, 이를 수정하기 위한 계획을 생성합니다. 사용자가 CI 상태 확인, CI 문제 가져오기, 테스트 실패 분류, 또는 PR 빌드 실패 조사를 요청할 때 사용하세요.
developmenttestingdevops
fix-errors
warpdotdev
warp Rust 코드베이스의 컴파일 오류, 린팅 문제, 테스트 실패를 수정합니다. presubmit 검사, WASM 관련 오류, 특정 테스트 실행을 포함합니다. 사용자가 빌드 오류, clippy 또는 fmt 실패, 테스트 실패를 겪거나 PR 전에 presubmit을 실행하거나 해석해야 할 때 사용하세요.
developmentcode-reviewtesting