AI coding needs acceptance criteria first

AI coding agents make it dangerously easy to start before the work is defined. A founder writes “clean up the onboarding flow.” A product lead asks for “a better empty state.” An engineer says “fix the flaky signup bug.” The agent produces a diff, often a plausible one, and the team spends the review trying to reconstruct what the task was supposed to mean.

That is the wrong review conversation. The bottleneck is not only whether the agent can write code. The bottleneck is whether the human gave it a reviewable definition of done before it started.

OpenAI’s Codex guidance is explicit about this operating pattern: useful tasks include the goal, relevant context, constraints, and what should be true when the task is complete. The same guidance says Codex works best when treated less like a one-off assistant and more like a teammate configured and improved over time, with reusable project context and review habits. See OpenAI’s own Codex best practices and its paper on how OpenAI uses Codex.

The practical move is simple: turn the prompt into an agent task contract before the agent touches the code.

The prompt is not the definition of done

A prompt can express intention. It does not automatically create accountability.

“Make the checkout clearer” might mean reducing copy, changing the order summary, handling a failed payment differently, or improving accessibility labels. All four could be reasonable. Only one may be the work you actually need this week.

When humans work together, teams often rely on conversation to narrow that ambiguity. A senior engineer asks, “Which page?” A designer asks, “What problem are we solving?” A product manager asks, “How will we know this is better?” With an AI coding agent, that clarification step is easy to skip because the agent is so willing to begin.

That willingness creates review debt. The pull request is no longer judged against a crisp outcome. It is judged against memory, taste, and whatever the reviewer assumes the prompt meant. This is how teams end up saying the agent is “unreliable” when the more precise diagnosis is that the task was unreviewable.

This is related to the operating problem in Agents need queues, not just prompts. Once agent work becomes more than a single throwaway command, the team needs a system for scope, ownership, status, and stop conditions. Acceptance criteria are the front door of that system. They make the unit of work small enough to assign and concrete enough to inspect.

What should an agent task contract include?

An agent task contract is not a heavy specification. It is a short brief that prevents vague intent from becoming vague code. It should fit in a ticket, issue, task comment, or repository note.

Use six fields.

Goal. State the user or business outcome, not only the implementation request. “Allow invited workspace members to accept an invitation after signing in with Google” is stronger than “fix invite login.”

Constraints. List boundaries the agent must respect. These can include architecture rules, design system usage, accessibility requirements, naming conventions, API compatibility, security rules, performance expectations, or “do not modify billing logic.” Constraints are where product judgment and engineering standards meet.

Affected files or areas. Point the agent toward the likely files, routes, components, tests, docs, or examples. This does not mean pretending you know the entire implementation. It means reducing the search space and making assumptions visible. OpenAI’s Codex material recommends prompts that look more like GitHub issues, including file paths, component names, diffs, and relevant snippets when useful.

Acceptance criteria. Define what must be true when the task is complete. Good criteria are observable: the empty state appears only when the project has zero tasks, the primary CTA opens the create-task modal, the existing keyboard shortcut still works, the relevant unit test passes, the bug no longer reproduces with the described steps.

Review path. Say who reviews what. A product person may review behavior and copy. An engineer may review design fit, test coverage, and risk. A founder may approve the tradeoff if the change affects pricing or activation. Without a review path, the agent can create work that technically compiles but socially floats.

Rollback note. Add the fastest safe way to undo the change. It can be as simple as “single feature flag,” “revert this PR,” or “migration is additive, no rollback needed unless the new column is read in production.” The point is to think about blast radius before the merge button appears.

A compact contract might look like this:

Goal: reduce confusion after a new user creates an empty workspace.
Constraints: use existing EmptyState component, no new dependency, preserve analytics event names.
Affected areas: app/workspaces/[id]/page.tsx, components/empty-state, onboarding tests.
Acceptance criteria:
- Empty workspace shows title, short explanation, and Create first project CTA.
- CTA opens the existing project creation modal.
- Existing workspace with projects is unchanged.
- Relevant tests pass or the agent explains why no test changed.
Review path: product reviews copy and behavior, engineering reviews diff and tests.
Rollback: revert PR, no database changes.

That is not bureaucracy. It is the minimum shape of a reviewable task.

Why do acceptance criteria improve the review?

Acceptance criteria change the question from “Do I like this diff?” to “Does this diff satisfy the contract?”

That shift matters because AI-generated code can be fluent and distracting. It may introduce a helper that looks elegant but is unnecessary. It may solve a neighboring problem. It may broaden scope because the prompt left room for interpretation. A reviewer without acceptance criteria must inspect both code quality and product intent at the same time.

With criteria, the review becomes staged.

First, check the outcome. Does the behavior match the stated goal? Second, check the boundaries. Did the agent stay inside the allowed files, patterns, and constraints, or did it quietly rewrite unrelated code? Third, check evidence. Are tests, lint, type checks, screenshots, reproduction steps, or manual notes included? Fourth, check reversibility. If this fails in production, does the team know how to back out?

This is also why acceptance criteria should not be only technical. “Tests pass” is necessary in many codebases, but it is not enough. Product-facing work needs behavioral criteria. Internal tooling needs workflow criteria. Measurement changes need event and data-contract criteria. Agent output becomes safer when the definition of done reflects the real system, not only the compiler.

The same principle appears in Product operating models start with decision rights. A workflow is not healthy because everyone can comment. It is healthy when the right people know which decisions they own. AI coding review needs the same clarity.

Where product leaders should intervene

Product leaders do not need to become prompt police. They need to define where ambiguity is expensive.

A useful rule is to intervene before the agent starts when the task touches one of four areas: user behavior, revenue logic, data collection, or cross-team conventions. These are places where a technically valid diff can still be the wrong product decision.

For a small visual fix, the contract can be tiny. For a signup change, it should include expected states, edge cases, analytics events, and review ownership. For billing, permissions, authentication, or migrations, the contract should include explicit constraints and rollback thinking before any agent gets write access.

This is not a case against speed. It is how speed survives contact with review. Teams that skip the contract may feel fast for the first hour and then lose the day in rework. Teams that define the contract can let the agent move quickly inside a smaller box.

The next improvement is to make repeated contracts reusable. Put durable repository guidance in an agent file, team convention, or task template. Keep architecture rules, test commands, naming patterns, and “done means” guidance close to the work. If the agent makes the same mistake twice, update the durable guidance instead of repeating the correction in every prompt.

The artifact is small, but the habit is big

The agent task contract is deliberately modest: goal, constraints, affected files, acceptance criteria, review path, rollback note. It does not promise perfect AI coding. It makes failure easier to see, review, and correct.

That is the operating advantage. The team stops treating AI coding as magic output and starts treating it as delegated work. Delegated work needs a definition of done before execution, not after the diff arrives.

If your AI coding workflow produces too much rework, do not start by changing models, adding more tools, or writing longer prompts. Start by designing the task contract. The agent can only help reliably when the human has made the work reviewable.