How to Prompt Cursor and AI Coding Agents: A Practical Guide (2026)

Coding agents changed what a prompt is. In a chat window, a prompt asks for an answer. In Cursor, Claude Code, Codex or Copilot's agent mode, a prompt hands over a task to something that reads your files, edits them and runs commands. A vague answer costs you a reread. A vague task costs you a diff you have to untangle.

We wrote a dedicated guide on how to use Claude Code. This one is broader: the prompting habits that carry across all four tools, plus the places where their setup differs. Let's break it down in the order you'd actually work: scope, brief, context, rules, plan, verify, review. Tool details were checked against each vendor's docs on November 3, 2026.

1. Scope the Task to One Reviewable Change

The most common failure isn't a bad sentence. It's a task that's too big or too blurry to review. "Refactor the backend" has no finish line. "Move the pricing calculation out of the checkout component into src/lib/pricing.ts, with no behavior change" does.

OpenAI's Codex best-practices guide lists "using one chat for an entire project instead of one chat per coherent outcome" as a common mistake. Cursor's agent guide makes the same point from the other direction: start a new conversation when you switch tasks, or when the agent's effectiveness starts dropping. Old context isn't free; the agent keeps reading it.

A quick test before you hit enter: could you review the resulting diff in one sitting and say yes or no? If not, split the task.

In practice, the right size for an agent task is the size of a pull request you'd want to review.

2. Write the Brief: Goal, Context, Constraints, Done When

OpenAI's Codex guide suggests four parts for every prompt, and they work just as well in Cursor, Claude Code and Copilot:

Here's the difference in a real-looking prompt. Cursor's agent best-practices post uses this contrast: "add tests for auth.ts" versus a prompt that names the edge case, the test patterns to follow and the constraint to avoid mocks. Written as a brief:

Goal: Add tests for the session-expiry path in src/auth/session.ts.
Context: Follow the patterns in src/auth/login.test.ts. The bug we
care about is a token that expires mid-request.
Constraints: Use the real token helpers; don't mock them.
Done when: The new tests run with `npm test -- src/auth` and the
expiry case fails on the current code.

This compact brief cuts most of the guesswork.

If a task brief doesn't say what "done" means, the agent decides for you.

3. Give Context Without Dumping the Repo

Agents can search your codebase, so you don't need to paste it. Cursor's guidance is a good rule of thumb across tools: if you know the exact file, tag it; if you don't, the agent will find it.

What's worth handing over directly is anything the agent can't find by reading code:

• The exact error. Paste the stack trace or test output rather than describing it.
• A screenshot of the broken UI or the design you're matching.
• The file you mean, by reference: @src/billing/format.ts in Cursor or Claude Code.
• Prior work. In Cursor, @Chats pulls in a past conversation selectively instead of copying a whole thread.
• Decisions made outside the repo. "We're deprecating the v1 API next quarter, so don't add endpoints to it."

What not to hand over: a wall of every file you think might be related. Extra context isn't neutral; it competes for attention with the context that matters.

4. Put Standing Rules in the Instruction File, Not the Prompt

If you type "use pnpm, not npm" into every prompt, it belongs in a file. Codex's guide lists "overloading the prompt with durable rules" as a common mistake. Every tool has a place for them:

AGENTS.md is the closest thing to a shared format: Codex, Cursor and Copilot all read it, though how they find nested files differs by tool and surface, as the table shows. If your team uses more than one agent, a root AGENTS.md is a sensible home for the rules they should all follow.

What goes in? The same short list every vendor converges on: the exact build, test and lint commands; conventions the code doesn't make obvious; and corrections you've had to give more than once. VS Code's custom-instructions docs add two useful tips: include the reasoning behind a rule, and skip conventions that standard linters or formatters already enforce.

What doesn't belong: everything. Cursor's advice is to start simple and add a rule only when the agent repeats the same mistake. Codex treats the file as a feedback loop: when the agent gets something wrong, correct it, then have it update AGENTS.md so the next session inherits the fix.

5. Plan First for Anything Ambiguous

For a one-line fix, skip this. For a feature with several valid designs, or a change that touches many files, have the agent research and propose before it edits:

