To one-shot or not? Building production systems with coding agents

You may have heard of one-shotting an entire application with a coding agent: you hand it the full brief, walk away, and come back to a working system generated in a single pass. It does work, and there is real merit in it. The agent has the complete picture from the start, so every component is built knowing about every other, the structure is coherent, and nothing gets bolted on later that the original design didn’t anticipate. For a prototype or a demo, something you want in front of stakeholders by Thursday, it’s hard to beat.

For anything heading to production it can be a disaster. A single enormous change is hard to test as you go, hard to review, and hard to unpick when the agent made a quietly wrong assumption early on that everything afterwards depends on. The tests, if there are any, were written by the same process that wrote the bugs, and the first time a human properly understands the system is when it fails in front of a user.

The approach that has worked well for us keeps the merit and drops the risk. It’s a hybrid: capture the full requirements up front and let the agent consider all of it at once, the way a one-shot would, but only ask it to one-shot the plan and the foundations. The features then get built incrementally on a skeleton that already anticipates them. Most of the iteration moves earlier: you argue over the architecture, the features, and the build order while they are still words in a document, when changing your mind costs nothing, rather than after the agent has poured code around a decision nobody quite made.

If that sounds to you like a quiet return to waterfall, you’re not the first to say so, and I’ve answered that at the end. The five steps come first.

1. Write the decisions down before anyone writes code

Every technical decision, spec, and constraint goes into the repo as documentation, and everyone who has a stake in the system agrees to it before a line of code exists. That means product, architecture, security and compliance, and the developers who will live with the result, all signing off on the same set of documents.

Nobody should sit down to write these documents from scratch. Have the conversations you would have had anyway, summarise them into a document everyone can agree to, and deposit that in the repo. Meetings are good at surfacing disagreement; documents are good at recording what was resolved.

Talking isn’t the only way to gather requirements, either. When the group can’t agree on what a feature should do, a one-shot prototype earns its keep. Have the agent generate a rough version in an afternoon, put it in front of the people who will use it, and watch what they do with it. You learn more from ten minutes of someone clicking around than from an hour of them describing what they think they want. The rule is that the prototype is disposable: it exists to sharpen the document, nothing gets built on top of it, and that’s what lets you keep it quick and dirty.

Expect this step to take several rounds. Someone will notice the data model can’t support a feature two pages later, or that two teams have assumed different owners for the same integration. Every one of those arguments is cheap to resolve in a document and expensive to resolve in code the agent has already generated around the wrong answer.

An agent works from whatever context it can see. If the architectural intent lives in someone’s head, or in a Teams thread from March, the agent will invent its own, and it will be internally consistent and confidently wrong.

2. Generate the implementation plan from the documentation, and agree that too

With the documentation in the repo, ask the agent to produce an implementation plan from it: what gets built, in what order, and how the pieces depend on each other. Then put that plan through the same agreement process. The build approach deserves as much scrutiny as the requirements did.

A useful side effect is that the plan is already most of your backlog. We’ve generated the tickets straight from it into the team’s backlog tool, which saves a planning session and keeps the tickets tied to the documented intent rather than to whoever was typing fastest.

3. Scaffold the whole repo in one pass, without building every feature

This is the part that earns the “one shot” label. With the full spec and plan in view, have the agent scaffold the entire repository and every component the system will eventually need: libraries, dependencies, database schemas, service boundaries, configuration. The goal is a structure that can carry every feature in the spec without a major refactor later, even though most of those features don’t exist yet.

A capable coding agent will recommend this anyway; it doesn’t want to build everything in one session either, since it can’t test as it goes. What it can do well is set up the shape of the thing when it can see the whole picture.

Three things belong in the scaffold that teams often defer:

