How to use SpecDD in 10 minutes

How-To Getting started Beginner 1001003HOWTO-1001003

HOWTO-1001003Getting startedBeginner

This guide shows the fastest useful path into spec-driven development with SpecDD: install the CLI, initialize a project, add a root spec, add one local same-basename spec, and ask a contributor or agent to complete a focused change.

You can do this in a new project or in an existing project around the next file you plan to change.

Prerequisites

Before you start, make sure you have:

a Git repository or project folder
a contributor or agent that can read project files
Node.js 22 or newer if you install the CLI with npm or Yarn

Other CLI install paths are available on the tools page .

Steps

1. Install the CLI

Install SpecDD with npm:

npm install --global specdd

Or use another supported install path from the tools page, such as Yarn, Homebrew, Docker Hub, or GitHub Container Registry.

Verify that the command is available:

specdd --help

2. Initialize SpecDD

Choose the folder you want SpecDD to govern. This folder is the selected content root.

From that folder, run:

specdd init

The initialization creates the agent entrypoint files and bootstrap directory:

AGENTS.md
CLAUDE.md
.specdd/
  bootstrap.md
  bootstrap.project.md
  bootstrap.local.md

AGENTS.md is the normal agent entrypoint. CLAUDE.md points Claude-style workflows to AGENTS.md. The .specdd bootstrap files explain the SpecDD operating rules, so daily prompts can stay focused on the actual task.

3. Add a root spec

Create one root .sdd file named after the selected content root directory.

If your project folder is named travel-planner, create:

travel-planner.sdd

Start small:

Spec: Travel Planner

Purpose:
  Help people plan trips and keep itinerary items organized.

Structure:
  ./src: Project source files
  ./tests: Project checks

Must:
  Trips can be created and reviewed.
  Itinerary items remain grouped by trip day.

Must not:
  Booking and ticket purchases are outside Travel Planner.

The root spec gives the project a top-level contract. Do not turn it into a full file inventory.

4. Add one local spec

Pick one real file you want to change. Add a same-basename .sdd file beside it.

src/trips/itinerary.js
src/trips/itinerary.sdd

Write a small local spec:

Spec: Itinerary

Purpose:
  Keep a trip itinerary organized by day.

Owns:
  ./itinerary.js

Must:
  Valid itinerary items are stored with a place name and trip date.
  Itinerary items appear in chronological order.

Must not:
  Destination search results are outside Itinerary.

Tasks:
  [ ] Add missing-place validation.

Done when:
  The missing-place scenario is checked.

Scenario: missing place name
  Given the place name is empty
  When the person adds the itinerary item
  Then validation fails
  And no itinerary item is stored

This is enough to run the first loop.

5. Ask an agent for a bounded change

Use a focused prompt:

Complete the open task in the Itinerary spec.

The prompt names the work in human terms. The project instructions and specs provide the SpecDD workflow and boundaries.

6. Review the result

Before accepting the change, check:

the agent modified only the files allowed by the local spec
the implementation satisfies the Must rules
the implementation does not violate Must not
the scenario is covered by a useful check
task status changed only after verification

If the work revealed a missing rule, update the spec before moving on.

Common beginner mistakes

Forgetting that the root spec filename must match the content root directory.
Writing a root spec that tries to describe every file in the project.
Repeating bootstrap instructions in the task prompt.
Combining several instructions into one prompt.
Treating Can read or References as permission to modify another area.
Asking for a broad refactor as the first SpecDD task.

← Getting started guides