I've been using AI coding agents — Claude Code, Cursor, Copilot Workspace — daily for the past year. They're incredible at writing code fast. But there's a problem nobody talks about enough:
The agent builds exactly what you tell it. If your spec is vague, the output is wrong.
Not "kind of wrong." Wrong in ways that take longer to fix than writing it from scratch.
The numbers are worse than you think
A recent study found that developers using AI were 19% slower despite believing they were faster. PR volume doubled, but review time went up 91%. The bottleneck shifted from writing code to verifying it.
And here's the part that hurts: 30-50% of engineering time goes to clarifying requirements and reworking features built from ambiguous specs. AI agents make this worse, not better, because they produce code so fast that you don't notice the spec was wrong until you're deep in review.
The spec is the prompt
When you use an AI agent, your spec isn't just a document for humans — it IS the prompt. The quality of your spec directly determines the quality of the agent's output.
A vague spec like "add a returns flow" gives the agent no guardrails. It'll build something reasonable-looking that misses half the edge cases:
- What happens when a gift recipient initiates a return? Who gets the refund?
- Can customers return individual items from a bundle?
- What's the rate limit on the returns API?
- How do you detect return fraud?
These aren't obscure edge cases. They're the things that cause production incidents.
What a good agent-ready spec looks like
A spec that an AI agent can execute without hallucinating scope needs:
- User stories with clear actors and outcomes
- Acceptance criteria that are testable (not "should work well")
- Edge cases enumerated explicitly
- Failure states with expected behavior for each
- Verification criteria so the agent knows when it's done
And ideally, it references your actual codebase — real file paths, real dependencies, real patterns. Not generic placeholders.
I built a tool for this
I kept running into this problem, so I built ClearSpec. You describe what you want to build in plain English, answer a few clarifying questions (the kind a senior PM would ask), and get a structured spec with all of the above.
The part I'm most excited about: connect your GitHub repo and specs reference actual code from your codebase. Instead of "create a new API endpoint," you get "add POST /api/refunds in src/routes/payments.ts using the existing StripeService from src/services/stripe.ts."
There's also a gap analysis feature — paste any existing PRD and get a list of what's missing: security blind spots, missing failure states, ambiguous criteria. Each gap comes with a specific fix.
It's free during early access (5 specs/month, no credit card). I'd genuinely love feedback on whether the specs are good enough to use as agent prompts.
Try it: clearspec.dev
What's your experience with AI agents and spec quality? I'd love to hear what works for you in the comments.
Top comments (0)