Cursor handoff

Cursor AI Coding Spec Template

Cursor is strongest when the prompt tells it which behavior matters and which nearby code is off limits. This template turns a vague composer request into a bounded coding task.

Generate packet Compare with Claude Code

Last updated: May 25, 2026

When Cursor Needs A Spec

Composer changes

Use it before asking Cursor to edit multiple files or infer implementation from scattered context.

Contract-sensitive work

Name API, DB, event, and UI contracts that must not change while the agent patches behavior.

Reviewable tasks

Keep the diff small enough that a human reviewer can compare output against acceptance criteria.

How To Keep Cursor Focused

Cursor can read a lot of neighboring code, which is useful and risky. The spec should separate read scope from write scope so useful context does not become permission to edit everything.

The prompt should also state what to do when the task needs another file. A good answer is not a creative refactor. It is a question back to the human owner.

Cursor Spec Checklist

  • Separate files Cursor may read from files Cursor may edit.
  • Name contracts, props, endpoints, or schemas that must stay stable.
  • Include at least one failure or permission criterion.
  • Require a changed-files summary before final approval.
  • Ask Cursor to stop if it needs wider scope.

Copy-Ready Cursor Spec

Use this with Composer or an inline edit request. Keep the first block short, then make verification explicit.

cursor-spec.md 
Cursor task:
- Implement:
- Preserve:

Open context:
- Read these files:
- May edit these files:
- Do not edit:

Behavior rules:
- Existing contract to preserve:
- Existing UI copy or API shape to preserve:
- Error, permission, and empty states:

Acceptance criteria:
- [ ] Given ..., when ..., then ...
- [ ] Given ..., when ..., then ...

Verification:
- Test command:
- Manual check or screenshot:
- Files changed summary:

If implementation requires a file outside "May edit", stop and ask.

Filled Example

This example keeps a notification settings change inside the intended UI and test files.

filled-example.md 
Cursor task:
- Add a "marketing email" toggle to notification preferences.

Open context:
- Read: src/settings/notifications/*
- May edit:
  - src/settings/notifications/PreferenceForm.tsx
  - src/settings/notifications/PreferenceForm.test.tsx
- Do not edit:
  - src/api/preferences.ts
  - src/auth/*

Acceptance criteria:
- [ ] Given the user disables marketing email, when they save, then the form sends marketingEmail=false.
- [ ] Given the save request fails, when the error returns, then the previous toggle state is restored and an error message is shown.
- [ ] Given the user lacks preferences.write, when the page loads, then the toggle is disabled.

Verification:
- npm test -- PreferenceForm
- Screenshot: disabled state and error state.

How To Keep Cursor Inside The Spec

Cursor is strongest when it can see enough context to make a good change, but that same context can tempt it to rewrite nearby abstractions. Treat this template as a workspace boundary: the agent may inspect broadly, edit narrowly, and explain every changed file against the criteria.

Separate reading from editing

Give Cursor read access to the module, tests, API client, and design context it needs, but keep the writable list much smaller. This distinction is especially important in UI folders where shared hooks, generated clients, and theme utilities sit close to feature code.

Pin the contract

Before generation, name the props, endpoint shape, event payload, permission rule, or copy string that must remain stable. Cursor can then use those details as guardrails instead of inventing a cleaner contract that breaks callers or tests outside the current change.

Review the diff path

After the edit, compare actual changed files with the allowed write scope before reading implementation style. If the diff touched shared utilities, generated files, schemas, or unrelated tests, send it back to the spec instead of accepting the wider change quietly.

Review Questions Before Adoption

Cursor AI Coding 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 Cursor AI Coding 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 cursor-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

Read scope equals write scope

Cursor can inspect a folder, but that should not mean it can rewrite the folder.

Prompting for style

Asking for a cleaner implementation invites refactors that are hard to review.

No UI state evidence

For UI changes, a test command alone is not enough when disabled, empty, or error states matter.

Related Resources

These resources help you move from Cursor prompt to spec packet and review evidence.

Claude Code Spec Template

Use the same bounded handoff pattern when working in Claude Code.

Compare template

AI Coding Acceptance Criteria

Turn each Cursor task into pass/fail behavior before generating code.

Write criteria

AI PR Review Checklist

Check whether Cursor respected the requested scope and evidence bar.

Review diff

Cursor Spec FAQ

Should I paste the whole repository context into Cursor?

No. Give Cursor enough context to understand the task, but separate read scope from write scope so it does not broaden the diff.

What is the most important field?

The may-edit list. It gives the reviewer a concrete way to reject scope drift.

Can I use this for tiny edits?

For copy-only edits, a lighter note is fine. Use the full template when behavior, contracts, permissions, or tests are involved.

Before the next Composer request, write the scope and criteria first. Cursor becomes much easier to review when the spec is already sharp.

Generate spec packet