Tell the agent what you want to see in the plan: the files it will change, the approach it chose and why, the tests it will add, and anything it's unsure about.

Here's the habit that saves the most time. Cursor's Plan Mode docs say that when a build doesn't match what you wanted, don't try to fix it through follow-up prompts: revert, make the plan more specific, and run it again. They note this is often faster than fixing an in-progress agent and produces cleaner results. Claude Code's docs land in the same place: after two failed corrections, clear the session and write one better prompt.

A plan is cheap to change; a half-built feature isn't.

6. Give the Agent Something to Verify Against

Agents stop when the work looks finished. Cursor puts it plainly: agents perform best when they have a clear target to iterate against. A test, a build exit code, a type check or a script that diffs output against a fixture all work.

For test-driven work, Cursor's suggested sequence is worth copying:

1. Ask the agent to write tests for the behavior you want.
2. Confirm the tests fail on the current code.
3. Commit the tests.
4. Ask it to implement until they pass, without changing the tests.

Cursor also suggests saying explicitly that you're doing TDD, so the agent doesn't create mock implementations for functionality that doesn't exist yet.

Then ask for evidence, not a summary. Anthropic's Claude Code guide notes that "all tests pass" on its own tells you very little; the command and its output tell you a lot.

When you're done, show the exact command you ran and its full output.
If anything fails, fix it and run it again before reporting back.

7. Review the Diff Like It Came From a Stranger

Cursor's own best-practices post warns that AI-generated code can look right while being subtly wrong. Treat a finished agent task like a pull request from a contributor you haven't worked with before.

Each tool has a review path:

• Cursor: watch the diff as it's generated, run Agent Review afterward, and use Bugbot on pull requests.
• Claude Code: /code-review reviews the diff in a fresh subagent that never saw your conversation.
• Codex: /review can review against a base branch, uncommitted changes, or a specific commit.
• Copilot: Copilot code review reads your custom instructions from the pull request's head branch, so review rules can live in the same files.

One more control worth knowing in Copilot's agent mode: by default, you approve each terminal command it proposes before it runs. Leave that on until you trust the workflow; Codex's guide similarly lists giving the agent full permission to your computer before you understand the workflow as a common mistake.

8. Two Agent Prompts We Ran Through the Optimizer

Below are two rough agent prompts, run through the PromptWizz optimizer. The first targets a generic coding agent ("Other" as the target AI); the second targets Claude, as you'd use it in Claude Code. The optimized versions are unedited. The scores come from PromptWizz's own rubric and rate the prompt, not the code an agent would write, so treat them as a guide rather than a guarantee. We didn't run them in Cursor or any other agent, so there's no generated code here.

Run 1: A feature request

add dark mode to the app. make it look good and make sure nothing breaks

You are a senior frontend engineer experienced in theming systems for React/web applications. Task: Add a dark mode option to the existing app. Context: Assume the app already has a light theme built with CSS variables or a styling library; first inspect the current styles and components to identify hardcoded colors. Steps: (1) Audit the codebase for hardcoded colors, images, and third-party components that need theme support. (2) Implement a theme provider with light/dark/system options, persisted in localStorage and respecting prefers-color-scheme. (3) Convert colors to semantic tokens (e.g., background, surface, text-primary, border, accent) with WCAG AA contrast ratios (4.5:1 for body text). (4) Add a toggle in the settings or header. (5) Verify no regressions: list the existing views and components you tested, and note any you could not verify. Constraints: Do not change existing layouts, spacing, or component behavior; do not add new dependencies unless necessary and justify them if so. Output: Provide a short summary of the approach, the list of files changed with brief descriptions, the code diffs, and a testing checklist. Keep prose concise and use headings for each section.

PromptWizz score: 25 → 88 (free Simple depth, run November 3, 2026)

• Added a senior frontend engineer role and turned "dark mode" into light, dark and system options, saved in localStorage.
• Replaced "make it look good" with semantic color tokens and WCAG AA contrast (4.5:1 for body text).
• Replaced "make sure nothing breaks" with constraints (no layout or behavior changes, no new dependencies without a reason) and a request to list what it tested and what it couldn't verify.
• Added five ordered steps and an output format: summary, files changed, diffs and a testing checklist.

