← Install and setup guides

How to add SpecDD to an existing project

How-To Install and setup Beginner 1011003HOWTO-1011003

HOWTO-1011003Install and setupBeginner

This guide shows how to add SpecDD to an existing repository without turning the adoption into a broad rewrite.

SpecDD works well on existing projects because you can initialize the framework once, then introduce .sdd specs around the next module, feature, service, workflow, or documentation area you actually plan to change.

Prerequisites

Before you start, make sure you have:

Steps

1. Start from a branch you can review

Before initializing, check the current diff:

git status --short

Use a branch or commit boundary that makes the setup files easy to inspect. SpecDD initialization is small, but it still adds project instructions that future agents will follow.

2. Run init at the intended content root

From the repository root, run:

specdd init

If SpecDD should govern a subproject instead of the whole repository, initialize that subdirectory:

specdd init path/to/subproject

The selected content root is important because root specs, /-prefixed paths, and inherited spec context are resolved from that boundary.

3. Review generated and skipped files

The current setup expects:

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

During init, existing non-bootstrap files are left unchanged. If your repository already had AGENTS.md, CLAUDE.md, or local bootstrap files, review those files and add the generated AGENTS.md content manually where needed:

Before working on this project, read `.specdd/bootstrap.md`.

Assume the role, rules, workflow, and implementation constraints described in SpecDD. Treat SpecDD specs as
source-adjacent development contracts, not optional documentation. Adhere to SpecDD rules unless explicitly
instructed otherwise.

Keep any existing agent instructions that are still valid. The goal is to wire SpecDD into the project, not erase useful local guidance.

4. Put project conventions in bootstrap.project.md

Add shared team rules to:

.specdd/bootstrap.project.md

Good project-wide rules include:

Do not put personal preferences there. Put those in .specdd/bootstrap.local.md, which is ignored by the generated .specdd/.gitignore.

5. Add a root spec

Create a root .sdd file named after the content root directory.

If the content root is:

travel-planner/

create:

travel-planner.sdd

Start with a short project contract:

Spec: Travel Planner

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

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

Must:
  Trips can be created and reviewed.

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

6. Start adoption in one active area

Pick the next area you expect to change. For example:

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

Add a small same-basename spec:

Spec: Itinerary

Purpose:
  Keep a trip itinerary organized by day.

Owns:
  ./itinerary.js

Must:
  Itinerary items remain grouped by trip day.

Must not:
  Manage destination search results.

This gives the first real implementation area a local contract without requiring the whole repository to be fully specified.

7. Verify the setup

Run:

specdd inspect .

Then check the diff:

git status --short
git diff

Commit only the shared setup and the first reviewed specs. Leave .specdd/bootstrap.local.md uncommitted.

Common mistakes

← Install and setup guides