How to write a coding agent work order it can act on

Stefan-Iulian Tesoi · 16 September 2026 · 7 min read

A coding agent work order contains six things: the repository and branch, the observable outcome, acceptance criteria each checkable by running something, the files or surfaces in scope, the constraints that must hold, and what to return as evidence. Everything else is context, and context is the part most likely to be wrong.

That list is short because it is what the agent cannot obtain for itself. Anything it can read from the repository does not belong in the order; anything it cannot read, and cannot ask about, has to be in there or it will be invented.

What is a work order?

A written instruction complete enough to be executed by someone who was not in the conversation that produced it.

The name is borrowed from trades where it has meant that for a century: a job card that goes to the bench with the part, carrying the spec, the tolerance and the sign-off. The person at the bench does not attend the meeting where the job was decided. That is the property worth copying, because an agent is permanently in the position of not having attended.

Every quality of a good work order follows from that one constraint. It is self-contained because there is nobody to ask. It states outcomes rather than steps because the bench knows the machine better than the office does. And it says what "finished" means in advance, because otherwise finished is decided afterwards by whoever is most tired.

How is a work order different from a prompt?

A prompt is a turn in a conversation. A work order is a document that survives the conversation ending.

The difference is not formality, it is dependence on shared state. "Now do the same for the settings page" is a fine prompt and a useless work order: it refers to a previous turn, and a week later nobody can reconstruct what "the same" meant. Prompting coding agents works well for exploration, where the next instruction depends on what the last one produced, and fails for delegated work, where the instruction has to stand alone.

Both have a place. The mistake is using the first where the second is needed, which is what happens when a backlog item is a title and the real instruction is typed into a chat window and then lost.

The six parts of a coding agent work order

Six, and the order matters less than the completeness.

1. Repository and branch. "The API" is not a location. A monorepo with nine packages makes this the difference between one edit and a wrong guess about which of nine.
2. The observable outcome. What is true afterwards that is not true now, stated so someone could check it without reading the diff.
3. Acceptance criteria. Each one a command and a result. "Works correctly" is not a criterion; GET /api/search?q=lime returning 200 with at least one match is.
4. Scope. The files, surfaces or modules this may touch — and, when it matters, the ones it may not.
5. Constraints. What must hold that the outcome does not imply: performance budgets, backwards compatibility, a public API that cannot change shape.
6. Evidence to return. Which commands to run and report, including the ones that fail.

Constraints are where precision pays most, and where ordinary English is weakest. RFC 2119 settled this for protocol specifications in 1997 by defining MUST, SHOULD and MAY as terms of art, and the same discipline works here: "the existing export format MUST NOT change" is a constraint, while "try not to break the export" is a hope. A good agent task specification borrows that vocabulary rather than inventing a softer one.

How much context is too much?

Anything the agent can read for itself is too much, and the test is whether removing it would change what gets built.

Over-long orders fail in a way that is easy to miss: they bury the four sentences that matter inside two pages of history, and the result is an agent that has read everything and weighted nothing. A twelve-paragraph preamble about why the feature exists makes the criteria harder to find, not easier to satisfy.

Four things worth cutting from most drafts:

• Repository facts. Directory structure, framework versions, which test runner — all readable, and all liable to be stale in the order and current in the repo.
• Narrative history. Why the last attempt failed matters only if it constrains this attempt; if it does, it is a constraint, so write it as one.
• Implementation steps, unless the approach is itself the requirement. Naming the outcome and then prescribing the route discards the thing the agent is good at.
• Hedges. "Ideally", "if possible", "would be nice" — every one of them is a decision someone has declined to make, handed to the least-informed participant.

What is worth keeping is the opposite: the fact that cannot be derived. The regression note that this module's tests pass in isolation and fail in a full run. The reason the obvious fix was rejected last time. Those are one line each and they save a rebuild.

The length of a work order is not the measure. A one-line item that names the repository, the outcome and a testable criterion is a work order. Two pages of background with no criteria is not.

What should the agent return?

The commands it ran, their outcomes including the failures, and anything a machine could not check named separately.

This closes the loop the criteria opened. A criterion that said "pnpm run ci exits 0" should come back as that command and that exit code, not as "tests are passing" — the second is a claim, the first is a fact a reviewer can re-run. Failures reported are more useful than a clean sheet, because a suite that failed and was fixed tells you where the work actually was.

Laimonade's part is drafting the six parts from a sentence of intent and then reading the returned evidence against the criteria the item was accepted on. What it does not do is close the item: an agent reaches In Review and no further, and a person takes the last step. That division is why AI agent instructions can be automated safely — the expensive judgement stays with a human at both ends.

Mechanically, the order reaches the agent over MCP rather than as pasted text: connecting a coding agent takes a few minutes, and the MCP tools reference lists what it can do with an item once connected. Claude Code, Claude and Cursor all speak it. The wider shape this fits into is in the coding agent workflow a team can actually run, and the defects that make items unusable are catalogued in a backlog an agent can actually read.

Frequently asked questions

Should the work order include the file paths?

Name the repository and the surface always, and specific files only when the choice is not obvious from the outcome. Over-specifying paths turns the order into a plan and discards the agent's ability to find the right place, which is one of the things it is genuinely good at. Under-specifying the repository is never defensible — in a monorepo it is a one-in-nine guess.

How long should a work order be?

Short enough that the criteria are findable, which in practice is under a page. The measure is not word count but whether every sentence changes what gets built. A three-line order naming a repository, an outcome and a testable criterion outperforms two pages of context with no criteria, and the second takes longer to write.

Does each agent need a different work order format?

No, and needing one would be a warning sign. The six parts are about what the work requires, not about which tool reads them, so the same order should be actionable by Claude Code, by Cursor, or by a contractor who starts on Monday. If an order only works for one agent, it is relying on something that agent happens to assume.

What if the outcome cannot be stated observably?

Then the item is not ready, and that is useful information rather than an obstacle. Work whose result nobody can describe from outside is usually research, and research should be scoped as a question to answer rather than as a change to make. Send it back asking what would be different afterwards, instead of asking an agent to guess.