Coding · guidance updated 4 Oct 2026
Cursor prompt guide
Cursor Agent runs Cursor's own Composer 2.5 and Grok 4.x models, plus Claude Opus/Sonnet 5.5, GPT-5.6 and Gemini 3.x; Auto routes requests. Cursor adjusts the agent for each model, so prompts don't need to be model-specific.
How to prompt Cursor
- Say the outcome and acceptance criteria first: what should be true when the task is done.
- Use Plan mode (Shift+Tab) for multi-file, ambiguous or architectural work, and edit the plan before building.
- @-mention the exact files or folders you know matter (@src/auth/), or leave them out and let Agent search.
- Point to an existing file as the pattern to follow.
- Name constraints: libraries allowed, files not to touch, no new dependencies.
- Ask the agent to run tests, lint or build and fix failures before finishing.
- Attach @Terminals output or the exact error text when debugging.
- Use @Branch or @Commit diffs for reviews of in-progress work.
- Keep team conventions in .cursor/rules/*.mdc (Always, Intelligent, glob or Manual) or AGENTS.md, under 500 lines each.
- Use /goal for long-running objectives such as fixing flaky tests until green.
- Keep each chat to one task and start a new chat for unrelated work.
The shape of a good prompt
[Goal and why] [Relevant context: @files, @folders, pattern to follow] [Requirements / acceptance criteria] [Constraints: don't touch, no new deps] [Verification: tests/build to run] [Mode: plan first if multi-file]
Avoid
- Vague asks like 'fix the bug' with no symptom or location
- @-mentioning large unrelated folders, which floods the context
- Restating the style guide in prompts instead of using rules or linters
- Rules files that are bloated or duplicate what's already in the code
- Mixing several unrelated tasks in one chat
Example
Request add dark mode
Add a dark mode toggle to the app. Context: theme tokens live in @src/styles/tokens.css; follow the pattern in @src/components/LanguageSwitcher.tsx for the settings control. Requirements: - Toggle in the header with Light / Dark / System options - Persist the choice in localStorage; default to System (prefers-color-scheme) - No flash of the wrong theme on first load - All existing components must read colours from CSS variables, with no hard-coded hex values Constraints: no new dependencies; don't change component APIs. Use Plan mode first: list the files you'll change. Then implement, run `npm run lint && npm test`, and fix any failures.
