How to write a build brief for an AI coding agent

Start with a concrete moment

“An app for freelancers” leaves many decisions open. Try: “A freelance designer records a client request, gives it a due date and sees overdue requests on a private dashboard.” That describes a workflow you can actually try.

Write down the current workaround and the smallest improvement worth testing. A single useful behavior makes a better first experiment than a large feature inventory.

Give the agent a completion test

Describe inputs and expected results before implementation. Include a negative case so the agent cannot satisfy the task through a plausible interface alone.

1. A signed-in user creates a request with a title and due date.
2. The request remains after reload and appears in a second session.
3. A missing title produces an understandable validation message.
4. Another account cannot read or change the request, including through its direct API URL.
5. Deleting the request removes it from the normal view.

Make constraints visible

Name the existing stack and link relevant project files. State which services are already configured, the devices that matter and whether the result is a prototype or a hosted release. List unknowns instead of letting the agent quietly invent them.

Keep API credentials out of the brief. Refer to environment variable names. Before adding a new dependency, ask what existing code or service can meet the requirement.

Keep the brief current

After a useful iteration, record the decisions, remaining uncertainties and tests that passed. If scope changes, revise the brief so the next session starts from the actual product. A long transcript is a poor substitute for a short, accurate description.