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

How To Keep spec.md Alive During The PR

A spec.md file is valuable only if it remains authoritative while the work changes. Treat it as a small contract that travels with the branch: the agent reads it before editing, the developer updates it when decisions change, and the reviewer uses it to judge the final diff.

Commit it near the change

Put spec.md where future readers will find it: a docs/specs folder, a .specs folder, or the task directory used by the repository. If the file lives only in chat, it cannot be diffed, linked from a PR, or reused by the next agent pass.

Update before expanding scope

When implementation reveals a missing decision, update spec.md before asking the agent to continue. Do not let the code become the first place where a new behavior, dependency, schema change, retry rule, or permission decision appears.

Review against the file

At review time, compare changed files, acceptance criteria, non-goals, and evidence against spec.md before reading style details. If the prompt history says one thing and spec.md says another, the durable file should win until it is explicitly changed.

Review Questions Before Adoption

spec.md Template for AI Agents is not just a prompt for an AI tool. It should help people decide whether the task is ready for implementation, who owns unresolved questions, and which evidence will remain with the pull request. Use these questions in team conventions, PR templates, or pre-implementation review.

Who owns the decision?

Before using spec.md Template for AI Agents, name the person or role allowed to approve scope changes. Open questions without an owner become an invitation for the agent to fill gaps, and they make reviewers discover product, data, or permission decisions only after the code exists.

What blocks implementation?

Separate questions that must be answered from questions that can move forward as accepted risk. Blocking items usually include public APIs, data migrations, permission boundaries, payment behavior, rollback paths, and user-facing copy. If these are unclear, do not ask an agent to generate production code yet.

What evidence stays with the PR?

The final pull request should link spec.md, list changed files, name skipped checks, and map tests, screenshots, logs, or metrics back to acceptance criteria. Without that record, future readers have to reverse-engineer the decision from the diff.

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