How to write prompts for coding agents

Coding agents such as Claude Code, Codex or Cursor act on your repository: they read files, run commands and edit code. A prompt for them is closer to a work ticket than to a question. The clearer it is about scope, checks and when to stop, the less you have to undo.

What a coding-agent prompt should state

• The goal in one sentence, with the observable symptom for a bug: what happens, and what should happen instead.
• Where to look: the files, modules or commands involved, and the project instructions file if your repository has one.
• Constraints: what must not change, such as public APIs, dependencies, database schema or unrelated files, and whether to commit.
• A definition of done the agent can check itself: a failing test that must pass, a command that must succeed.
• When to stop and ask: before destructive actions, schema changes, or when the cause is not what you described.
• What to report: what it changed, which checks it ran and their results, and what it could not verify.

A reusable bug-fix template

<GOAL>
Fix the bug where {{symptom}}. Expected behaviour: {{expected}}.
</GOAL>

<CONTEXT>
Repository: {{repo}}. The relevant code is in {{files}}. Read the project instructions file before you start.
</CONTEXT>

<CONSTRAINTS>
Find the root cause before editing. Keep the change minimal and match the surrounding code. Do not change public APIs, dependencies or unrelated files. Do not commit or push.
</CONSTRAINTS>

<DONE_WHEN>
A regression test fails before the fix and passes after it, and {{check_command}} passes.
</DONE_WHEN>

<STOP_AND_ASK>
Before deleting data, changing a schema or touching other modules, or if the cause turns out to be different from this description.
</STOP_AND_ASK>

<REPORT>
Summarize the cause, the change, the commands you ran with their results, and anything you could not verify.
</REPORT>

The variables keep the template reusable across bugs. Fill it in with the template filler before pasting it into your agent.

Common mistakes

• Several tasks in one prompt. "Fix the bug, refactor the module and update the docs" produces one large change that is hard to review. Ask for one, review it, then ask for the next.
• No way to verify. Without a test or command, the agent can only claim success. Name the check.
• Guessing at the fix. Describe the symptom and ask for the root cause, rather than prescribing a change you have not confirmed.
• Unstated limits. If the agent must not touch deployment files or push to a shared branch, say so.

Check a draft with the prompt checker, and see what makes a good prompt for the general structure.