How to write a spec an AI coding agent won't misread
To write a spec an AI coding agent won't misread, name five things: the feature, who it's for, the behavior to change, what must stay the same, and how you'll check it worked. Agents fill every gap with a common pattern from somewhere else. Ensemble keeps product knowledge next to the code, so the agent can look up the rest.
Why AI agents misread specs
An AI agent misreads a spec when the spec leaves out product facts the agent can't find in the files.
Coding agents are good at code. Give Claude Code or Cursor a clear, well-bounded task and it will usually get it right. The trouble is that most tickets aren't clear or bounded. They were written for a human teammate who already knows the product, and they rely on that knowledge without saying so.
Three gaps cause most of the wrong builds:
- Which code path is the live one. Most products have more than one version of something: an old checkout and a new one, a legacy settings page, a feature flag nobody removed. The agent searches, finds a match, and edits whichever one it found first.
- Who the feature is for. "Add an annual billing option" could mean every user or only admins on team plans. The agent can't tell, so it picks the most common pattern, which is usually "everyone."
- What must not change. Humans know not to touch individual checkout while working on team billing. Nothing in the ticket says so, and the agent has no reason to assume it.
When a gap exists, the agent doesn't stop and ask. It fills the gap with whatever looks most typical, based on millions of other codebases. The result is code that works, passes a quick review, and solves a slightly different problem from the one you had.
PMs leave these facts out because they can't see where the feature lives in the code. Engineers leave them out because the facts are obvious to them. Either way, the agent never gets them.
The five-part spec template
A spec an agent can act on answers five questions, and none of them needs a file path.
1. Feature
Which product feature, by the name your team uses.
Billing page, team plans.
Use the product's own vocabulary. If your team calls it "workspaces," don't write "organizations."
2. User
Who sees or uses the change.
Workspace admins on a team plan.
This is the single most useful line in the spec. It decides permissions, where the UI appears, and which tests matter.
3. Change
The behavior you want, not the implementation.
Add a monthly/annual toggle. Annual shows the discounted annual price and bills yearly.
Describe what the user can do afterward. Leave the how to the agent and the code review.
4. Must not change
What's off limits.
Individual checkout stays as is. Never show the tax ID field on team plans. Existing monthly subscriptions aren't migrated.
This is the line most specs skip, and the one that prevents the worst surprises. List anything nearby that the agent might reasonably "improve."
5. Done when
How you'll check it on a running app.
An admin on the seeded team account can switch to annual and sees the discounted price. A member on the same account doesn't see the toggle.
Write this as something you'll click through on a preview, not as a unit test. It forces you to name the accounts and states that matter.
The finished spec
Feature: Billing page, team plans
User: Workspace admins on a team plan
Change: Add a monthly/annual toggle. Annual shows the discounted
annual price and bills yearly.
Must not change: Individual checkout. Tax ID field never shows on
team plans. Existing monthly subscriptions aren't migrated.
Done when: The seeded team admin can switch to annual and sees the
discounted price. A member on the same account doesn't see
the toggle.
Five lines. It fits in a Linear ticket, and an agent can act on it without guessing.
What a spec should leave out
Leave out file paths, a tour of the repo and implementation choices. The agent can look those up, and your guesses will be out of date.
It's tempting to "help" by pasting in context: the file tree, an architecture doc, a list of files you think are relevant. It usually backfires:
- It goes stale. The architecture doc was accurate eight months ago.
- It anchors the agent on your guess. If you name the wrong file, the agent edits the wrong file.
- It buries the request. Three pages of context and one line of ask.
The better approach is to give the agent a source it can query for the current state of the code, and keep the ticket about the change.
How Ensemble fills in the product context
Ensemble indexes your codebase into a graph and generates product knowledge from it: what each feature is, which code implements it, and how comparable tickets were solved.
With that in place, the agent working on your spec doesn't rely on the ticket alone. Before it edits, it can ask Ensemble:
- What is the billing feature, and which code implements team plans?
- Where does a new setting on the billing page go, and what should it look like?
- How was the last billing change solved, and what did it touch?
Developers get the same answers inside Claude Code or Cursor through Ensemble's MCP server. PMs get them in Ensemble Studio, where the change runs on a live preview.
Two things are coming next: correcting what Ensemble believes about your product by telling it in chat ("team plans never show tax ID"), and turning a rough idea into a spec like the one above through a conversation. Until then, the template does that job.
The hand-off: spec plus preview
The spec and the preview link travel together, so the engineer reviews a running change, not a paragraph.
The "done when" line becomes the review script. The reviewer opens the preview, signs in as the seeded admin, flips the toggle, then signs in as a member and checks that the toggle is gone. If both work, they read the diff. See how to review a pull request without running it locally.
FAQ
Should I paste the codebase into the ticket?
No. Long pasted context goes stale and crowds out the actual request. Give the agent a queryable source, like Ensemble over MCP, and keep the ticket to the five parts.
Does an AI-ready spec replace a PRD?
Not entirely. A PRD explains why and for whom. A spec for an agent is the part of the PRD the agent needs to act: the feature, the user, the change, the limits and the check.
Do I need to know where the code lives?
No. Name the feature the way your team talks about it. Finding the code is the agent's job, and Ensemble's context helps it find the right place.
Can I read what Ensemble knows about my product?
Not as a wiki. Ensemble's product knowledge is internal. Agents and people query it through answers, which say what they're based on.
When can I refine tickets in chat with Ensemble?
Ticket refinement is on the roadmap for the release after launch. Today, use the template above and connect Linear so a finished ticket becomes a preview.
Ensemble turns every change into a running copy of your real app, with its services and data, at a private link anyone on the team can open. What is Ensemble?