Part of our guide to Build an app with AI without coding: a founder's guide to working with a coding agent
On this page · 9 sections
Most bad results from coding agents start with a bad brief. Not because the brief lacked technical detail, but because it lacked the user's view: what they're trying to do, what goes wrong, and what 'fixed' looks like. Non-developers often think they need to speak the agent's language. They don't. The agent needs yours.
This is the first step of the loop in our guide to building software with an AI coding agent: brief, preview, review, release, rollback. Get the brief right and the other four get much easier.
The five things every brief needs
- Who: the person using this part of the product. 'Riders on the tablet', 'me on the admin site', 'customers on their phones'.
- Now: what happens today, or what's missing. Be specific about the screen or step.
- Wanted: what should happen instead, described as behaviour, not implementation.
- Done when: two or three checks you'll do on the preview to decide it works. These are your acceptance checks.
- Not this time: anything related you don't want changed, so the agent doesn't 'helpfully' redesign the page.
That's it. Five short lines beat three paragraphs of background. Add context only where it changes the answer: a deadline, a customer complaint, a rule from your industry.
Templates you can copy
Feature or change request
An illustrative example, written as a phone message:
Who: me on the admin site. Now: to change a song's price I have to edit each song one by one. Wanted: let me select several songs and set one price for all of them. Done when: I can tick 5 songs, set A$2.50, and all 5 show A$2.50 on the kiosk; songs I didn't tick don't change; I can't set a negative price. Not this time: don't change how the song list looks.
Bug report
A bug the agent can't reproduce is a bug it will guess at. Make it easy to reproduce.
'The payment screen is broken' gives the agent nothing. An illustrative better version: 'On the kiosk tablet, after picking a song and tapping Pay, the spinner runs forever. Happened twice tonight around 9pm, both times on the car's mobile hotspot. Worked fine on wifi this morning. Screenshot attached.' gives it a lead, and the wifi detail is probably the clue.
Photos, screenshots and voice notes
A picture removes most ambiguity. Circle the thing on a screenshot, photograph the tablet in the car, or share a competitor's page with 'like this, but simpler'. In Fulcrum Cortex you can send briefs through Telegram, WhatsApp, Slack or Discord, including voice notes, photos and phone videos, and the agent works from them.
Voice notes are fine for small changes, but they tend to ramble. A useful habit: send the voice note, then ask the agent to reply with the brief written in the five-part format above. Correct that, and you have a clear record of what you asked for.
Writing acceptance checks a non-developer can run
Acceptance checks are the most important part of the brief, because they're what you'll use in review. Good checks are things you can do yourself on a preview in a couple of minutes:
| Vague | Checkable |
|---|---|
| Make the form better | A customer can submit the form on a phone without zooming; a missing email shows a message under the field |
| Speed up the dashboard | The jobs page shows this week's jobs within about two seconds on the office laptop |
| Fix the prices | Prices on the kiosk match the admin site for these five songs |
| Add a report | Every Monday at 8am I get an email with last week's bookings by day, and the total matches the booking screen |
| Make it secure | Logged-out users who open the admin address are sent to the login page |
Include at least one 'nothing else broke' check, such as 'the existing checkout still works with the test card'. The review guide for AI-built changes explains which of these checks are worth turning into automated tests.
One change per brief
Bundle five changes into one message and you'll get one large change that's hard to review and harder to roll back. Split them. If they depend on each other, number them and say so. A good rule of thumb: if you can't describe the done-when checks in three lines, the brief is probably two briefs.
The exception is a first version of something new, such as an internal dashboard, where a single brief describes the whole first scope. Even then, keep that scope small. Our article on building internal tools with AI shows how to cut a first version down to what's useful.
Constraints worth stating up front
A few things the agent can't guess and should always be told:
- Devices: 'this runs on a 10-inch Android tablet in a moving car' changes the design.
- Users' context: 'staff use this with gloves on', 'customers are often older and on slow connections'.
- Rules: pricing in AUD including GST, Australian date formats, any industry requirements.
- Sensitive areas: 'don't touch the payment flow in this change' or 'this involves customer health information'.
- Timing: 'needs to be live before Saturday's event', or 'no rush, do it properly'.
Answering the agent's questions
A good agent asks questions when the brief is ambiguous. Treat that as a feature. Answer them in the same thread so the record stays together, and if a question reveals you hadn't thought something through, it's fine to say 'good point, leave that out for now'. Ask the agent to restate the final scope before it starts building.
The general principles here apply to any delegated task, not just code; see how to write instructions for AI agents for the wider version.
Briefs that go wrong, and how to fix them
- The solution brief. 'Add a dropdown with these 40 options.' Better: describe the problem and let the agent propose the design, then judge it on the preview.
- The everything brief. A wish list for a whole product. Better: pick the one change that matters most this week.
- The context-free bug. 'It's broken again.' Better: the bug template, with steps and a screenshot.
- The silent constraint. You knew it had to work offline but didn't say. Better: state devices and conditions every time it matters.
To see how briefs sent from chat become built, deployed and reported changes, look at Fulcrum Code.
Frequently asked questions
Do I need technical knowledge to brief an AI coding agent?
No. Describe the change from the user's side: who it's for, what happens now, what should happen and how you'll check it. The agent handles the technical approach and should ask you questions where the brief is unclear.
What are acceptance criteria?
They're the specific checks that decide whether a change is done, written so you can try them yourself on a preview. For example: 'I can tick five songs, set one price, and all five show that price on the kiosk.'
How do I report a bug to an AI coding agent?
Give the location, the exact steps you took, what you expected, what actually happened including any error text, when and how often it happens, and a screenshot or short recording. The easier it is to reproduce, the faster the fix.
Can I brief an AI coding agent with a voice note?
Yes, in channels that accept voice notes. For anything beyond a small change, ask the agent to reply with the brief written out in a clear format and correct it before work starts.
