Effective prompting techniques for coding agents

Effective prompting techniques for coding agents are five patterns that turn a vague request into checkable work: the agent asks its questions before it codes, the prompt states the constraints and the command that proves the result, an existing file serves as the pattern, planning precedes implementation, and review covers the evidence instead of every line.

This page is for developers who drive Claude Code, Codex or Cursor every day, and for tech leads who want the whole team to prompt the same way. You ask for “user authentication with email verification”. The agent picks a session strategy you would never ship, wires in a mailer you do not use, writes tests that mock everything, and reports success. Every one of those choices was a gap in the prompt that the model filled with a default.

What these prompting techniques give you on a real task

• A clarification prompt that surfaces missing requirements before any code exists
• A constraints-and-check template that tells the agent what “done” means as a command it can run
• A plan-then-implement loop that stops architectural mistakes while they cost a sentence to fix
• Recovery prompts for a stuck debugging loop, a self-review pass and a cleaner second draft
• An evidence report you can check in two minutes instead of reading a 600-line diff
• The per-tool levers (project instructions, file references, reasoning effort, context hygiene) that fix quality before you touch the model

Why does the same model produce good and bad code?

A coding agent treats everything you leave unsaid as a decision it is allowed to make. Each technique below closes one kind of gap:

Gap in the prompt	What the agent does	Technique that closes it
Requirements you have not stated	Guesses a plausible default	Ask for questions first
Library, config and error behaviour	Improvises	State constraints
“Done” is undefined	Stops when the code looks done	Name the check it must run
Your house conventions	Invents its own	Point at an existing file
The approach itself	Commits to the first idea	Plan, then implement one step

The order matters. Questions come first because the answers change the constraints; the check comes before the plan because a plan without a check cannot be accepted or rejected.

Ask the agent to question you before it writes code

End any request larger than a one-line fix by asking the agent what it needs to know. The agent exposes its assumptions while they are still cheap to change, and you answer them in one message instead of un-picking them from a diff.

Copy-paste prompt: clarify before coding

I need user authentication with email verification for this Express + PostgreSQL app.
Before writing any code, read the existing auth-related files, then ask me the questions
whose answers would change the design: session vs token strategy, which mailer we use,
token expiry, rate limiting, and anything you found in the code that conflicts.
Ask at most seven questions, most important first. Do not edit any file until I answer.

The cap on questions matters. Without it, some sessions return twenty trivial questions and the important one is buried at number fourteen. Anthropic’s Claude Code best practices describe a longer variant for large features: the agent interviews you with its AskUserQuestion tool and writes the result to a spec file, and you implement it in a fresh session (Claude Code best practices, checked 2026-09-26). A written spec is the input the rest of the artifact chain builds on.

The same closing line works across the lifecycle: “ask what you need to write the best spec”, “ask what you need to plan this”, “ask for any context that would help diagnose this failure”.

State the constraints and the check the agent must run

Vague requests get generic code. Name the library, the configuration source, the failure behaviour and, most importantly, the command that decides whether the work is finished.

• Instead of: “Add a database connection.”
• Write: “Add a PostgreSQL connection using the pg library. Read the connection string from DATABASE_URL. Retry with exponential backoff, at most five attempts. Export a typed healthCheck() function. Done when npm test -- db passes and npm run typecheck is clean.”

The last sentence does the most work. Anthropic’s best practices put it plainly: without a check the agent can run, “looks done” is the only signal available, and you become the verification loop (Claude Code best practices, checked 2026-09-26). With a check, the agent runs it, reads the failure and iterates on its own.

Copy-paste prompt: constraints plus a done-when check

Add rate limiting to POST /api/login.
Constraints:
- Use the existing Redis client in src/lib/redis.ts; add no new dependency.
- 5 attempts per IP per 15 minutes; respond 429 with a Retry-After header.
- Do not change the login response shape for successful requests.
Done when:
- A new test in tests/api/login.test.ts proves the 6th attempt returns 429.
- `npm test` and `npm run lint` both pass.
Do not edit or delete existing tests. Run both commands and paste their final lines.

“Do not edit or delete existing tests” is not decoration. An agent that cannot make a check pass will sometimes weaken the check instead; the protect-the-oracle page covers how to enforce that mechanically. For turning a user story into checks like these, see executable acceptance criteria.

Point at an existing file instead of describing the convention

To make the agent match your codebase, show it a file that already follows the convention. A concrete example is a tighter specification than a paragraph of prose, and it carries details you would forget to mention: error types, logging calls, naming, export style.

• Instead of: “Create a service class with a constructor, a private logger, and JSDoc on public methods.”
• Write: “Create PaymentService following the structure of src/services/AuthService.ts: same constructor injection, same error classes, same logging. Do not copy its TODO comments or its deprecated legacyLogin method.”

Pick a file that has been reviewed recently, and say what not to copy. The agent reproduces the example faithfully, including its mistakes. Each tool also has a way to attach the file directly, shown in the per-tool section below.

