Writing work orders for coding agents

Coding agents can now accept an issue and return a pull request, which makes the issue itself part of the engineering system. A useful work order needs a bounded objective, relevant context, acceptance criteria, permitted scope and checks that show whether the change actually works. This month, OpenAI released Codex as a cloud software-engineering agent, and GitHub put its Copilot coding agent into public preview. Both can work in a repository, make changes and produce something for review. GitHub's version starts from an assigned issue and opens a draft pull request. When a ticket is vague, an asynchronous agent may produce a plausible patch before anyone notices the misunderstanding. "Improve the checkout" does not identify an observable change. The objective should identify the behaviour to change and where a reviewer can observe it. For example: "When the payment provider returns a timeout, keep the order pending and show the existing retry message. Do not mark the order paid or failed." This gives the agent a state transition, a user-visible result and two forbidden outcomes. It still leaves room to inspect the implementation. Name the starting point when it matters. A task may depend on a branch, migration or earlier pull request that is not in the default branch. Link the relevant issue or commit rather than pasting an old description that may have drifted.

Keep one issue to one coherent change. If the objective contains several unrelated verbs across different subsystems, split it. Smaller tasks reduce the amount of repository context the agent must infer and make the resulting pull request easier to review. An agent can search code, but it does not know which conventions are deliberate and which are accidents. The issue should identify the likely entry points and the documents that carry authority. Useful context includes the affected route, service, component or command; the existing test file; a schema or interface that must remain compatible; and the repository's build and lint commands. If there is a local instruction file, say where it applies. If another implementation is the approved pattern, link to it and explain which part should be followed. Avoid attaching a wall of copied code. File paths and stable symbols are easier to verify and less likely to become stale. State uncertainty honestly: "The handler appears to start here, but confirm all callers before changing the signature." That gives the agent a lead without pretending the issue author has already completed the investigation. Private production data, credentials and customer examples do not belong in the work order. Create a synthetic fixture that demonstrates the shape of the problem. Coding agents can discover adjacent cleanup and make a patch broader than intended. Tell the agent which areas it may modify and which require approval.

A scope section can name permitted directories, whether dependency changes are allowed, whether a migration is expected and whether generated files should be updated. It can also rule out opportunistic refactors. "Do not rename public API fields" is much more useful than "avoid breaking changes" because the agent can check it directly. Permissions around the execution environment matter too. OpenAI says Codex tasks run in isolated cloud sandboxes preloaded with a repository. GitHub says its coding agent uses a GitHub Actions-backed environment. Decide whether the task needs network access, secrets or external services. Most code changes should use mocks or local fixtures instead of production credentials. If the task genuinely needs a new package or remote documentation, make that an explicit allowance. Record the package manager and lockfile policy so the patch does not update dependencies by accident. Write acceptance criteria around observable behaviour. They should let a reviewer decide whether the task is complete without guessing the issue author's intent. For a bug, include a failing case that should pass after the change and any neighbouring behaviour that must stay unchanged. For a feature, identify the successful path, relevant validation and the response or state transition. Use concrete values in examples, especially around dates, money, permissions and empty input. Good criteria can often be translated into tests:

• given a timed-out provider call, the order remains pending;
• a retry uses the existing order identifier rather than creating another order;
• the user receives the current retry message;
• existing success and explicit-decline tests still pass.

Avoid criteria such as "works correctly", "handles edge cases" or "has good test coverage". Name the edge case. Name the test level that can prove it. The issue should contain commands that work from a clean checkout. Include focused tests first, then the broader suite that is reasonable for the repository. Add lint, type checking, build or migration checks where they apply. Commands need their expected environment. If tests require a service, point to the supported local setup. If part of the suite is known to fail on the base branch, record the exact failure before work begins. Otherwise the agent may spend time fixing unrelated breakage or, worse, describe a failing run as caused by its patch. Ask for the verification evidence in the pull request: commands run, exit status, relevant test names and anything not run. Both Codex and GitHub describe logs or session records that reviewers can inspect. Reviewers still need to inspect the diff and run important checks in the normal CI environment.

Generated snapshots and large formatting changes can hide the functional patch. Require the agent to explain them or leave them out. The work order should define the handoff. The agent returns a draft pull request with a concise summary, linked issue, test evidence and known limitations. It should not merge, deploy or change repository settings unless a separate approved workflow grants that authority. During review, check whether the patch meets the stated behaviour, stays within scope, introduces a security or data migration risk and follows the repository's conventions. Read the code, not only the agent's account of it. Try this on one bounded issue with an existing failing test. If the resulting pull request requires a long conversation to discover what the ticket meant, improve the work order before assigning a larger task.