# Free spec packet template for AI coding agents

This is a free spec packet template in Markdown for handing a feature to an AI coding agent such as Claude Code, Cursor or Codex. It covers context, problem, evidence, user stories, acceptance criteria, constraints, out of scope, a test plan and likely files. Use it when you want the agent to build exactly what you meant.

Updated14 November 2026

## How do you use this template?

- Copy the template below into a Markdown file in your repository, for example **specs/feature-name.md**, so the agent can read it and the spec is versioned with the code.
- Fill in **Context**, **Problem** and **Evidence** first. If you have a PRD, most of this comes from it.
- Write each requirement with an ID, a priority and Given / When / Then acceptance criteria, including error and empty states.
- Add **Constraints**, **Out of scope**, the **Test plan** and **Files likely touched** with an engineer. Resolve every high-impact open question.
- Point the agent at the file, for example: "Implement specs/feature-name.md. Start with the P0 requirements and stop to ask if an open question blocks you."

## The spec packet template

spec-packet-template.md

```
# Spec: [Feature name]

## 1. Context

- Product:
- Users:
- Stack: [e.g. React + TypeScript frontend, FastAPI + Postgres backend]
- Conventions: [e.g. follow existing patterns in src/features/*, use the shared Button component]

## 2. Problem

## 3. Evidence

| ID | Evidence | Source |
|---|---|---|
| EV-001 | "[Verbatim customer quote]" | [Interview, date] |
| EV-002 | [Ticket count, usage data] | [Source] |

## 4. User stories

- US-1: As a ..., I want ... so that ...
- US-2:

## 5. Requirements and acceptance criteria

### REQ-001 [Title] (P0)
Story: US-1. Evidence: EV-001.
- Given ..., when ..., then ...
- Given ..., when ..., then ...

### REQ-002 [Title] (P1)
Story: US-1.
- Given ..., when ..., then ...

### REQ-003 [Error and empty states] (P1)
- Given no data, when the user opens the view, then ...
- Given the request fails, when ..., then ...

## 6. Constraints

-

## 7. Out of scope

- Do not ...
- Do not ...

## 8. Assumptions and open questions

| ID | Assumption or question | Impact if wrong | Status |
|---|---|---|---|
| ASM-001 | | High / Medium / Low | Open / Resolved: [answer] |

## 9. Test plan

- Unit: [what to test] (REQ-001, REQ-002)
- Integration / API: [what to test]
- End to end: [the main flow from US-1]
- Commands: [e.g. npm test, pytest tests/feature_x]

## 10. Files likely touched

- [path/to/component.tsx]: [what changes]
- [path/to/api/route.py]: [what changes]
- [path/to/tests/]: [new tests]

## 11. Definition of done
- [ ] All P0 and P1 acceptance criteria pass
- [ ] Tests in the test plan are written and passing
- [ ] Nothing in Out of scope was built
- [ ] Open questions are resolved or listed in the pull request description

```

## Common mistakes when writing specs for AI coding agents

- **Adjectives instead of acceptance criteria.** "Fast" and "clean" leave the agent to decide what you meant.
- **No out-of-scope list.** Agents fill silence by building more, not less.
- **Open questions left open.** The agent will not ask unless told to; it will guess and move on.
- **Skipping error and empty states.** These are the cases most often missing from generated code.
- **No test plan.** Without one, "done" means "compiles".

## How Praxiom AI fills this in for you

Praxiom AI generates a [Spec Packet](https://www.praxiomai.xyz/glossary/spec-packet) from your research, with numbered requirements, acceptance criteria, assumptions and evidence linked to customer quotes. It scores readiness, lists the blockers, and produces one implementation ticket per requirement plus a coding-agent prompt for Claude Code or Codex. See [specs for AI coding agents](https://www.praxiomai.xyz/use-cases/specs-for-ai-coding-agents) or [sign up](https://app.praxiomai.xyz/sign-up).

## Frequently asked questions

### Does this template work with Claude Code, Cursor and Codex?

Yes. It is plain Markdown, which all of them read. Save it in the repository and reference it in your prompt, or paste it directly into the chat.

### How is this different from a PRD template?

A PRD aligns people; this spec is written to be executed. It adds constraints, a test plan, files likely touched and an explicit definition of done, and it requires open questions to be resolved. Start from the [PRD template](https://www.praxiomai.xyz/templates/prd-template) if you need team alignment first.

### Why include evidence in a spec for a coding agent?

The agent does not need it to write code, but the people reviewing the pull request do. Evidence explains why each requirement exists, which helps reviewers judge trade-offs the agent made.

### How long should a spec for an AI coding agent be?

Scope it to work an agent can complete and a person can review in one pull request. If the requirements list grows long, split the feature into several specs.

Run your product discovery on autopilot.

Bring your interviews, tickets and surveys. Get scored insights, a PRD and tickets.

[Sign up](https://app.praxiomai.xyz/sign-up)[See pricing](https://www.praxiomai.xyz/pricing)

Source: https://www.praxiomai.xyz/templates/spec-packet-template