Plan first, then implement one step at a time

For anything bigger than a small fix, separate thinking from doing. The agent proposes a plan with no code; you correct the plan; then it implements one step and stops.

1. Ask for a plan and forbid edits. Switch the tool to its read-only planning mode (see agent mode vs ask mode for the exact switch in each tool), then send:

   Copy-paste prompt: plan only

   Plan a feature that lets users upload a profile picture (max 2 MB, JPEG or PNG,
   stored in our existing S3 bucket via src/lib/storage.ts).
   Produce a numbered plan: for each step, the files you will create or change,
   what changes, and the test that proves the step works.
   Flag every assumption you are making. Do not write or edit any code.

2. Correct the plan, not the code. The plan comes back as a numbered list. Fix it while it is still text: “Use a separate AvatarUpload component instead of editing ProfilePage. Validate the MIME type on the server, not only in the browser.”

3. Implement one step and stop.

   Copy-paste prompt: execute one approved step

   The plan is approved with my corrections. Implement step 1 only.
   Run the test you named for step 1 and paste the result.
   Then list any place where you deviated from the plan, and stop.

This loop catches a wrong approach when it costs one sentence to fix, not a 30-file diff. The full discipline, from intent through spec and plan to tasks, is on the artifact chain page.

Do personas make the agent more accurate?

Priming the model with a role (“you are a senior security engineer”) is widely taught, but the evidence does not support it as an accuracy lever. Zheng, Pei, Logeswaran, Lee and Jurgens (“When ‘A Helpful Assistant’ Is Not Really Helpful”, arXiv, November 2023) tested 162 roles across 4 model families and 2,410 factual questions and found that adding a persona to the system prompt did not improve performance compared with no persona, and that the effect of any single persona was “largely random” (paper arXiv 2311.10054, abstract as published in the authors’ repository, read 2026-09-26).

A role still shapes what the model looks at and how it formats the answer. Use it for focus, and let explicit criteria carry the weight:

• Weak: “You are an expert security engineer. Review this code.”
• Strong: “Review src/api/upload.ts for path traversal, missing MIME validation, unbounded file size and SSRF through the URL-import option. For each finding: file, line, exploit sketch, fix.”

A more useful move than one persona is several viewpoints at once, because disagreement surfaces the trade-offs a single answer hides.

Copy-paste prompt: review from several perspectives

Review the design in docs/plans/avatar-upload.md from four perspectives:
security, operations (on-call at 3 a.m.), performance, and the next developer
who has to change this code. For each, give the strongest criticism and the change
it would demand. Then list where the perspectives disagree and what you recommend.

Which prompts get a stuck or finished agent back on track?

Three prompts pay for themselves on almost every task.

Hypothesis before fix. When the agent is thrashing on a bug (edit, re-run, revert, repeat), stop it and force a measurement instead of another guess. The error-driven development page builds a whole workflow on this.

Copy-paste prompt: stuck debugging

Stop changing application code. List 5-7 possible causes of this failure,
narrow them to the 1-2 most likely with your reasoning, then add logging or a
failing test that would confirm or rule out each one. Run it and show me the
output before you propose any fix.

Self-review against the request. A second pass over the agent’s own diff, checked against what you asked for, catches scope creep and forgotten requirements. It is a filter, not proof; the next section covers proof.

Copy-paste prompt: self-review pass

Go through every change you made in this session and check it against my original
request. For each requirement: implemented fully, partially, or not at all?
Then list every change I did not ask for, including formatting, renamed symbols and
edited tests. Report first; do not fix anything yet.

The second draft. The first working version is often exploration. Once the tests pass, the agent knows enough to write a simpler version behind the same tests.

Copy-paste prompt: cleaner rewrite behind green tests

This works and the tests pass. Knowing what you learned, rewrite the implementation
to be simpler: fewer moving parts, clearer names, less code, same behaviour.
Do not touch the tests. Run the full test suite and the linter after the rewrite
and paste their final lines.

How do you check the result without reading every line?

Prompting well moves the work from reading code to checking evidence. Build the evidence into the prompt, then let machines and a second reviewer do the reading.

1. The check is in the prompt. Every implementation prompt ends with “done when” commands (tests, types, lint), and the agent pastes their output. A missing or red result means the task is not done, whatever the summary says.

2. The agent writes an evidence report. Ask for it at the end of every task:

   Copy-paste prompt: evidence report before handoff

   Before you hand this back, write an evidence report:
   1. Each requirement from my request and the test that proves it (file and test name).
   2. Every command you ran to verify the work, with its exit code.
   3. Every file you changed, one line each on why.
   4. Anything you changed that I did not ask for, and anything you could not verify.
   Keep it under 40 lines.

3. A second reviewer reads the diff, not you. Run an independent review in a fresh context: /code-review in Claude Code, /review or codex review in Codex, or Bugbot on the pull request in Cursor. The agent that wrote the code is a weak judge of it.

