TL;DR
Agentic coding works when the spec, not the prompt, is the source of truth. Here is the flow we use to turn intent into shipped software with agents doing the mechanical work and senior engineers owning the decisions.
Why "prompt an agent to write code" stops scaling
The first time an engineer hands a coding agent a well-phrased prompt and gets a working function back, it feels like a step change. The second and third time, the cracks show. The agent makes a reasonable-looking change that subtly contradicts a decision made three files away. It re-implements something that already exists. It guesses at intent the prompt left implicit, and the guess is plausible and wrong. The problem is not the model. The problem is that a prompt is a poor source of truth.
Prompts are ephemeral, ambiguous, and disconnected from the codebase's existing decisions. As soon as more than one person, or more than one agent, is involved, you need a shared, durable definition of what you are building. That is what a spec is. An agentic development flow that works is built around the spec as the single source of truth, with agents doing the mechanical translation and senior engineers owning every decision that matters.
The principle: the spec is the contract
In a spec-driven flow, the artifact you maintain is not a pile of prompts. It is a specification that states what the system should do, the constraints it must respect, and the behaviour that proves it is correct. The agent's job is to turn that contract into code. The engineer's job is to own the contract and review the result against it. When the spec is the source of truth, both humans and agents are building the same thing, and disagreements surface as spec questions rather than as silent divergence in the code.
This is the difference between an agent that improvises and an agent that executes a plan. The plan is reviewable, versioned, and shared. We use Supaspec for this so the spec is a first-class artifact rather than a comment buried in a ticket.
The core flow, step by step
- Frame the spec with a human. A senior engineer writes the spec: the intent, the interfaces, the edge cases, and the acceptance criteria. This is where the hard thinking happens, and it is deliberately not delegated to the agent. The agent can help draft, but a person owns the decisions.
- Engineer the context. Give the agent the spec plus the relevant slice of the codebase: the modules it will touch, the conventions it must follow, the types and interfaces it must respect. Good context engineering is the single biggest lever on output quality. An agent with the right context writes code that fits; an agent guessing from a thin prompt writes code that looks right and isn't.
- Let the agent implement against the spec. The agent produces the change as a normal pull request: code, plus the tests that demonstrate the acceptance criteria. Because the spec defined "done," the agent has a concrete target rather than an open-ended instruction.
- Review as code, not as magic. A senior engineer reviews the diff the way they would review any colleague's work, checking it against the spec, not just for whether it runs. This review is the accountability gate. Nothing merges because "the agent wrote it"; it merges because a person stands behind it.
- Close the loop. When review surfaces a gap, the fix usually belongs in the spec, not just the code. Updating the spec keeps the source of truth accurate so the next change, by a human or an agent, starts from solid ground.
The throughline is consistent with how we work everywhere: AI handles the mechanical translation from intent to implementation, and senior engineers own the architecture, the spec, and the review.
Pitfalls and tradeoffs
The most common mistake is skipping the spec because the task feels small. For a one-line fix, that is fine. For anything with design implications, an under-specified task hands the agent the architecture decision by default, and you inherit whatever it guessed. The discipline is to spend the thinking time up front, where it is cheap, rather than in review, where it is expensive.
The second tradeoff is review load. Agents can produce more changes than humans can carefully review, and an unreviewed agent change is a liability, not a gain. If your flow generates more diffs than your seniors can genuinely scrutinise, you have not sped up; you have just moved the bottleneck and added risk. Keep generation in balance with the review capacity that actually protects quality.
Finally, this flow does not fit greenfield exploration well. When you genuinely do not yet know what you are building, forcing a formal spec too early is friction. In that mode, use agents to prototype and explore, then write the spec once the shape is clear and switch into the disciplined flow for the work that has to last.
What good looks like
A team running this well treats specs as the durable artifact and code as its output. New work starts as a spec a senior engineer owns. Agents turn specs into pull requests for review, with tests tied to acceptance criteria. Review is rigorous and focused because the reviewer knows exactly what "correct" was supposed to mean. Engineers spend their time on decisions because the mechanical work is automated, and quality holds because a human is accountable for every decision and every merge.
The takeaway
Agentic development is not about prompting harder. It is about making the spec the single source of truth, engineering the context agents work from, and keeping senior engineers on the decisions and the review. Done that way, agents give you real leverage on the mechanical work while the judgement that determines whether software is any good stays exactly where it belongs. That is how we build day to day.
