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.

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