Compare it with the four-part brief in section 2. The optimizer didn't leave placeholders. It assumed a React-style web app with CSS variables or a styling library, and its "done" is a list of the views it tested, not a command. Before you paste it into an agent, swap in your real stack and theme files, and add a test or build command as the check (section 6). The optimizer's own tips make the same point about naming the stack.

Run 2: A refactor

refactor the user service, it's a mess. also add tests

You are a senior software engineer experienced in refactoring legacy code and writing unit tests. Refactor the user service so it is cleaner, more maintainable, and easier to test, without changing its external behavior. Work in this order: (1) read the existing user service and list the main problems you see (duplication, long functions, mixed responsibilities, unclear naming, poor error handling); (2) write characterization tests that lock in the current behavior before changing anything; (3) apply the refactoring in small, reviewable steps, explaining each change; (4) add unit tests for the refactored code covering the happy path, edge cases, and error conditions. Constraints: keep the public API and function signatures unchanged unless you flag the change explicitly, do not add new dependencies, and follow the testing framework already used in the project. Output format: start with a short summary of issues found, then the refactored code, then the test code, then a brief note on anything you were unsure about or could not verify. Keep explanations concise and aimed at a mid-level developer reviewing a pull request.

PromptWizz score: 25 → 90 (free Simple depth, run November 3, 2026)

• Replaced "it's a mess" with a goal: cleaner, more maintainable and easier to test, with no change to external behavior.
• Ordered the work: list the problems, write characterization tests first, refactor in small steps, then add unit tests.
• Added constraints: keep the public API and signatures unless the change is explicitly flagged, add no dependencies, and use the existing test framework. It also asks for a closing note on anything unverified.

"It's a mess" is the classic scope problem from section 1. The optimized version gives the refactor a finish line in terms of behavior (no change to external behavior), but its API rule is softer: signatures can change as long as the agent flags it, so decide whether you'd accept that. It also writes characterization tests first. Those aren't the red-first tests from section 6. Characterization tests should pass on the current code, because they record what it does today; section 6's TDD tests should fail until the new behavior exists. The optimizer's tips ask you to paste the code or its file path and to name the language, framework and test library. We'd also add the exact test command, so the agent has a check to run. Finally, it keeps the refactor and the new tests in one request. If that diff would be too big to review in one sitting, stop after the characterization tests and run the rest as a second task.

A Coding-Agent Brief You Can Copy

Goal: [the change, in one or two sentences]
Context: [files to start from, error output, screenshot, related PR]
Constraints: [patterns to follow, code not to touch, no new dependencies]
Done when: [command that must pass] passes, and [observable behavior].
Plan first: list the files you'll change and anything you're unsure
about. Wait for my approval before editing.
Evidence: show the exact command you ran and its output.

Delete the "Plan first" line for small, familiar changes.

Tighten an agent brief before you hand it over. Paste your rough prompt into the PromptWizz optimizer, pick Claude for Claude Code or Other for Cursor, Codex and Copilot, and get a more structured version with a before-and-after score. It's free to try.

Keep Reading

• How to Use Claude Code: A Prompting Guide for Real Projects
• Best Prompt Engineering Framework for Coding
• ChatGPT vs Claude for Coding

Sources

• Cursor Docs, Rules. https://cursor.com/docs/context/rules
• Cursor Docs, Plan Mode. https://cursor.com/docs/agent/plan-mode
• Cursor, Best practices for coding with agents (January 9, 2026). https://cursor.com/blog/agent-best-practices
• OpenAI Codex, Best practices. https://learn.chatgpt.com/guides/best-practices
• OpenAI Codex, AGENTS.md. https://learn.chatgpt.com/docs/agent-configuration/agents-md
• Anthropic, Best practices for Claude Code. https://code.claude.com/docs/en/best-practices
• GitHub Docs, Adding repository custom instructions for GitHub Copilot. https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
• GitHub Docs, Using agent mode in your IDE. https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/use-copilot-agents/use-agent-mode?tool=vscode
• Visual Studio Code Docs, Custom instructions. https://code.visualstudio.com/docs/agent-customization/custom-instructions
• GitHub Docs, Adding repository custom instructions in your IDE. https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/configure-custom-instructions/add-repository-instructions-in-your-ide