Stop Writing Wishes: How to Write Checkable Acceptance Criteria for AI Agents

Prose acceptance criteria are where intent goes to die

Developer Kunal Sharda identifies a critical failure point in AI-driven development. He found that vague acceptance criteria lead agents to confidently commit code based on incorrect assumptions.

Why This Matters

While human engineers provide a safety net by questioning ambiguous requirements, AI agents guess instantly and execute without friction. This removes the natural refinement process, meaning underspecified tickets that would normally be flagged by a human now sail straight into production as buggy or incorrect code.

Key Insights

• Replace adjectives with numbers: ‘Fast’ must become ‘under 200ms at p95’ to ensure the requirement is checkable (Sharda, 2026).
• Use the Given/When/Then format: Structure criteria as testable scenarios, such as defining specific row counts for large files instead of using the word ‘large’.
• Explicitly state unhappy paths: Define behavior for empty inputs, duplicates, or permission errors to prevent the agent from inventing its own logic.

Working Examples

A checkable specification replacing vague prose like ‘handle large files gracefully’.

Given a CSV with 100,000 rows
When the user triggers an export
Then the file streams to download and completes within 30 seconds
And peak memory stays under 512 MB

Practical Applications

References:

• https://dev.to/kunalsharda/i-changed-how-i-write-acceptance-criteria-and-my-ai-agent-stopped-building-the-wrong-thing-3j7c