Repository-first method

Spec as Code Hub

Spec as code means the decision artifact lives beside the implementation. A small spec.md is versioned in git, reviewed before coding, linked from the pull request, and updated whenever behavior changes.

Generate a spec Open feature template

Last updated: May 19, 2026

What Spec as Code Solves

Most delivery drift starts when the requirement, the implementation, and the review evidence live in different places. A product note sits in a ticket, the real decisions happen in chat, the pull request shows code without context, and QA has to infer behavior from whatever changed. Spec as code puts the small decision record into the same review path as the implementation.

The goal is not to turn every feature into a long design document. The goal is to make the behavior that matters visible before the first large diff appears. If a reviewer can read the spec, understand the boundary, inspect the tests, and see the rollout evidence from the same pull request, the team has a shared contract instead of a memory test.

Spec as Code vs Related Terms

Term	Best meaning	What to do on this site
Spec-first development	Decide behavior, scope, and acceptance before implementation.	Use the Spec-First Hub when you need the overall method.
Spec as code	Keep the spec in the repository and review it like code.	Use this page when you need file structure, review rules, and evidence links.
Code spec	A common search phrase for a small implementation-facing spec.	Write a short `spec.md` that names affected files, interfaces, and tests.
Coding spec	A practical spec that guides implementation work.	Start with acceptance criteria, allowed scope, edge cases, and proof before merge.
SDD	Spec-driven development: specs, plans, tasks, tests, and evidence as a workflow.	Use the SDD Hub for multi-step delivery and AI coding governance.

Repository Structure

repo layoutcopy-ready

/specs
  /checkout-coupon
    feature.spec.md
    acceptance.md
    evidence.md
    decisions.md

/src
  /checkout
    coupon-service.ts
    coupon-service.test.ts

/docs
  release-notes.md

Keep the artifact close, but not buried

A good location is easy to link from tickets and pull requests. Put specs in a predictable /specs directory or beside the module they govern. Avoid storing the only copy in chat, a private document, or a generated prompt transcript.

Use stable file names such as feature.spec.md or api-contract.spec.md.
Link the spec from the issue, pull request, release note, and test evidence.
Keep rejected alternatives in decisions.md when the tradeoff will matter later.

Review Workflow

Draft

Write goal, non-goals, acceptance criteria, affected interfaces, and evidence expectations.

Review

Ask product, engineering, QA, and operations to reject vague scope before coding starts.

Implement

Keep the diff inside the approved scope. Update the spec when behavior changes.

Prove

Attach tests, logs, rollout notes, and rollback signals before merge or release.

Evidence Matrix

Change type	Minimum spec content	Evidence before merge
Feature behavior	Goal, non-goals, acceptance criteria, edge cases	Unit test, integration test, manual QA note for visual or workflow cases
API contract	Request, response, errors, compatibility, migration plan	OpenAPI diff, consumer test, retry and timeout coverage
Database change	Schema intent, migration order, rollback, data safety rule	Migration dry run, backfill metric, rollback rehearsal note
AI-generated code	Allowed files, prompt boundary, acceptance criteria, risk class	Changed-file map, tests run, reviewer notes, evidence log
Release workflow	Owner, rollout threshold, stop signal, rollback owner	Dashboard link, log query, release checklist, incident fallback

Common Mistakes

Putting the spec in the repo but never making it a review gate.
Writing a narrative summary without testable acceptance criteria.
Letting implementation drift without updating the spec in the same pull request.
Using the spec as a prompt only, then losing the source of truth after the AI session ends.
Claiming a change is complete without linking tests, logs, metrics, or release evidence.

Recommended Resources

Generate a spec packet

Turn a rough requirement into spec, tasks, acceptance criteria, and an evidence checklist.

Open packet tool

Browse spec templates

Use feature, API, database, evidence log, and AI coding review templates.

Open templates

Compare SDD references

Study OpenSpec, Superpowers, and Spec Kit patterns for modern spec-driven delivery.

Read comparison

Review before coding

Check whether the spec is specific enough before a large implementation diff starts.

Use checklist

See a real before and after

Watch a vague requirement become a reviewable spec packet with acceptance evidence.

Open example

Understand spec-first

Use the broader method when your team needs a shared delivery model, not just a file format.

Open hub

FAQ

What does spec as code mean?

Spec as code means the spec lives with the codebase, usually as a markdown file reviewed in git before implementation. It is versioned, linked from issues and pull requests, and updated when behavior changes.

Is spec as code the same as spec-first development?

They overlap but are not identical. Spec-first describes the habit of deciding behavior before coding. Spec as code describes where the artifact lives and how it is reviewed, versioned, and connected to evidence.

What should be inside a code spec?

A useful code spec includes goal, non-goals, acceptance criteria, affected files or interfaces, edge cases, tests, rollout notes, and evidence required before merge.

Do small teams need spec as code?

Yes, when the change is risky or easy to misunderstand. The smallest useful version is one spec.md file linked from the ticket and pull request.

How does this help AI coding workflows?

AI coding works better when the model receives a bounded spec, allowed files, acceptance criteria, and evidence expectations. Spec as code keeps those instructions reviewable instead of hidden in a chat prompt.

Use this page when a search for code spec or coding spec really means: "I need a short, reviewable spec.md that can guide implementation."

Generate a spec Browse templates