← Spec-writing technique guides

How to name SpecDD files

How-To Spec-writing technique Beginner 1071004HOWTO-1071004

HOWTO-1071004Spec-writing techniqueBeginner

This guide shows you how to name spec-driven development .sdd files.

Good naming makes specs easy to find. It also helps tools and agents resolve the local spec without guessing from similar names, symbols, tests, or imports.

Short answer

Name the root spec after the selected content root directory. For local file behavior, prefer same-directory same-basename specs such as itinerary.js and itinerary.sdd. Use suffixes such as .component.sdd, .policy.sdd, or .api.sdd only when they clarify the subject. Follow existing project naming conventions and avoid ambiguous case-only duplicates.

Steps

1. Name the root spec after the content root

If the content root is:

travel-planner/

the root spec is:

travel-planner.sdd

Use the directory basename, not the product title or package identifier.

2. Use same-basename specs for files

itinerary.js
itinerary.sdd

Same-directory basename matching is an explicit SpecDD rule. The .sdd file is the local spec for the ordinary file when they share a basename in the same directory.

Examples:

main.test.js -> main.test.sdd
Dockerfile -> Dockerfile.sdd
Trip.ts -> Trip.sdd

Matching is case-insensitive, but exact matches should win.

3. Use directory specs for directories

A directory can be described by a same-basename spec inside it:

src/trips/trips.sdd

or by a parent-held spec:

src/trips.sdd

Both may contribute context. They are cumulative, not ambiguity.

4. Use suffixes only when they clarify

Suffixes are optional:

itinerary.component.sdd
trip-access.policy.sdd
create-trip.api.sdd

Omit the suffix when the folder or filename already makes the role clear:

src/trips/itinerary.sdd

5. Follow project conventions

SpecDD naming examples are illustrations, not rules. A Python project may use lowercase names. A Java project may use class-like names. Use the convention that makes specs align closely with the files and components they describe.

Put project-wide naming conventions in .specdd/bootstrap.project.md.

6. Connect named specs explicitly

Named specs do not automatically apply to every nearby file.

If a named feature or policy spec should be discoverable from a directory, reference it:

Structure:
  ./trip-access.policy.sdd: Trip access decisions

References:
  ./trip-access.policy.sdd

References provide context, not write authority.

Common mistakes

How to verify the result

Spec file names are working when:

← Spec-writing technique guides