How to give your AI coding agent a clear 'definition of done'

When a human teammate picks up a vague ticket, they fill the gaps with judgment and ask questions. An AI coding agent does neither. It reads your request, writes the code, runs whatever checks it can, and declares the feature done — often without a single clarifying question. As one guide puts it, when you hand fuzzy requirements to an agent, "the slack does not get absorbed — it gets built."

That makes your definition of done the single highest-leverage thing you can write. This guide covers how to write one an agent can actually act on.

Acceptance criteria vs. definition of done

Two related ideas, worth keeping separate:

• Acceptance criteria are feature-specific: what this particular piece of work must do to count as correct.
• Definition of done is project-wide: the quality gates every change must pass before it ships — tests, review, docs, no secrets committed.

Think of acceptance criteria as "did we build the right thing" and definition of done as "did we build it to our standard." Your agent needs both. (Atlassian has a good primer on the distinction.)

Make it testable, not aspirational

The test for a good criterion: could a script — or the agent itself — check whether it's true? "The login form should feel fast" is unverifiable. Rewrite it as something with an edge:

• Submitting valid credentials redirects to /dashboard within 500ms
• Submitting a wrong password shows an inline error and does not navigate away
• Submitting an empty field is blocked client-side before any network request
• Failed logins are rate-limited to 5 attempts per minute per IP

Each line is something the agent can build toward and confirm. Addy Osmani's advice on writing a good spec for AI agents is to focus on what and why, not the line-by-line how — describe the intent and the constraints, and let the agent choose the implementation.

A concrete example

Compare these two prompts for the same task.

Vague:

Add a way for users to reset their password.

With a definition of done:

Add a password-reset flow. Done means:

• A POST /auth/reset-request endpoint accepts an email and always returns 200 (never reveal whether the email exists)
• A signed, single-use token valid for 1 hour is emailed via the existing mailer in src/lib/mail.ts
• POST /auth/reset-confirm validates the token, enforces the current password policy, and invalidates the token after use
• Tests cover: valid reset, expired token, reused token, unknown email
• No new dependencies without flagging them first

The second version isn't longer because it's bureaucratic — it's longer because every ambiguity the agent would otherwise guess at is now decided. The security-sensitive choices (don't leak account existence, expire tokens, one-time use) are the ones you least want an agent improvising.

Wire 'done' into the agent's loop

The real power of a testable definition of done is that it closes the agent's feedback loop. An agentic cycle of code → test → fix → repeat only converges if there's a clear target to hit. When your criteria map to actual tests, the agent can run them, see failures, and fix its own work before handing it back to you.

So don't just describe done — give the agent a way to check it:

• Point it at the test command (npm test, pytest) and tell it the feature isn't done until they pass.
• For things that are hard to assert in code — readability, following an existing pattern — use an LLM-as-a-judge pass: a second prompt that reviews the output against your quality bar. Anthropic and others have found this effective for subjective checks.
• Keep security and "no placeholder/mock code" in your project-wide definition of done so it applies to every change, not just the ones you remember to mention.

Put it where the agent will see it

Write your project-wide definition of done once, in a file the agent reads automatically — an AGENTS.md or CLAUDE.md at the repo root. Feature-specific acceptance criteria go in the task prompt itself. That way "our standard" is always in context, and you only spell out what's unique to today's work.

The shift is subtle but it's the whole game: with a capable agent, your acceptance criteria stop being a note to a colleague and become the specification the code is built against. Write them like it.