Prompt Patterns for Coding Agents

Why prompting a coding agent is different

A chatbot answers once; a coding agent works in a loop, reading your repository, editing files, running your tests and reacting to the results. That changes what a good prompt has to do. You are not asking for a snippet, you are briefing a teammate who will take real actions in your codebase, so the prompt has to carry intent (what you want and why), constraints (your stack, conventions and what not to touch), and a definition of done the agent can check itself against. The single biggest lever is moving the standing rules out of the prompt entirely: put your stack, conventions and quality gate in a CLAUDE.md or AGENTS.md so every prompt starts from your rules, and the prompt itself only has to carry the task. The patterns below assume that foundation and focus on the per-task brief.

• The agent acts: it edits files and runs commands, so vague intent becomes wrong changes, not just a wrong sentence.
• Standing rules belong in CLAUDE.md or AGENTS.md, not re-typed every prompt; see How to Use Claude Code.
• A good per-task prompt carries intent, constraints and a checkable definition of done.
• Context is finite: a focused prompt leaves room for the agent to read code and think. See the glossary on the context window.

Pattern 1: role and spec

The most reliable opening is to state the role the agent should adopt and then specify the task as a tight, testable spec rather than a wish. A spec names the goal, the constraints, the files or area in scope, and the acceptance criteria that decide when it is done. "Make the login better" is a wish; the version below is a spec. The role line focuses the model (a senior engineer reviews differently than a tutor), and the acceptance criteria give the agent something concrete to verify against, which is what stops it from declaring victory early. Keep the spec to what matters: over-specifying every line removes the agent's ability to make good local decisions.

Role: act as a senior backend engineer on this codebase.

Goal: add rate limiting to the public /api/contact endpoint.

Constraints:
- Use the existing Convex rate-limit helper; do not add a new dependency.
- Limit to 5 requests per minute per IP. Return 429 with a clear JSON body.
- Touch only the contact route and its test; leave other endpoints alone.

Done when:
- A new test proves the 6th request in a minute gets a 429.
- `bun run lint && bun run typecheck && bun run test` all pass.

Plan first (do not edit yet), show me the plan, and wait for my go-ahead.

Pattern 2: show an example (few-shot)

Models match patterns, so the fastest way to get output in the shape you want is to show one. When you need a new file, component, test or migration that should look like the ones you already have, point the agent at an existing example and ask it to follow the same structure: "Write the new endpoint the same way as src/api/users.ts, including its test file." This few-shot pattern works because your codebase is the best style guide you have, and it beats describing your conventions in prose. For output you cannot point at, give a tiny inline example of the format you expect (a sample log line, a JSON shape, a commit-message style) so the agent has a target to match.

• Point at an existing file: "Follow the structure of src/api/users.ts and its test."
• Your codebase is your style guide; an example beats a paragraph of conventions.
• For new formats, inline a tiny sample of the exact output you want (a log line, a JSON shape).
• One sharp example usually outperforms several vague instructions.

Pattern 3: decompose big work into steps

Large, vague requests are where agents drift: asked to "build the dashboard" they make a hundred decisions you would have made differently and bury the mistakes in a giant diff. The fix is decomposition. Either break the work into a sequence of small, separately reviewable tasks yourself, or ask the agent to propose a plan first and approve it before any code is written. Plan-first is the highest-leverage habit with coding agents: a wrong direction caught in a plan costs nothing, while the same mistake caught after a thousand-line diff costs real time. In Claude Code this is plan mode (Shift+Tab); in any agent you can simply instruct "plan first, do not edit, show me the steps." Then implement one step, review, and move to the next.

• Split a big task into small, separately reviewable steps rather than one mega-prompt.
• Ask for a plan before edits; correcting a plan is free, correcting a huge diff is not.
• Implement one step, review the diff, then continue; keep each change small enough to read.
• Smaller steps also keep the context window clean, so the agent stays sharp across the task.

Pattern 4: build a verification loop

The defining feature of a coding agent is that it can run things, so the best prompts tell it how to check its own work and to keep going until the check passes. Instead of "fix the failing test," say "run the test suite, fix what is red, and run it again; do not stop until it is green." Instead of trusting that a change works, tell the agent to run the type checker, the linter and the tests, and to read the actual output rather than assume. This turns the agent from a one-shot generator into a closed loop that grounds itself in real results. The strongest version bakes the loop into your project so it is not even a prompt: hooks that run your gate automatically (see the Claude Code Hooks guide) mean the agent is held to the standard whether or not you remember to ask.

• Ask the agent to run the gate (types, lint, tests) and to read the real output, not assume.
• Make it iterate: "keep fixing and re-running until the suite is green," not a single pass.
• For UI or behaviour, have it run the dev server or a Playwright check so it sees the real result.
• Automate the loop with hooks so verification happens every time, not only when you remember.

Pattern 5: give the agent the right context, not all of it

Agents fail more often from missing context than from a weak model: asked to use an API without its docs, they guess. So bring the agent what it needs, deliberately. Point it at the relevant files, paste the error in full, link the doc, name the exact function. But resist the opposite trap of dumping everything: a context window stuffed with twenty files and a long history degrades quality, because the model loses the important detail in the noise (the "lost in the middle" effect). The skill is curation: enough context to succeed, little enough to stay sharp. This is the heart of context engineering, and our Context Engineering guide goes deep on managing the window across a long task.

• Name the exact files, paste the full error, and link the doc the agent needs.
• Do not dump the whole repo; relevant context beats maximum context every time.
• Watch for "lost in the middle": key detail buried in a huge prompt gets ignored.
• See the Context Engineering guide and the glossary on the context window and the system prompt.

Anti-patterns to avoid

Most prompting pain comes from a short list of repeatable mistakes. Naming them makes them easy to catch in your own habits. The cure for every one is a pattern above: be specific, show an example, decompose, verify, and curate context.

• Vague wishes: "make it better" gives the agent nothing to verify against. State a spec and acceptance criteria.
• The mega-prompt: one huge request that buries a hundred decisions in an unreviewable diff. Decompose and plan first.
• Trust without verification: accepting output you did not ask the agent to test. Build a verification loop.
• Context dumping: pasting everything so the signal drowns. Curate to what the task needs.
• Re-typing rules every turn: stack and conventions belong in CLAUDE.md or AGENTS.md, not each prompt.
• Politeness as instruction: "please try to maybe" reads as optional. Be direct; constraints are rules, not suggestions.

Frequently asked questions

Keep learning