Skip to content
Skills Library
Management & product · Writing

spec-driven-development

/spec-driven-development

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.

Author
jmxt3 ↗
Repository
gitscape.ai ↗
Licence
Apache-2.0
Last repository change
17.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.07.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.

Original author description

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.

How it works

  1. Overview
  2. When to Use
  3. The Spec Process
  4. Spec Quality Bar
  5. Common Rationalizations
  6. Red Flags
  7. Verification
Original SKILL.md headings · 121 lines, 817 words
SKILL.md preview
---
name: spec-driven-development
description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.
---

# Spec-Driven Development

## Overview

Write a structured specification before writing any code. A spec answers three questions: **what** are we building, **why** are we building it, and **how will we know it's done?** Every hour spent on a spec saves multiple hours of rework. Never start implementation without a written, reviewed spec.

## When to Use

- Starting a new project, feature, or significant change
- Requirements are unclear, ambiguous, or stated as a vague idea
- Multiple possible approaches exist and the tradeoffs need documenting
- The change touches more than two files or crosses a system boundary

**When NOT to use:** Trivial bug fixes with a clear, single-line root cause, or changes where the spec already exists and is current.

## The Spec Process

### Step 1: Interview First (If the Ask Is Vague)

Before writing the spec, gather enough context to write it well:

- What problem does this solve for the user?
- Who are the users, and what do they currently do instead?
- What does success look like? How will we measure it?
- Are there any hard constraints (perf, security, compatibility, deadline)?
- What's explicitly out of scope?

Do not write the spec until you can answer these with confidence.

### Step 2: Write the Spec

A spec has six sections:

```markdown
# Spec: [Feature Name]

## Objective
One paragraph: what problem this solves and for whom. Include the measurable
success condition (e.g., "users can reset their password without contacting support").

## Commands / User Flows
The primary interactions from the user's point of view. Use imperative language:
- User navigates to /reset-password
- User enters email address and submits
- User receives email with a time-limited link
- User sets a new password via the link

## Project Structure
Which files and modules will change or be created. Group by layer (API, frontend, DB).
Note any new dependencies.

## Code Style and Patterns
- Which existing patterns to follow (e.g., "use the existing AuthService pattern")
- Naming conventions for new symbols
- Error handling approach

## Testing Strategy
- What will be unit tested
- What requires integration tests
- Any E2E coverage needed
- Edge cases to cover explicitly

## Boundaries
- Always: [things the implementation must always do]
- Ask first: [decisions that require human sign-off before proceeding]
- Never: [things the implementation must never do]
```

### Step 3: Review Before Coding

Before writing any code:

- [ ] Spec covers all six sections
- [ ] Objective includes a measurable success condition
- [ ] Boundaries list at least one "Never"
- [ ] Human has reviewed and approved the spec
- [ ] Open questions are resolved or explicitly parked

A spec that is "good enough to review" is good enough to start coding. Perfection is not the goal — clarity is.

### Step 4: Save and Reference

Save the spec as `SPEC.md` in the project root (or `docs/SPEC.md` for multi-project repos). Reference it in commits and PRs. When requirements change, update the spec first — the spec is the source of truth, not the code.

## Spec Quality Bar

A good spec:
- **Defines done** — a reader can verify completion without asking the author
- **Surfaces trade-offs** — records the decisions made and why alternatives were rejected
- **Scopes explicitly** — what is out of scope is as important as what is in scope
- **Is short** — a one-page spec is better than a ten-page spec. If the spec is long, break the work into multiple specs.

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "I know what to build, I don't need a spec" | The spec isn't for you — it's for the reviewer, the future maintainer, and your future self after a context switch. |
| "The requirements will change anyway" | A spec makes changes visible. Without one, scope creep is invisible until it's a problem. |
| "Writing a spec takes too long" | A vague spec takes 15 minutes. The rework it prevents takes hours. |
| "The ticket/issue is the spec" | Issue trackers capture requests, not decisions. A spec captures what was decided and why. |

## Red Flags

- Starting implementation without a written spec
- A spec with no measurable success condition
- A spec where "out of scope" is empty
- No human review before coding begins
- Spec is written after the code (post-hoc rationalization)

## Verification

Before writing code, confirm:

- [ ] Spec exists as a file (not just in your head)
- [ ] All six sections are present and non-empty
- [ ] The objective includes a measurable success condition
- [ ] At least one "Never" boundary is defined
- [ ] A human has read and approved the spec
- [ ] Open questions are explicitly tracked (not silently assumed)

Versions

RepositoryScoreLicence
This page · jmxt3/gitscape.ai100Apache-2.0
magnus919/agent-skills100MIT
lucasouzadev/agent-kit-skill100MIT
FrancoStino/opencode-skills-collection100MIT
DanielCryer/spec-workflow100MIT
ctoforaday/special-circumstances100MIT
krzysztofsurdy/code-virtuoso100MIT
rafidone/agent-skills100MIT
sickn33/agentic-awesome-skills100MIT

Database snapshot: 13.11.2026 · package version 5cabe58d2b79 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90spec-driven
    Use when starting a project or feature, requirements are unclear, or a change crosses modules. Accepts new specs and already-approved specs via the existing-spec entry.
  • 100spec-driven
    Use when starting a project or feature, requirements are unclear, or a change crosses modules. Not for implementing from an existing spec: use spec-driven-implementation.
  • 100spec
    Designs and develops specs following the spec-driven method. Asks clarifying questions before proposing structure, and builds the spec section by section. Use it when starting a large feature, before writing code.
  • 90sdd
    Implements the Spec-Driven Development lifecycle (Intent, Requirements, Design, Tasks, Build) for structured feature development. Use when the user wants to scaffold a new feature spec, generate EARS requirements, create a technical design, break work into tasks, or check spec…
  • 90data-specification
    Creates structured specifications for data products and pipeline changes. Use when starting a new pipeline, model, ingestion flow, or any significant change with unclear requirements.
  • 100spec
    Interview the user about a feature or project, then write a spec they can build from. Use when the user wants to plan, scope or spec something before coding, or runs /spec with an idea.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.