Acceptance Criteria That Agents Can Verify

Writing effective acceptance criteria remains one of the most difficult parts of software engineering. When humans read requirements, they rely on intuition and shared context to fill in the gaps. However, as we move toward an era of autonomous development, we must learn to write acceptance criteria that agents can verify without human intervention. An AI agent lacks the ability to guess what you meant if the specifications are ambiguous. If an agent cannot verify a requirement through a terminal command, a browser check, or a unit test, that requirement is incomplete.

The Shift From Narrative to Verification

Traditional user stories focus on the "value" to the user, often using the classic "As a, I want, So that" template. While this is helpful for product managers, it is often too vague for an AI coding agent. When an agent receives a task, it needs a definition of done that is binary. Either the code meets the requirement, or it does not.

To achieve this, developers must transition from descriptive writing to verifiable specifications. Instead of saying the UI should be fast, you must define a specific threshold for a performance metric. Instead of saying the login should be secure, you must specify the exact hashing algorithm and the expected response for failed attempts. This approach aligns closely with test driven development principles, but extends beyond unit tests to include environmental and visual states.

Components of Verifiable Acceptance Criteria

A verifiable criterion must have a clear input, an expected outcome, and a method of observation. If any of these three elements are missing, the agent will likely hallucinate or produce code that passes its own internal logic but fails in the real world.

• State the initial conditions: The agent needs to know what the environment looks like before the action takes place.
• Define the specific action: Use Precise verbs like "execute", "render", or "persist" rather than "handle" or "process".
• Specify the observation method: Tell the agent how to check its work. This could be a curl command to an API, a grep on a log file, or a specific selector in a headless browser.

When using tools like Claude Code or Codex CLI within coding agents, providing these three pillars allows the agent to self-correct. If the agent runs a command and the output does not match your criteria, it can iterate on the code until the terminal output aligns with the spec.

A Recipe for Agent Friendly Specifications

To write criteria that agents can actually verify, follow this structured recipe for every major feature or bug fix. This structure ensures that the agent stays within the boundaries of your intended architecture.

1. The Execution Path

Define the exact files that should be modified and where new logic should reside. While agents can explore a codebase, they are more efficient when given a starting point. Within the Deska canvas, you can place your notes panel next to your code editor to keep these instructions visible for both you and the agent.

2. The Success Command

Every requirement should be accompanied by a command that returns a zero exit code when successful. This might be a test suite execution, a linter check, or a custom script. For example, if you are building a new API endpoint, the criterion should be that a specific curl command returns a 200 OK status with a specific JSON schema.

3. Visual and DOM Assertions

For frontend tasks, agents need to know what to look for in the rendered output. If you are using browser widgets, you can instruct the agent to verify that a specific CSS class is present or that a button is not disabled after a certain event.

Comparison of Verification Methods

Different types of development require different verification strategies. The following table compares how agents interact with various testing layers.

Leveraging Deska for Agent Verification

Deska provides a unique environment for this workflow because of its local-first architecture. When an agent runs in a panel, it has direct access to your local filesystem and your terminals. This eliminates the latency and security concerns associated with cloud based environments where agents are siloed from the actual execution context.

You can use the Ask Deska assistant to coordinate multiple agents. For instance, you can have one agent writing code in one panel while another agent runs a monitoring script in one of the terminals. Because the workspace is an infinite canvas, you can lay out these panels relative to your technical specifications, ensuring that the agent has the full context of your requirement documents.

If you are away from your desk, the mobile app allows you to monitor these verification steps. You can see if an agent has finished a long test suite and check the terminal output directly from your phone. This creates a continuous loop where the agent works against your verifiable criteria while you provide high level oversight.

Common Pitfalls in Agent Specifications

Even with a structured approach, it is easy to fall back into human-centric writing. Avoid these common mistakes to keep your agents productive.

• Avoid subjective language: Terms like "user friendly", "intuitive", or "modern" mean nothing to an agent. Replace them with specific UI patterns or accessibility standards.
• Do not assume environmental state: Always instruct the agent to verify dependencies or environment variables before beginning the main task.
• Beware of circular logic: If the agent writes both the code and the test without a predefined acceptance criterion from you, it will simply write a test that passes its faulty code.

FAQ

How to write acceptance criteria for LLMs?

Focus on binary outcomes and specific observation methods. Treat the agent like a junior developer who has no access to your project history but has perfect knowledge of documentation. Give them the exact commands they should run to verify that a task is complete.

Can agents perform visual regression testing?

Yes, if they have access to a browser environment and a reference image or DOM state. In a multi panel workspace, an agent can compare the rendered output in a browser panel against the requirements stated in a notes panel.

Should I let agents write their own tests?

Only if you have already provided the high level acceptance criteria. The agent can generate the boilerplate for unit tests, but you must define the assertions. Otherwise, the agent might create tests that reflect its own misunderstandings of the requirements.

Start Building With Verifiable Specs

Transitioning to verifiable acceptance criteria will not only make your AI agents more effective, but it will also improve the clarity of your own manual development process. By defining success in clear, executable terms, you reduce ambiguity and build more robust software. You can experiment with these workflows by using the coding agents available today.

Download Deska to start organizing your development workspace with agents and terminals side by side on a local, secure canvas.