Feature slices
Use it for one screen, endpoint, background job, or workflow branch that can be reviewed in one pull request.
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.
When To Use This Template
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.
How To Use It In A Real Claude Code Run
The template works best when it is treated as a small operating contract, not as decoration above a prompt. Use it to slow down the first thirty seconds of the run: the agent should read the boundary, confirm the plan, edit inside the allowed area, and report evidence in the same vocabulary the reviewer will use later.
Before the first edit
Paste the spec before asking for implementation. Ask Claude Code to restate the task, allowed files, non-goals, and evidence bar before it touches the repository. This catches missing decisions while the cost is still low, especially when the work touches payments, permissions, migrations, jobs, or public APIs.
During the implementation
Keep the conversation anchored to the spec. If Claude Code proposes changing an unlisted file, adding a dependency, altering a schema, or widening a public contract, treat that as a spec change request. Either update the spec explicitly or ask the agent to find a narrower path.
Before merge
Do not accept a final answer that only says the task is complete. Require the changed-files summary, command output, skipped checks, and criterion-to-evidence mapping. That record makes the PR review faster because reviewers can reject drift before debating style or implementation preference.
Review Questions Before Adoption
Claude Code Spec Template 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 Claude Code Spec Template, 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 claude-code-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 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 generatorspec.md Template for AI Agents
Use a repo-level spec.md when several agents or tools need the same source of truth.
Open templateAI PR Review Checklist
Review the generated diff against the original spec before merge.
Open checklistClaude 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