Writing a brief for an unattended agent

The autonomous coding agents page makes one claim this guide rests on: for an agent working unattended, the brief is the specification, and nothing else is. Whatever it leaves out, the agent decides. This is a method for writing one, from a task that already exists to a brief you can hand over and walk away from.

It starts where planning ends. The requirements, the design and the task list come first, and the blog covers each: requirements an agent can build from, a design it cannot improvise and tasks it can finish. The example throughout is the refund flow from those posts, and the brief is for its third task, the call to the payment provider.

What the agent reads

An agent working on its own reads three things: the brief, the repository, and whatever rules file it loads at the start. It does not read the conversation in which you planned the work, the comment on the ticket, or your memory of the call where the design was agreed. A fact reaches it only if one of those three holds it.

That gives the first rule. Every fact the task depends on is either in the brief or in a file the brief names. Name a file in the repository rather than pasting it in, because a copy drifts from its source, and say which part of it this task must follow. Conventions that hold for every task belong in the rules file, once, rather than in each brief. Writing and scoping a rules file covers what goes there.

The parts of a brief

The last two are the parts most briefs leave out, and they are the cheapest to write.

A brief for the provider call

In the task list, the provider call is a title and three lines: what it satisfies, what it depends on and when it is done. The brief turns those into everything the agent needs and nothing it does not.

# Task 3: the provider call
 
Goal: send a refund in `requested` to the payment provider and record
the answer.
 
Satisfies: R5, R6 in `specs/refunds/requirements.md`.
Depends on: task 2, merged. Refund rows exist in `requested`, each with
an idempotency key.
 
## Decided already
 
Read `specs/refunds/design.md` first. For this task:
 
- The row is committed before the provider is called. Never the reverse.
- Send the idempotency key stored on the row. Never make a new one,
  including on a retry.
- A definite answer sets `succeeded` or `failed`. Store the provider's
  reason exactly as it arrives.
- No answer is task 4. Leave the timeout path alone, and add no retry loop.
 
## Boundaries
 
- Work on the branch `task/03-provider-call`.
- Leave alone: `src/payments/`, every merged migration, and `specs/`.
- Add no dependencies. If one seems necessary, stop and say why.
- Tests use the provider stub in `tests/stubs/provider.js`. Nothing in
  this task calls the real provider.
 
## Done when
 
- `tests/refunds/provider-call.test.js` passes. It was written from R5
  and R6 before this task. Do not edit it.
- The whole suite, lint and type check pass, using the commands in
  `rules/project.md`.
- A refund sent twice reaches the stub with the same key both times.
 
## If you get stuck
 
Stop and report, rather than working around it, when:
 
- something this task needs does not exist
- a test you were told not to edit looks wrong
- the change seems to need a file under a path in Boundaries
 
## Hand back
 
- Each file changed, with one line on why.
- The test that covers R5, and the test that covers R6.
- Every decision you made that this brief did not make.
- Anything you could not do.

A few choices in it are worth naming.

• Decided already quotes two decisions and points at the rest. Writing the row before the call and reusing the stored idempotency key are the two decisions in the design that this task could break, and both are invisible when wrong. The rest of the design is one file away.
• The test exists before the task does. The brief names a test written from the requirements and says not to edit it. That is what makes green mean what you meant rather than whatever the code does, the failure AI testing and debugging describes.
• Boundaries fence off the next task as well as the files. The timeout path is task 4. Neighbouring work is where an eager agent overreaches, because the next task's work often looks like part of this one.
• Hand back asks for the decisions the brief did not make. That list is where invention shows, and it is where review starts.

What to leave out

• How to build it. File names, helper names, how the tests are scaffolded, and library choice inside a constraint you already stated. These are cheap to change and obvious when wrong, so they are the agent's to pick. A brief that specifies them is the code written slowly in prose, and wrong wherever the codebase disagrees with it.
• Why you decided. The reasoning behind a decision belongs in the design document, where the next person can find it. The brief says what was decided and points there.
• A second behaviour. If Done when holds two checks that have nothing to do with each other, the brief holds two tasks. Split it, or the change that comes back will be too large to review in one sitting.
• The project's conventions. Restated in every brief, they become several copies that drift apart. Put them in the rules file and let every brief rely on it.

Set the environment before it starts

What the agent can reach while it works decides what a wrong decision can damage, and the category page sets out what it should and should not have. The brief's Boundaries section states the limits, but a sentence in a brief is a request. Where the environment can enforce a limit, make it.

• A branch of its own, cut from a known commit, with no right to push to the main line.
• Test credentials scoped to the task, and no production secret anywhere in the environment.
• No deploy rights and no access to live data.
• A fresh environment for each task, thrown away afterwards. A cloud development environment built from a file in the repository makes that cheap.
• A decision about network access and package installs, made by you before the run rather than by the agent during it.

Check the brief before handing it over

Four checks, before the agent starts.

1. The question test. For each line of Done when, could someone write a passing or failing check from it without asking you anything? That is the test for a requirement in Writing requirements an AI coding agent can build from, and it holds for a brief too.
2. Read it as a stranger. Close the design document, set aside what was said in planning, and read the brief alone. Every place you would have to guess is a decision you are about to hand over. Write the answer in, or name the file that holds it.
3. Ask for its questions first. Begin the run with one attended step: the agent reads the brief and the files it names, then replies with a plan and the questions the brief leaves open, before it changes anything. Answer by editing the brief, not in the chat, so the run that follows, and any rerun, starts from the same text.
4. Run the acceptance tests first. On a clean checkout, before the agent touches anything, the tests named in Done when should fail, and fail because the behaviour is missing. A test that already passes cannot tell you the task is done.

The opening message for the third check can be this short:

Read tasks/03-provider-call.md and every file it names.
Before changing anything, reply with:
 
1. the files you expect to change
2. your approach, in three to five lines
3. every question this brief leaves open
 
Then wait for an answer.

Asking for a plan before the code is the habit Prompt engineering for developers recommends in the editor. Unattended, it matters more, because it is the last point at which a wrong reading of the brief costs a minute rather than a run.

When it comes back

Review the change against the brief, not against the agent's summary of it, and start from the hand-back list of decisions it made. Reviewing a change an agent made sets out the order.

If the change is wrong because the brief allowed it, fix the brief and run the task again rather than patching the diff. A patched diff fixes one change. A fixed brief stops the next run making the same decision, and it keeps the record Delegated execution says you will want when a change breaks something weeks later: the task, the criteria it was built against and the checks that ran.