4. You sign off on the evidence, CI decides the merge. You read the report, spot-check the tests that prove the riskiest requirement, and read only the files the reviewer flagged. CI runs the same checks again and blocks the merge on red.

What a complete report must contain for a pull request is on the evidence bundle page, and the review routine is on reviewing an agent’s pull request. For code that passes its tests but is still wrong, see catching plausible-but-wrong code.

Where prompting differs in Claude Code, Codex and Cursor

When output quality drops, check the setup before the model: missing project instructions, no file reference, too little reasoning effort, or a context window full of failed attempts. The techniques above are identical in all three tools; the levers differ. Commands below were checked on 2026-09-26 against claude --help 2.1.283 and codex --help 0.157.1, and the Claude Code command reference.

Claude Code

• Project instructions: run /init to generate a CLAUDE.md, then prune it as the project changes.

• Point at files: type @ plus a path in the prompt, for example @src/services/AuthService.ts, to include the file directly.

• Plan first: /plan <description> enters plan mode for that task.

• Reasoning effort: /effort high (or xhigh) before a hard design or refactor; claude --effort high sets it for a session. From v2.1.280 (the latest channel) the default model is Claude Opus 5.5, which runs at medium effort by default, so raise effort before switching model.

• Context hygiene: /context shows what fills the window; /compact <focus instructions> summarises mid-task; /clear starts fresh between unrelated tasks.

• Current library docs: install the Context7 plugin from the official marketplace:

  claude plugin install context7@claude-plugins-official

  Then add “use context7” to a prompt that touches a fast-moving library.

Codex

• Project instructions: /init in the TUI creates an AGENTS.md; keep one per package in a monorepo.

• Point at files: /mention attaches a file, or name the path in the prompt.

• Plan first: /plan switches the TUI to Plan mode.

• Reasoning effort: /model chooses both model and reasoning effort. For a session, pass it as config: codex -c model_reasoning_effort="high". The bundled default, GPT-6 Astra, runs at low effort in Codex by default, so raise effort before switching model.

• Context hygiene: /compact summarises the conversation; /new starts a fresh chat.

• Current library docs: add Context7’s hosted MCP server (the API key is optional and only raises rate limits):

  codex mcp add context7 --url https://mcp.context7.com/mcp

Cursor

• Project instructions: use Rules, which Cursor describes as “system-level instructions to Agent” (Rules docs, checked 2026-08-28).

• Point at files: name the file path in the prompt so the agent edits the existing code instead of recreating it.

• Plan first: Plan Mode “creates detailed implementation plans before writing any code”.

• Current library docs: add Context7 to .cursor/mcp.json:

  { "mcpServers": { "context7": { "url": "https://mcp.context7.com/mcp" } } }

Cursor’s documentation could not be re-checked on 2026-09-26, so this tab holds only what was verified on 2026-08-28, and it names no Cursor model or mode setting.

Which model to run, and when to leave the default, is covered on the models hub. The rule this site follows: start on the tool’s default model, tune effort before switching, and switch only when your own evals say so. For the deeper per-tool prompt catalogues, see Claude Code prompt engineering, Codex prompt engineering and Cursor prompt templates.

Tech leads: once a prompt from this page works for your team, stop pasting it. Commit it as a skill so every developer and every tool runs the same version; see agent skills.

What goes wrong with these prompts, and how do you recover?

• The agent keeps making the same mistake after you corrected it. The context is full of failed attempts. Anthropic’s guidance is to start fresh once you have corrected the same issue more than twice (best practices, checked 2026-09-26). Recovery: /clear in Claude Code or /new in Codex, then send one prompt that includes what you learned.
• The clarification step returns trivial questions. Recovery: cap the number, demand “questions whose answers would change the design”, and ask it to read the code first so it does not ask what the repository already answers.
• The agent copied the example file’s bugs. Recovery: pick a recently reviewed file and add “do not copy” lines for known debt.
• The implementation drifts from the approved plan. Recovery: implement one step per prompt and require a “deviations from the plan” list at the end of each step.
• Self-review reports that everything is fine. Self-review filters; it does not prove. Recovery: rely on the check commands and an independent reviewer in a fresh context, as in the verification steps above.
• The check passes because the agent edited the check. Recovery: forbid test edits in the prompt, diff the test directory before accepting, and make the checks read-only to the agent as described in protect the oracle.
• The code targets an old library API. Recovery: add Context7 or paste the current docs page; see documentation as context.
• Quality drops late in a long session. Recovery: check context use (/context in Claude Code) and compact or restart; see context windows.

Where to go next with prompting

• The artifact chain: intent, spec, plan and tasks, the structure these prompts feed
• Agent mode vs ask mode: when the agent may edit and when it may only plan
• Executable acceptance criteria: turning “done when” into failing tests before implementation
• Error-driven development: the hypothesis-first debugging loop in depth
• The evidence bundle: what an agent’s pull request must prove