How to Brief an AI Coding Agent: A Plain-English Guide

If you want to know how to brief an AI coding agent, the short answer is this: describe the result you want in business terms, point to where it lives, say what must not change, and say how you will know it works. The agent can infer a lot, but it cannot read your mind. Anthropic's guide to Claude Code puts it this way: Claude "can infer intent, but it can't read your mind."

You do not need to write code to do this. You need to be as clear as you would be with a new contractor on their first day.

Why does the brief matter so much?

An AI coding agent works fast and does what it understood, not what you meant. If the request is vague, it makes choices for you, and you find out later.

Anthropic's guide says it plainly: "The more precise your instructions, the fewer corrections you'll need." OpenAI's guidance for Codex, its coding agent, makes a similar point. A useful prompt, it says, preserves important constraints and says how to verify the change.

Two words matter most to non-coders: constraints (what must stay the same) and verification (how you will know it works). We cover both below.

What should a good brief include?

Think of four parts. You can write each in a sentence or two.

1. The outcome, in your words

Say what a person should be able to do, or what should be different. "A customer who forgets their password can get a reset email and set a new one" is a good outcome. "Add password stuff" is not.

2. Where it happens

Name the screen, the page, the report or the part of the product. If you can, attach a screenshot. Claude Code lets you paste images into the prompt, and Codex's guidance covers working from images too. Pointing at things saves the agent from guessing.

If something similar already exists, say so. Anthropic's example contrasts "add a calendar widget" with a request that tells Claude to look at how the existing widgets on the home page are built and follow that pattern. For you, that might be: "make the new invoices page work like the existing orders page."

Codex's guidance adds one point about pictures: an image shows what something looks like, but you still need to describe behaviour it does not show, such as what happens on hover or what counts as valid input.

3. What must not change

Constraints are the guard rails. Examples:

• "Do not change what customers see on the checkout page."
• "Keep the fix small."
• "Do not add new paid services."
• "Use the tools we already use."

OpenAI's bug-fix example for Codex includes lines like "Do not change the API shape" and "Keep the fix minimal". This is where your knowledge of the business is worth the most, because the agent cannot know which parts are sensitive.

4. How you will know it works

This is the part most people skip. More on it next.

How do I tell the agent what "done" means?

Give it something that says pass or fail. Anthropic's guide has a section titled "Give Claude a way to verify its work". Its reasoning: the agent stops when the work looks done. Without a check it can run, "looks done" is the only signal it has, and you become the person who has to catch every mistake.

You can supply a check in plain terms:

• Examples with answers. "A discount code of SAVE10 takes 10% off. An expired code shows the message 'This code has expired'. An empty code does nothing."
• A picture of the goal. "Here is the design. Take a screenshot of the result and list the differences."
• A story to replay. "A new user signs up, adds an item, pays, and gets a receipt email. That whole path must work."

Then ask for evidence, not reassurance. Anthropic suggests having the agent show the test output, the command it ran and what came back, or a screenshot, rather than just saying it succeeded. "It works" is a claim. A passing test and a screenshot are proof you can look at.

If you cannot say how you would check a piece of work, slow down. Anthropic lists this among its common failure patterns: if you can't verify it, don't ship it.

Weak briefs and better briefs

Here are three everyday swaps, adapted from the examples in Anthropic's guide.

"Fix the login bug." Better: "Customers report that login fails after they have been away for a while. Write a test that shows the problem first. Then fix it, and show me it no longer happens." This gives the symptom, asks for the problem to be reproduced, and defines fixed.

"Make the dashboard look better." Better: "Here is the design from our designer. Make the dashboard match it, take a screenshot, and tell me what still differs."

"Add tests." Better: "Test what happens when a customer is logged out and tries to open their invoices. Avoid fakes where you can." That gives scope, scenario and a preference in one line. ("Mocks", in Anthropic's wording, are stand-ins for real parts of the system.)

Notice what is missing from the better versions: jargon. Every one is something a product owner or analyst can write.

Should I plan first or let it start building?

For anything beyond a small tweak, plan first. Anthropic recommends separating research and planning from building, because letting the agent jump straight to code can produce something that solves the wrong problem. Codex's guidance also suggests asking for a plan before editing on multi-step tasks, and working through larger changes in milestones.

A simple rule from Anthropic: if you could describe the change in one sentence, skip the plan. Fixing a typo or renaming a label does not need one. A new payment option does.

For bigger features, there is a handy trick: ask the agent to interview you. Anthropic suggests starting with a short description and asking Claude to question you about the hard parts, including technical choices, how the screen should behave, edge cases and trade-offs, and then to write a spec. A spec is just a written description of what will be built.

The most useful specs, Anthropic says, are self-contained, state what is out of scope, and end with a step that proves the feature works from start to finish. Your answers in that interview are your real contribution. You know the customers and the rules; the agent knows how to turn them into software.

What goes wrong, and how do I spot it early?

These problems come up again and again.

• Plausible but incomplete work. The result looks right but misses the awkward cases, like an empty form or an expired card. Cure: examples that include the awkward cases.
• Correcting again and again. Anthropic's advice is that after two failed corrections on the same point, you should clear the conversation and write a better opening request that includes what you learned. A clean start with a better brief almost always beats a long thread of patches.
• Unrelated requests in one conversation. The agent's working memory, which Anthropic calls the context window, holds everything said and every file read. Performance degrades as it fills. Start a new conversation for a new topic.
• Open-ended "investigate this" requests. Without limits, the agent may read hundreds of files and fill that working memory. Say what you want to learn and where to look.

Vague is not always wrong. If you are exploring ("what would you improve on this page?"), a loose question can surface things you would not have thought to ask. Just do not expect a precise result from it.

What does this mean for my role?

Your job moves from describing tasks to deciding what good looks like. That means writing the examples, naming the constraints, approving plans and looking at the evidence. Product owners, analysts and testers already have these skills.

It also means you should decide the things an agent should not decide alone: spending money, going live, deleting data, dropping features. Keep those with you whatever tool you use.

Where Atlas fits

Atlas is a team of AI engineers built on Claude Code. You brief one of them, PA, in plain words, and PA shares the work with specialists. Its gates help a brief hold: building waits for an approved architecture, a signed-off design and failing tests, and "done" is refused until the work is on main or queued to land and a screen has its test cases and screenshots. If writing an issue list is the hard part, you can record a call or walkthrough instead, and Atlas lists the issues for you to review before anything is fixed. Atlas does not decide production go-lives, spending or deleting data for you. You can read more at Atlas.

Conclusion

A good brief is short: the outcome, where it happens, what must not change, and how you will know it works. Add examples, ask for evidence, plan first for anything big, and restart with a sharper brief rather than patching a muddled one. You do not need to learn to code to do any of this. You need to be clear about what you want and honest about what you can check.