• Test structure, including frontend tests. When an agent can run tests and see them fail, it checks its own work and fixes the failure before you ever see it, instead of handing back code that looks finished and isn’t.
• CI/CD from day one. Linting, tests, versioning, and deployment pipelines all set up before the first feature. Every later change then arrives with a verdict attached.
• Observability from day one. Logging, tracing, and error reporting wired in at the foundation, so you’re never retrofitting instrumentation onto a system that’s already misbehaving.

4. Deploy the empty scaffold before you build anything on it

Get the scaffold into a test environment and confirm every part is talking to every other part: the frontend reaches the API, the API reaches the database, the pipelines run, the logs arrive. Deploying an empty system feels like a strange thing to celebrate, but it flushes out the integration and environment problems while they are cheap, rather than in week six when they’re tangled up with real features.

Where you can, give the coding agent access to the logs in that test environment. An agent that can deploy a change, read the resulting error, and try again closes the loop on its own. One that has to wait for a human to paste in a stack trace is working at human speed.

None of this is new. It’s what a careful team did before coding agents existed. The change is that the time cost has collapsed, so the excuse for skipping it has gone.

5. Build the features, one at a time, as usual

With the foundations deployed and verified, the rest is ordinary feature work. The agent builds against a structure that already anticipates each feature, tests it against a harness that already exists, and deploys it through a pipeline that already runs.

Expect bigger pull requests, and review them differently

One side effect shows up quickly once the features start landing: pull requests get a lot bigger. An agent can implement an entire feature in one go, touching the database, the API, the frontend, and the tests together, where a person would have delivered it in three or four smaller changes. There’s an upside to that: the history stays clean, since each merge is a complete feature rather than a fragment. The downside is that a change that size is hard to undo by hand if something goes wrong.

It’s also more than any reviewer can read line by line, which is why the test structure and pipelines from the scaffolding step matter so much. They become the first reviewer, and they don’t get tired on the four-hundredth line. My own review of a large pull request has changed as a result. Rather than reading it top to bottom, I point an agent at it and interrogate it about the things I’m suspicious of: how does this handle a failed write halfway through, where does the permission check happen. The agent has read every line; I’ve read the parts that carry risk.

Are coding agents pushing us back to waterfall?

On paper this looks suspiciously like the thing the industry spent twenty years getting away from: agree the requirements, write the architecture down, get sign-off before anyone builds. A project manager from 2004 would recognise the plan. It isn’t waterfall, though. Waterfall’s problem was never that it planned; it was that the plan was expensive to produce, expensive to change, and the first real feedback arrived months later when the system met its users. Agile shortened that loop so you could learn early and cheaply, and nothing here gives that up.

The rhythm is the same: plan, build, verify, learn, repeat. What changes is the shape of each pass and what you expect to come out of it. The first iteration used to be a thin vertical slice through the stack and now it can be the entire deployed foundation; an iteration that used to deliver a single story can deliver a whole feature with its tests and pipeline attached. The design phase gets iterations of its own as well, on documents rather than code; that is where the early agreement gets built.

One caveat. This approach assumes the requirements are largely knowable up front, which is true of most enterprise builds where the domain, the integrations, and the constraints are already understood. On a product still in discovery, where nobody yet knows what users want, the spec agreed in week one will be wrong in ways no architecture can absorb. That’s where the one-shot prototype comes back into its own: generate it, test the concept with stakeholders, throw it away, and repeat until the picture is clear enough to write down. Discovery becomes a series of disposable one-shots feeding the document, and the build starts once it holds.

Closing thoughts

The answer to the title, then, is: one-shot the prototypes and the foundations, never the production application. The plan and the skeleton get created in one go, with every factor considered at once, and the system gets built layer by layer from there.

What has shifted most is where the humans spend their effort. Nearly everything in the five steps is about setting up the conditions for the agent to succeed: the documented decisions it works from, the structure it builds into, the tests that tell it when it’s wrong, the pipelines and logs that close the loop. The job has become building the factory rather than handmaking the product, and the teams getting the most out of coding agents are the ones who noticed that early and put their best people on the factory.