Repo source of truth

spec.md Template for AI Agents

A good spec.md is not a prompt wrapper. It is the shared contract that lets humans, AI agents, tests, and reviewers agree on what the change means.

Generate spec packet See Claude template

Last updated: May 25, 2026

Where spec.md Fits

Multi-agent work

Use it when drafting, planning, coding, and review may happen in separate tool passes.

Repository memory

Keep the decision near the code so future reviewers can see why the change exists.

Spec-first AI

Give every coding agent the same bounded source of truth before implementation starts.

What Belongs In spec.md

The file should answer what is changing, why it matters, which boundaries are real, and what evidence will prove completion. It should not become a vague product essay.

Use open questions deliberately. If a decision is still unknown, name it and block implementation until it is answered or explicitly accepted as risk.

spec.md Readiness Checklist

  • The goal names the smallest useful outcome.
  • Scope lists allowed write paths and read-only context.
  • Non-goals block dependencies, contracts, and refactors not approved.
  • Acceptance criteria include at least one edge or failure case.
  • Open questions identify owner and whether they block implementation.

Copy-Ready spec.md

Place this in docs/specs, .specs, or the task folder. Keep it updated in the same PR as implementation changes.

spec.md 
# spec.md

## Context
- Problem:
- Current behavior:
- Users or systems affected:

## Goal
- The smallest useful outcome:

## Scope
- In scope:
- Allowed write paths:
- Read-only context:

## Non-goals
- Explicitly excluded:
- Dependencies or contracts that must not change:

## Acceptance Criteria
- [ ] AC-1:
- [ ] AC-2:
- [ ] AC-3:

## Evidence
- Automated tests:
- Manual checks:
- Logs, screenshots, metrics, or migration output:

## Open Questions
- Question:
- Owner:
- Blocking implementation? yes/no

If this spec conflicts with a prompt, this spec wins.

Filled Example

This example shows the level of detail an AI agent can safely implement from.

filled-example.md 
# spec.md

## Context
- Users can disable all notifications, but security alerts must remain mandatory.

## Goal
- Add per-channel notification preferences without disabling security alerts.

## Scope
- In scope: settings UI, preferences API client, preference form tests
- Allowed write paths: src/settings/notifications/*, tests/settings/*
- Read-only context: src/auth/*, src/api/preferences.ts

## Non-goals
- No delivery pipeline changes
- No digest mode
- No auth role changes

## Acceptance Criteria
- [ ] Marketing email toggle saves marketingEmail=false.
- [ ] Security alert row is visible but locked.
- [ ] Failed save restores previous toggle state and shows an error.

## Evidence
- npm test -- notifications
- Screenshot: locked security alert row
- PR notes changed files and skipped checks

Common spec.md Problems

Prompt dump

The file repeats a chat prompt instead of storing the durable decisions.

No owner for questions

Open questions without owners become permission for the agent to guess.

No update habit

Implementation changes behavior, but spec.md stays frozen and loses authority.

Related Resources

Use spec.md as the anchor, then choose the right tool-specific handoff.

Claude Code Spec Template

Paste a narrower task version into Claude Code.

Open template

Cursor AI Coding Spec Template

Use read/write scope when prompting Cursor.

Open template

Feature Spec Template

Use a fuller template for product and engineering review.

Copy template

spec.md FAQ

Where should spec.md live?

Use a stable docs/specs or .specs folder, or keep it next to the task when the repository has an established convention.

Should spec.md be committed?

For meaningful behavior changes, yes. The spec should move with the implementation evidence.

What if the prompt conflicts with spec.md?

Treat spec.md as the source of truth and update it explicitly before asking an agent to continue.

A durable spec.md lets AI tools help without becoming the place where product decisions disappear.

Generate spec packet