Briefs an agent's work can be accepted against

A coding agent implements what you write – gaps included. Where your brief is open, it decides, and without mentioning it. The quality of the result therefore depends less on the model than on the brief.

Five parts

1. Starting point. What is the case today? “Search finds exact matches only.”

2. Desired behaviour. What should be observably different afterwards? Describe the outcome, not the route – unless the route is given.

3. Acceptance. A command that shows success or failure. This is the part most often missing and with the biggest effect.

4. Limits. What must not be touched: files, interfaces, dependencies.

5. Entry point. Where the agent should start reading. A file name saves it ten search steps.

## Starting point
Search in src/search.ts finds exact matches only.
“bycicle” returns nothing.

## Desired behaviour
For a typo with one wrong or missing letter, the hits for the
correct word appear.

## Acceptance
- npm test passes
- new test: “bycicle” finds entries containing “bicycle”
- existing tests are unchanged

## Limits
- no new dependency
- do not touch src/db/

## Entry point
src/search.ts, tests in src/search.test.ts

This format is at the same time a good GitHub issue. Write your tasks this way and you can hand them to a person or an agent.

Test first, then code

The sharpest form of acceptance is a test that exists before the implementation and fails. The approach in three steps:

1. Have the agent write only the test.
2. Read the test. Does it check what you mean? Does it fail for the right reason?
3. Only then: “Implement it until the test passes. Do not change the test.”

The last sentence matters. An agent under pressure to get a test green occasionally finds the shortest route: adjusting the test.

Small tasks

One brief, one goal, one pull request. As a measure: if you cannot read the changes in ten minutes, the task was too big.

Large undertakings you break down – ideally with the agent in plan mode. Have it list the sub-steps, put them in an order in which each step can be checked on its own, and commission them one by one.

Three briefing mistakes

Several goals in one. “Fix the bug and tidy up while you are at it” produces a pull request in which the actual fix hides among two hundred lines of reformatting.

Solution instead of problem. “Build in a cache” – perhaps the problem was an unoptimised database query. Describe what is slow and how fast it should be.

No criterion. “Make it more robust”, “improve readability”. The agent changes something and reports success, and you cannot disagree.

What the agent should hand back

At the end of every brief, write what you expect as the result:

Report at the end: which files were changed, the verification
command you ran with its output, and anything you deliberately did
not touch.

The third point often brings out the most useful thing: the place where the agent saw another problem and rightly left it alone.

In the next station this workflow moves to GitHub – the brief becomes an issue, the result a pull request.