AI coding handoff

Claude Code Spec Template

Use this page when Claude Code is ready to edit files, but the task still needs a narrow source of truth. The goal is to give the agent enough context to work and enough limits to stay reviewable.

Generate packet Read the packet guide

Last updated: May 25, 2026

When To Use This Template

Feature slices

Use it for one screen, endpoint, background job, or workflow branch that can be reviewed in one pull request.

Bug fixes

Write the failing behavior, expected behavior, reproduction path, and regression test before asking for a patch.

Risky edits

Use allowed write scope when the repository has nearby files Claude Code might be tempted to rewrite.

What The Spec Should Decide

Start with the outcome, not the implementation guess. Claude Code should know what behavior must change, which behavior must stay intact, and which files are off limits.

The strongest field is often Evidence before merge. If the agent cannot produce the named test command, screenshot, log query, or manual check, the final response should say so instead of pretending the work is ready.

Before You Paste It

  • The task can be explained in one sentence.
  • Allowed write scope is smaller than the repository.
  • Non-goals block common scope expansions.
  • Every acceptance criterion can become a test or manual check.
  • The agent must ask before changing unlisted files or contracts.

Copy-Ready Claude Code Spec

Paste this into Claude Code before the first edit. Keep the allowed write scope narrow, then ask the agent to stop and ask if the task appears to require a wider change.

claude-code-spec.md 
Use this spec as the source of truth.

Task:
- Implement:
- Preserve existing behavior:

Allowed write scope:
- May edit:
- May read:
- Must not change:

Non-goals:
- No unrelated refactors.
- No new dependencies unless explicitly approved.
- No public API or schema changes unless listed here.

Acceptance criteria:
- [ ] Given ..., when ..., then ...
- [ ] Failure path:
- [ ] Permission, empty, duplicate, or timeout state:

Evidence before merge:
- Test command:
- Manual check:
- Changed files summary:
- Criteria-to-evidence mapping:

If the spec is ambiguous, ask before editing.

Filled Example

This example turns a vague retry request into a bounded patch that can be reviewed mechanically.

filled-example.md 
Task:
- Add retry handling when LedgerClient.recordPayment times out once.

Allowed write scope:
- src/payments/webhook-handler.ts
- src/payments/webhook-handler.test.ts

Must not change:
- LedgerClient public API
- webhook signature validation
- provider timeout constants

Acceptance criteria:
- [ ] Given LedgerClient times out once, when a valid payment event is processed, then the handler retries once and records the payment.
- [ ] Given LedgerClient times out twice, when the event is processed, then the existing retryable failure response is returned.
- [ ] Given signature verification fails, when the handler receives the event, then no ledger call is attempted.

Evidence:
- npm test -- webhook-handler
- PR summary maps AC-1, AC-2, and AC-3 to test cases.

Common Mistakes

No file boundary

The prompt says what to build but not which files may change, so the agent expands into nearby helpers.

Only happy path

The spec covers success but omits failure, permission, timeout, or empty states.

Evidence as prose

The final answer says tests passed without naming the command, case, screenshot, or log evidence.

Related Resources

Use these pages to move from handoff to implementation and review without losing the spec boundary.

AI Spec Packet Generator

Generate spec.md, tasks, acceptance criteria, and evidence in one browser tool.

Open generator

spec.md Template for AI Agents

Use a repo-level spec.md when several agents or tools need the same source of truth.

Open template

AI PR Review Checklist

Review the generated diff against the original spec before merge.

Open checklist

Claude Code Spec FAQ

What should I give Claude Code before asking it to edit files?

Give it a short spec with task summary, allowed files, non-goals, acceptance criteria, and evidence required before merge.

Should the spec include implementation steps?

Include a small plan when file ownership matters, but keep it reviewable. Acceptance criteria and non-goals are more important than a long task list.

How do I stop scope drift?

Name allowed write scope and non-goals explicitly, then require Claude Code to ask before changing files or behavior outside that boundary.

For the next real task, generate a packet first, then paste it into Claude Code with the allowed files and evidence fields intact.

Generate spec packet