How to write an AI project brief that a coding agent can actually build

Start with the outcome, not the feature list

Describe who needs the result, what they must be able to accomplish and what observable evidence will prove it works. A list of screens or technologies is not a success condition.

A useful outcome is specific enough to test but leaves implementation choices open. For example: a first-time visitor can describe a project, receive a complete implementation dossier and resume safely after leaving.

1. Name the primary user.
2. State the job they need to finish.
3. Define the visible result.
4. Define what must never happen.

Separate facts, decisions and assumptions

Coding agents are good at filling gaps, which is dangerous when a gap represents a business decision. Mark confirmed facts, owner decisions and reversible assumptions separately.

If a choice changes money, permissions, public publication, legal language or irreversible data, keep it blocked until the right person confirms it.

Specify the unhappy paths

A build is incomplete if the brief describes only success. Include empty, loading, timeout, permission, duplicate, reload and partial-failure behavior. State how the user recovers without losing work.

For AI features, also define output validation, retry limits, budget ceilings and what happens when a provider returns an uncertain result.

Make verification part of the brief

Ask for evidence at the natural destination: the real page, API, database state or provider receipt. A passing unit test is useful, but it does not prove that the released customer journey works.

Bind release evidence to the exact build and keep a known rollback. This prevents a later build from borrowing proof that belongs to an older version.