What makes a spec "agent-ready"?
An agent-ready spec is one that an AI coding agent — Claude Code, Cursor, GitHub Copilot — can pick up and implement without asking for clarification. The agent has everything it needs: what to build, why, what success looks like, what edge cases to handle, and how to verify the result.
Most specs are not agent-ready. They assume shared context that doesn't exist in an AI session. They use vague language ("make it fast," "improve the UX") that a human colleague could interpret but an agent cannot. They omit edge cases that a senior engineer would think to ask about.
The three requirements
1. Unambiguous scope. The spec must clearly state what is in scope and what is not. An agent that encounters ambiguity will either guess (producing unwanted code) or stall (wasting tokens on clarification that never comes in an autonomous session).
2. Measurable outcomes. "Improve performance" is not agent-ready. "Reduce p95 API response time from 800ms to under 200ms" is. The agent needs to know when it's done. Measurable outcomes also enable automated verification — the spec can define its own test criteria.
3. Explicit constraints. What must not change? What dependencies exist? What patterns should the implementation follow? Agents operate in isolation. They don't know your team's conventions unless you tell them. Constraints prevent the agent from producing technically correct but contextually wrong code.
Why this matters now
When a human engineer receives a vague spec, they compensate with experience, team context, and the ability to ask questions in Slack. The cost of ambiguity is a short conversation.
When an AI agent receives a vague spec, it compensates with hallucination. The cost of ambiguity is wasted compute, incorrect implementations, and manual rework that often exceeds the time saved by using the agent.
The quality of your specification is now the primary bottleneck on AI-assisted development speed. Teams that invest in agent-ready specs get compounding returns: faster implementation, fewer iterations, and code that passes review on the first attempt.
From human-readable to agent-ready
Converting an existing spec to agent-ready format usually involves three steps:
-
Replace adjectives with numbers. "Fast" becomes "<200ms." "Simple" becomes "single form, max 3 fields." "Secure" becomes "input sanitized, rate-limited to 10 requests/minute."
-
Add edge cases. Think about what happens when the input is empty, the network fails, the user is unauthenticated, or the data doesn't exist. Every unhandled edge case is a potential hallucination point.
-
Define verification. How will you know this works? Automated tests, manual checks, performance benchmarks — make it concrete. If you can't describe how to verify it, the spec isn't specific enough.
The IntentSpec format codifies these practices into a repeatable structure.