“Build me an app.”
That’s the most common prompt developers use to start a new project. And it’s the worst one. Not because the model doesn’t produce anything—on the contrary. It produces results immediately: directory structure, configuration, routing, database schema, UI components. In minutes, something that looks like an application emerges.
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 system 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 will time tracking be mapped (per task, per project, per day)? Monolith or services?
The model doesn’t decide. It guesses. It chooses the statistically most likely setup—that is, what appears in most tutorials and GitHub repos. That might be enough for a prototype. For an application that needs to be maintained, extended, and operated, it’s a foundation built on chance.
LLMs lack an architectural overview. They cannot develop one because architecture is not a text problem. It is a decision-making problem. And decisions require context that no prompt can fully provide.
What the Tool Itself Reveals
A look at the tools themselves is revealing. And a bit meta.
I use Claude Code as my main agent. This tool has a built-in Plan Mode: Before code is written, the agent creates a plan that the human must approve. The tool is literally built to think first and then implement.
There is a file named CLAUDE.md located in the project root. It contains architectural 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, deduces 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. Not because the developers at Anthropic are nostalgic, but because it’s 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 begins with a conversation: He lets the model guide him through his idea question by question until a complete specification is in place, a spec.md. Then a reasoning model generates a project plan from this, consisting of granular, sequential tasks. 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 condensed but comprehensive planning phase (requirements, architectural decisions, data model, test strategy) before the first line of code is written.
The pattern is clear: People who work successfully with AI agents plan more than before, not less.
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 humans learn while coding. That writing code is a thought process, not just a production process. That the architecture matures in the developer’s mind as they implement.
When an AI agent writes the code, this learning does not take place. The implementation is finished in minutes, but the understanding of the decisions behind it is not. The architecture does not emerge. It drifts. Each prompt adds a layer that builds on the previous one, without anyone having the big picture in mind.
The Agile movement has replaced planning with learning by doing. AI agents have automated the doing. What remains when neither planning nor learning takes place?
My Workflow for Greenfield Projects
Over the past few months, I’ve developed a workflow that addresses these issues. It’s not elegant, but it works.
Phase 1: Architecture — Without an Agent
Before an agent sees a single line of code, I write an architecture document. Not a slide deck, but a simple Markdown document containing:
- Objectives: What should the software do? What should it explicitly not do?
- Data model: What entities exist? How are they related?
- Technical Decisions: Which framework, and why? Which patterns?
- Interfaces: Which APIs, which formats?
This takes an hour. Sometimes two. But I save that time many times over because the agent doesn’t have to guess afterward.
Phase 2: Defining Tasks — Small and Sequential
I break down the architecture into tasks that can be processed and tested individually. 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. The agent gets context, not freedom.
Phase 3: Implementation with a Pipeline
Each task goes through an automated pipeline: Compile, Lint, Test. The agent iterates against this pipeline until everything is green. Separate quality gate scripts run alongside: 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 just for correctness, but for architectural compliance: Does the code adhere to the decisions from Phase 1? Or has the agent quietly introduced a different pattern?
The latter happens more often than you might think.
What Looks Old Is Actually New
Yes, this looks like Waterfall. Specification → Design → Implementation → Test → Review. In exactly that order.
But there are significant differences from the Waterfall of the 90s:
- Speed: The entire cycle takes hours, not months. Planning takes an hour, not three months.
- Iteration: The architecture document can be adjusted after each iteration. It’s not a contract; it’s a living document.
- Granularity: The tasks are so small that errors remain localized. A wrong prompt affects a single function, not the entire system.
What has remained the same is the principle: Think before you type. The old waterfall failed because months passed between the thinking and the result, and requirements changed. The new waterfall doesn’t have this problem because implementation takes minutes. What used to be too slow is now just right.
Implementation has become so fast that the thinking that used to happen during coding now has to happen beforehand. This isn't a step backward. It's the logical consequence.
Craftsmanship Means Being Able to Plan
In 35 years of software development, I have experienced both extremes: the rigid waterfall of the ’90s with its massive requirements specifications, and the agile counter-movement that almost declared planning a sin. Neither worked in its pure form.
What is emerging now is a third way. Not waterfall, not Agile, but a workflow enforced by the tool: humans think, machines type. Humans decide on the architecture; machines implement it. Humans test the result; machines iterate.
This requires skills that have sometimes been neglected in the agile world: the ability to design a system before it exists. The ability to make and justify decisions before the first test passes. The ability to plan.
90% done in minutes. But only if the architecture is right. And no agent writes that.