“Build me an app.”
That’s the most common prompt developers use to start a new project, and the worst one. Not because the model produces nothing. It produces immediately: directory structure, configuration, routing, database schema, UI components. In minutes, something appears that looks like an application.
But it’s not architecture. It’s a hallucination of architecture.
The Architecture Problem
When I tell an AI agent “Build me a project management tool with user roles and time tracking,” it makes dozens of architectural decisions in the first few seconds: Which framework? Which ORM? How are roles modeled (RBAC, ACL, or simple flags)? How is time tracking represented (per task, per project, per day)? Monolith or services?
The model doesn’t decide. It guesses. It picks the statistically most likely setup, that is, whatever shows up in most tutorials and GitHub repos. For a prototype that may be enough. For an application that has to be maintained, extended and operated, it’s a foundation built on chance.
LLMs have no architectural overview. They cannot develop one, because architecture is not a text problem. It is a decision problem, and decisions need context that no prompt can supply in full.
What the Tool Itself Gives Away
A look at the tools themselves is instructive, and a bit meta.
I use Claude Code as my main agent. The tool has a built-in Plan Mode: before any code is written, the agent creates a plan that the human must approve. The tool is literally built to think first and implement second.
In the project root sits a file named CLAUDE.md. It holds architecture rules, conventions, patterns, everything the agent needs to know to write consistent code. Without this file, something predictable happens: the agent reads the existing code, works out what is “normal” from it, and reproduces it. If the code is inconsistent, the new code will be too.
“Claude does not invent architecture. It copies what it sees.” (from the Claude Code documentation)
The irony is hard to miss: The tool itself is built for waterfall. Specify, plan, then implement. In exactly that order. The developers at Anthropic did not build it that way out of nostalgia. It is the only order that works reliably.
Waterfall in 15 Minutes
I’m not the only one who’s noticed this.
Harper Reed has described a workflow that starts with a conversation: he lets the model walk him through his idea question by question until a complete specification is in place, a spec.md. A reasoning model then generates a project plan from it, consisting of small tasks that build on one another. Only then is code written.
Addy Osmani, who works on the Chrome team at Google, describes the same approach and calls it by its name: “Waterfall in 15 minutes.” A compressed but complete planning phase (requirements, architectural decisions, data model, test strategy) before the first line of code is written.
The pattern is clear: the people who work successfully with AI agents plan more than before.
Why Agile Doesn’t Work Here
This contradicts a principle that has shaped our industry for 20 years: let the architecture emerge. Write code, learn as you go, refactor. “Working software over comprehensive documentation.”
This principle assumes that the human learns while coding. That writing code is not only a production process but also a thinking process. That the architecture matures in the developer’s head while they implement.
When an AI agent writes the code, that learning does not happen. The implementation is done in minutes, but the understanding of the decisions inside it is not. The architecture does not emerge, it drifts: each prompt adds a layer on top of the previous one, without anyone holding the whole picture in their head.
The Agile movement replaced planning with learning by doing. AI agents have automated the doing. What is left when there is neither planning nor learning?
My Workflow for Greenfield Projects
Over the past few months I have developed a workflow that tackles these problems. It lacks elegance, but it works.
Phase 1: Architecture Without an Agent
Before an agent sees a single line of code, I write an architecture document, a plain Markdown file (no slide deck) containing:
- Objective: What should the software do? What should it explicitly not do?
- Data model: Which entities exist? How do they relate to each other?
- Technical decisions: Which framework, and why? Which patterns?
- Interfaces: Which APIs, which formats?
This takes an hour. Sometimes two. But I get that time back several times over, because afterwards the agent doesn’t have to guess.
Phase 2: Defining Tasks, Small and Sequential
I break the architecture down into tasks that can be worked through and tested one at a time. Not “Implement user management,” but “Create the user model with these fields” → “Write the registration with these validation rules” → “Implement the login route with these acceptance criteria.”
Every task has a clear outcome and clear boundaries. Within those boundaries, the agent gets context.
Phase 3: Implementation with a Pipeline
Every task runs through an automated pipeline: compile, lint, test. The agent iterates against that pipeline until everything is green. Alongside it run my own quality-gate scripts: checks for open TODOs, swallowed errors, missing tests.
Phase 4: Review Cycle
After each completed task I have the code reviewed, sometimes by a second agent, always by me. Not only for correctness but also for architectural conformance: does the code stick to the decisions from Phase 1? Or has the agent introduced a different pattern without saying so?
The latter happens more often than you would think.
What Looks Old Is Actually New
Yes, this looks like waterfall. Specification → Design → Implementation → Test → Review. In exactly that order.
But there are substantial differences from the waterfall of the 90s:
- Speed: The whole cycle takes hours, the planning one of them. It used to take months, with three of them for the planning alone.
- Iteration: After every pass I can adjust the architecture document. It is a living document and not a contract.
- Granularity: The tasks are so small that errors stay local. A bad prompt affects only a single function.
What has stayed the same is the principle: think before you type. The old waterfall failed because months passed between the thinking and the result, and the requirements changed in between. The new waterfall doesn’t have that problem, because implementation takes only minutes. What used to be too slow is now just right.
Implementation has become so fast that the thinking time that used to sit inside the coding now has to come before it. That is the logical consequence, and not a step backward.
Craftsmanship Means Being Able to Plan
In 35 years of software development I have seen both extremes: the rigid waterfall of the 90s with its requirements specifications weighing a ton, and the agile counter-movement that all but declared planning a sin. Neither worked in its pure form.
What is emerging now is a third thing, a workflow the tool enforces: the human thinks, decides the architecture and checks the result. The machine types, implements the architecture and iterates.
This requires skills that the agile world sometimes neglected: designing a system before it exists, and making and justifying decisions before the first test is green. In a word: planning.
90% done in minutes, but only if the architecture is right. No agent writes that.