← Getting started guides

How to run your first spec-driven change end to end

How-To Getting started Beginner 1001005HOWTO-1001005

HOWTO-1001005Getting startedBeginner

An end-to-end spec-driven development change starts with intent and ends with review. The important part is the loop: define the behavior, make the implementation follow the spec, verify the result, and keep the spec aligned with the code.

This guide shows a minimal SpecDD workflow for one small change.

Short answer

Pick a small target, write or update the local .sdd spec, add a concrete Done when and Scenario, prompt the specific work, implement the smallest change, run checks, update task status only after verification, and review the diff against the spec.

What you will change

By the end, you will have:

Steps

1. Choose a small behavior

Start with behavior that fits in one local boundary.

Example:

Reject itinerary items when the place name is missing.

This is better than:

Improve itinerary management.

The first request has a testable outcome. The second invites broad implementation.

2. Find or create the local spec

If the target file is:

src/trips/itinerary.js

use:

src/trips/itinerary.sdd

If a spec already exists, update it before implementation when intended behavior changes. If no spec exists, create the smallest useful one.

3. Define the behavior and task

Add the behavior as a requirement and the work as a task:

Spec: Itinerary

Purpose:
  Keep a trip itinerary organized by day.

Owns:
  ./itinerary.js
  ./itinerary.test.js

Must:
  A missing place name is rejected before an itinerary item is stored.
  Existing itinerary items remain unchanged when validation fails.

Must not:
  Manage destination search results.

Tasks:
  [ ] Add missing-place validation.

Done when:
  Missing-place behavior is covered by a check.
  Existing itinerary behavior still passes.

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

The Must rules define durable behavior. The task is just the current work packet.

4. Ask for the specific work

Use a task-focused prompt:

Implement the open validation task in the Itinerary spec.

Do not repeat the SpecDD bootstrap instructions in the prompt. The task prompt should identify the work; the project instructions and specs provide the workflow and boundaries. Keep each prompt to one instruction.

5. Implement the bounded slice

For a very small change, the implementation prompt may be the same as the task prompt:

Implement missing-place validation in the Itinerary feature.

Keep the change as small as possible. A first spec-driven change should prove the loop, not solve every nearby problem.

6. Run checks

Run the relevant tests, validation, linting, or documentation checks for the project. If an agent ran the checks, review what it reports.

Good final reports include:

If a check cannot run, record why. Do not mark a task complete simply because code was written.

7. Update task status

Only after implementation and checks are complete, update:

Tasks:
  [x] Add missing-place validation.

Do not mark unrelated tasks complete. Tasks are local work guidance, not a place for opportunistic cleanup.

8. Review the diff against the spec

Before merging or accepting the result, check:

Common mistakes

How to verify the result

The end-to-end loop worked when:

← Getting started guides