“Fix the login bug” is a sentence, not a prompt. It’s the kind of instruction that gets a coding agent to change five files, three of which weren’t broken, in a diff that takes longer to review than the bug would have taken to fix by hand. The frustrating part is the agent isn’t malfunctioning — it did exactly what a vague instruction invites: guessed at scope and filled in the gaps with its own assumptions.
The skill that separates a useful agent session from a frustrating one has almost nothing to do with the model and almost everything to do with the prompt. Writing better prompts for AI coding agents means being specific about scope, context, and constraints before the agent writes a single line, and it’s a skill that pays off immediately — the same agent, given a sharper prompt, produces a diff you can approve in thirty seconds instead of one you have to unwind.
Start With Scope, Not Just the Goal
A goal (“add dark mode”) tells an agent what to build but not where its responsibility ends. Scope tells it where to stop. Compare:
- Vague: “Add dark mode to the app.”
- Scoped: “Add a dark mode toggle to the settings screen that switches a CSS class on
<body>. Don’t touch the color values themselves yet — just wire up the toggle and persist the choice in localStorage.”
The scoped version tells the agent exactly what “done” looks like, which means it stops there instead of continuing to touch adjacent files it decided were also relevant. Every extra file an agent touches is extra diff you have to read, so tightening scope is directly a review-time savings.
Give Context the Agent Can’t Infer
Agents are good at inferring patterns from the code they can see, but they can’t infer decisions that only exist in your head — why a certain function is written the awkward way it is, which dependency is deprecated, which test file is intentionally skipped. Front-load that context rather than letting the agent discover it the hard way:
Context: This repo uses Zustand for state, not Redux — don't add Redux.
Context: `legacy/auth.js` is deprecated; new code should use `auth/session.ts`.
Task: Add a "remember me" checkbox to the login form that extends the
session TTL to 30 days. Only touch files under `auth/` and the login form
component.
That kind of prompt takes thirty extra seconds to write and reliably saves ten minutes of cleanup, because the agent isn’t guessing at constraints you already knew.
A Prompt Structure That Holds Up
For anything beyond a one-line fix, a consistent structure keeps prompts from missing the details that matter:
| Section | Purpose | Example |
|---|---|---|
| Context | Facts the agent can’t infer from the code alone | “We use Zustand, not Redux” |
| Task | The specific, scoped change | “Add a remember-me checkbox” |
| Constraints | What to avoid touching or changing | “Don’t touch the legacy auth file” |
| Definition of done | How you’ll know it’s finished | “Session should persist 30 days; add a test” |
Not every prompt needs all four sections spelled out explicitly, but thinking through them before you type catches the ambiguity that would otherwise show up as an oversized diff twenty minutes later.
Iterating Instead of Starting Over
When an agent’s first attempt misses the mark, the instinct is often to scrap it and rewrite the prompt from scratch. Usually a shorter follow-up works better, because the agent still has the context of what it just did:
Good: "That's close, but move the toggle into the existing SettingsRow
component instead of adding a new one."
Wasteful: starting a brand new session with a longer prompt that re-explains
everything from zero.
Treat the first prompt as a draft and the follow-up as the real editing pass — it’s usually faster than trying to write one perfect prompt up front, and it mirrors how you’d actually review a junior engineer’s first attempt at a task.
Show, Don’t Just Tell, When You Can
Language is often the fastest way to communicate intent, but it’s not always the clearest. When a change involves layout, a specific error message, or a visual bug, a screenshot or a short code snippet pinned to the prompt removes an entire category of misunderstanding. Describing “the button that’s too close to the edge” in words invites the agent to guess which button and which edge; pointing at a screenshot doesn’t.
This is part of why annotated screenshots have become a standard part of serious agent workflows — see screenshot-driven development for the broader case. The same logic applies to code: pasting the exact error message or stack trace into a prompt is almost always faster than describing the error in your own words, since the agent can pattern-match against the literal text instead of your paraphrase of it.
Common Prompting Mistakes Worth Naming
A few habits show up often enough to call out directly:
- Compound prompts. Asking for three unrelated changes in one message makes the resulting diff harder to review and harder to revert if only one part goes wrong. Split unrelated asks into separate prompts, even if it means separate sessions.
- Assuming the agent remembers yesterday. Unless you’re continuing the same session, the agent doesn’t know about a decision from last week’s conversation. Restate the relevant context rather than assuming continuity.
- Vague success criteria. “Make it faster” is not verifiable. “Reduce the initial render time below 200ms” is. Agents work better against a target they can check against, and so do you when reviewing the result.
- Not specifying what to leave alone. Agents don’t know which parts of a file are stable and which are a work in progress unless you say so explicitly.
None of these are exotic mistakes — they’re the same ones that make instructions to a new human collaborator go sideways. The discipline of writing a clear prompt for an AI agent is, underneath it, the same discipline as writing a clear ticket for a teammate. The field of study around this, prompt engineering, has grown into its own body of technique precisely because the wording of a request measurably changes the quality of what comes back.
Isolating Each Prompted Task
One habit compounds the value of good prompts: giving each task its own isolated workspace so a bad first attempt doesn’t tangle with a good one. Running each prompted task in its own git worktree means you can throw away a session that went sideways without touching anything else, and it keeps your prompt-and-review loop clean — you’re reviewing one task’s diff at a time, not several mixed together.
Getting Started
- Before your next agent session, write out context, task, and constraints as three separate lines — even for a task that feels simple.
- Watch the diff that comes back and note anywhere the agent guessed at something you didn’t specify; that’s the gap to close in your next prompt.
- When a first attempt is close but not right, iterate with a short follow-up rather than restarting with a longer prompt.
- Run each prompted task in its own isolated space so a messy first attempt never bleeds into your next one — Agents gives every session its own worktree, branch, and diff panel automatically, with a 7-day free trial to try the workflow.
Better prompts don’t make agents smarter — they make the gap between what you meant and what the agent assumed smaller, which is where almost all wasted diffs come from. Pair sharper prompts with a clean diff review workflow and most of the friction in agent-driven coding disappears.