How to Prompt a Coding Agent: Write a Brief It Can Finish

To prompt a coding agent well, write a short brief, not a wish: state the goal, give the context it can’t find on its own, list the constraints, and define a finish line it can check by itself. Agents fail most often because the task never said what “done” looks like. Fix that, and the same agent suddenly looks much smarter.

Below is a template you can reuse, plus the reasoning behind each part.

Why coding agents need briefs, not prompts

A chatbot answers one message. A coding agent works for many steps, reading files, editing, running commands, and deciding what to do next. Every one of those decisions leans on your original instructions.

That changes what a good prompt looks like. A vague request in a chat produces a vague answer you can immediately correct. A vague request to an agent produces twenty minutes of confident work in the wrong direction. We go deeper on this shift in prompting AI agents vs prompting chatbots.

Think of it as delegating to a capable new hire who has never seen your project and can’t ask you questions mid-task.

The five parts of a good brief

1. The goal, in one or two sentences

Say what should be true when the work is finished, from the user’s point of view.

• Weak: “Fix the login.”
• Strong: “Users who enter a wrong password should see an inline error under the password field instead of a blank page.”

A good goal describes an outcome, not a list of code edits. Let the agent figure out which files to touch.

2. Context the agent can’t discover

The agent can read your code. It can’t read your mind. Include only what isn’t already in the repository:

• Why the change matters, if it affects choices (“this page is used on mobile, keep it light”).
• Related decisions (“we’re moving away from the old API client; use the new one”).
• Where to look first, if the codebase is large (“the checkout flow lives in the payments folder”).
• Links to an issue, an error log, or a screenshot description.

Skip things it can figure out. Long briefs bury the important parts.

3. Constraints

Constraints prevent the most common surprises: an agent “helpfully” rewriting half the project.

• What not to change (“don’t modify the database schema”).
• Libraries to use or avoid (“no new dependencies”).
• Style rules (“match the existing component patterns”).
• Scope limits (“only the settings page; other pages come later”).

4. A finish line it can verify

This is the most important part, and the one most people leave out. Give the agent a way to prove it’s done:

• “All existing tests pass, and add a test for the wrong-password case.”
• “The build succeeds with no new warnings.”
• “Running npm run lint reports no errors.”
• “The page loads at /settings and the toggle persists after refresh.”

An agent with a checkable finish line will run the check, see failures, and keep fixing. An agent without one stops when it feels done.

5. What to report back

Ask for a short summary so reviewing is fast:

• What changed and why.
• Anything it was unsure about or couldn’t do.
• Follow-up suggestions, kept separate from the work itself.

A reusable brief template

Copy this and fill it in:

Goal:
<one or two sentences describing the outcome>

Context:
- <why it matters / relevant decisions>
- <where to start looking>

Constraints:
- <what not to touch>
- <dependencies, style, scope>

Done when:
- <tests/build/lint that must pass>
- <behavior a person could check>

Report:
- Summarize changes, open questions, and suggested follow-ups.

Example: a filled-in brief

Goal:
Add a "Export as CSV" button to the orders table so admins can
download the currently filtered orders.

Context:
- Admins asked for this to share data with accounting.
- The table component is in the admin dashboard folder.

Constraints:
- No new dependencies; build the CSV by hand.
- Don't change the table's existing filtering logic.

Done when:
- Existing tests pass.
- A new test checks the CSV header row and one data row.
- The button only exports rows that match the active filters.

Report:
- List changed files and anything you weren't sure about.

Sizing the task

Even a perfect brief fails if the task is too big. A good rule: if you can’t describe “done” in a few bullet points, split the task.

Too big	Better split
“Build user accounts”	Signup form → login → password reset → account settings
“Redesign the dashboard”	New layout shell → move widgets → update styles → remove old code
“Improve performance”	Measure slow pages → fix the slowest query → add caching to one endpoint

Smaller tasks are easier to review, easier to undo, and much more likely to finish cleanly.

Common mistakes

• Describing the solution instead of the problem. If you dictate every edit, you lose the agent’s ability to find a better approach.
• No finish line. “Make it work” is not checkable.
• Burying the key rule. Put the one constraint that really matters near the top.
• Mixing several tasks. “Fix the bug, also refactor auth, and update the docs” invites half-finished work on all three.
• Assuming it knows your conventions. Write recurring rules into a project instructions file instead of repeating them in every brief.

Make repeated instructions permanent

If you find yourself pasting the same paragraph into every brief, move it out of the brief:

• Project instructions files hold commands, conventions, and rules the agent reads at the start of each session.
• Agent Skills package a repeatable procedure, such as “how we write database migrations,” as a SKILL.md file the agent loads when relevant. See what are Agent Skills.

Your briefs then stay short and focused on the task itself.

Briefs in a team of agents

When several agents work together, the brief becomes even more important, because one agent’s output is another’s input. In BotQuarters, a team lead agent writes these briefs for you: it turns your goal into scoped tasks with clear finish lines, assigns them to teammates, and runs the project’s tests before accepting any work. The same principles apply whether you write the brief or a lead agent does.

For a wider view of how agents fit into a workflow, read the beginner’s guide to AI coding agents.

FAQ

How long should a prompt for a coding agent be?

Usually a short paragraph for the goal plus a few bullets each for context, constraints, and the finish line. Long enough to remove guesswork, short enough that the important rules stand out. If it grows past a page, the task is probably too big.

What is the most important thing to include in a coding agent prompt?

A verifiable finish line, such as tests that must pass or a behavior a person could check. Agents use it to test their own work and keep fixing until it passes, which dramatically improves results.

Should I tell the agent exactly which files to change?

Only if you know it matters. It’s usually better to describe the outcome and point to where to start looking. Over-specifying the edits stops the agent from finding a cleaner solution.

Why does my coding agent keep doing more than I asked?

It’s filling gaps in the brief with its own judgment. Add explicit constraints on scope, like “only change the settings page” or “no new dependencies,” and ask it to list suggested follow-ups separately instead of doing them.