Why your AI coding agent keeps shipping the wrong thing

Here's a sentence we've heard from every engineering director we've spoken to in the last six months: “Our agent is impressive — when we tell it exactly what to do.” The emphasis on exactlyis doing all the work in that sentence. It's also where the mismatch lives.

We don't have a model problem in 2026. The frontier models are astonishingly capable. We have a brief problem. The interface between “what we want” and “what gets built” is still a Slack thread, a half-typed Notion page, and three ad-hoc meetings. That worked when humans typed the code. It does not work when an agent does — because the agent will not push back, will not raise its hand, will not interrupt the meeting. It will simply ship.

The misalignment tax

Every team we've worked with pays the same hidden tax. A feature ships, the demo runs, and somewhere in week three a product manager realises the thing the agent built is not the thing the team agreed to. The token cost was real. The rework cost is bigger. The morale cost is the worst of the three — because no one is sure who to blame.

The agent is not at fault. The brief was. The brief said “build a patient-intake portal” and the agent built a patient-intake portal. It was the wrong one. There was no sentence in the brief that ruled out the wrong one. There was also no sentence that said the right one was the right one.

Specs are contracts, not vibes. If your AI agent has to guess what you meant, you have already paid for the misunderstanding twice — once in tokens, once in rework.

What a contract actually looks like

We've been deliberate about the shape of the artefact we ship to a coding agent. It is eight files. It is signed. It is versioned. It cites every constraint back to a wish, and every wish back to the human who made it. That sounds heavy. In practice it's lighter than the four-meeting kickoff it replaces — because the agent reads it once and remembers it perfectly, instead of nine humans reading it nine times and remembering nine different things.

• product-brief.md — the why, in one page.
• prd.md — the what, by section.
• architecture.md — the how, with the decisions called out.
• ux-design.md — the surface, with tokens.
• epics.md + per-story implementation — the work, sequenced.
• qa-test-plan.md — the proof.
• project-context.md + CLAUDE.md — the context the agent needs to not drift.

What this isn't

It isn't a return to waterfall. We don't want a 200-page spec written by a lone analyst before a single line is written. We want a small, sealed contract written collaboratively, in the room, in two weeks, with the constraints of every department captured as evidence. The contract is then handed to the agent. The agent runs. The team watches.

It also isn't about replacing engineers. It's about finally giving them the deliverable they've been asking for since 2010 — a brief that doesn't change shape three days into the sprint.

What you can do this week

• Pick the next feature you're about to ship. Write the brief in three paragraphs. Then circulate it to one person from each affected department and ask, “is anything missing here that, if it were missing in production, would cost us a week?”.
• Ask your coding agent to read the brief and respond with the three biggest ambiguities, not questions. The phrasing matters.
• Capture every clarifying answer back into the brief, dated, attributed. Stop relying on the answer staying in someone's head.

We're not religious about how teams adopt this. But we are serious about one thing: in the world we're heading into, the brief is the leverage point. Get it right and the rest is execution. Get it wrong and no model — no matter how big — will save you.