AI Coding Task Brief Template: Scope, Tests and a Clean Handoff

A coding agent can produce a large diff without completing the job you meant. The problem is often visible before implementation starts: the desired behaviour is vague, the allowed scope is missing, and “done” is defined as code written rather than behaviour verified.

This kit provides three editable documents: a task brief, an acceptance checklist and a handoff. A fourth file shows them applied to a small event-tracking integration defect.

The four individual Markdown files are included inside the ZIP. The current WordPress delivery path serves the safe ZIP package rather than enabling arbitrary .md uploads.

The templates are useful for a single agent or for moving a task between workers. They are not an autonomous agent, a secret prompt or a guarantee of lower token usage.

Define the observable change

Start with a statement a user or test can observe.

“Improve analytics” is not enough. “Submitting a valid chooser result sends exactly one approved completion event, while QA sessions send none” is a bounded behaviour.

Separate the observed symptom from a suspected cause. A test may reveal that the original diagnosis was wrong. The agent should be allowed to report that evidence without expanding into an unrelated redesign.

Name the boundary

List the files or components likely to change, then identify what must remain untouched. For a tracking repair, recommendation scoring, article copy and SEO metadata might all be outside scope.

A boundary is not a demand to ignore a security problem. It is a way to prevent an agent from turning one repair into five elective refactors. Unexpected consequential work should be reported separately.

Include the current branch and relevant commit when known. Do not invent a commit merely to make the brief look complete.

Test the connection, not just the pieces

Consider a tool that dispatches a custom browser event on window while its analytics integration listens on document. Both files may contain the expected event name, and source-string tests may pass, while the integration still fails to receive the event.

A useful acceptance test exercises the actual dispatch and listener path. It checks the resulting call, invalid input and QA exclusion.

This distinction applies beyond analytics. A valid export function does not prove that the download button calls it. A correct calculation does not prove that the interface supplied the right units.

Define evidence for completion

Ask the worker to report what it actually ran: the command, relevant result and any untested boundary.

Local tests are not production QA. A repository commit is not a deployment. An HTTP success response is not proof that a user completed a download.

The acceptance checklist separates these states so another worker does not inherit a misleading “done”.

Hand off verified state

A handoff should let the next worker answer three questions quickly: what changed, what is verified, and what remains.

Record uncommitted files, the real branch/commit and whether production was changed. Include a minimal reproduction for any blocker. Do not copy secrets, cookies, access tokens or private customer data.

If the next worker cannot access the previous environment, say so. A local path that exists on one machine is not proof that another worker can read the file.

Use the kit

Fill the task brief before implementation. Turn the acceptance conditions into tests where practical. Complete the handoff when stopping or transferring the task, including when a usage limit interrupts work.

For a tiny change, shorten the documents. A one-line correction does not need a ten-page process. The purpose is to remove ambiguity, not create paperwork.

Use project instructions and the owner’s authorization boundaries alongside the template. A document does not override platform safeguards or supply permission to publish, delete data or spend money.

Download

The ZIP contains plain Markdown documents and a worked example. It includes no executable scripts, credentials or account integrations. You can adapt the templates to your own repository and workflow.

Must every task use all three templates?

No. Use only the sections that remove real uncertainty.

Does a test pass mean the task is finished?

Only if the tested behaviour covers the acceptance criteria. Record what was not tested.

Can another worker continue from the handoff alone?

Only when the referenced source and environment are accessible. The handoff must make missing dependencies explicit.