From Prompt and Iterate to Architect and Build

When I started experimenting with AI-assisted development, my process was straightforward: describe what I wanted, see what came back, fix what broke. Prompt and iterate.

It worked well enough at first. Then projects got more complex, context windows filled up, and the AI started making decisions I hadn’t anticipated — not because it was wrong, but because I hadn’t been clear enough about what right looked like.

The fix wasn’t a better AI. It was a better briefing.

The before

Without structure, every new session started from scratch. The AI had no memory of what had been decided, why certain approaches had been chosen, or what was explicitly out of scope. I was rebuilding context constantly, and so was it. The result was inconsistency — good work in some areas, unexpected decisions in others.

The other problem was scope. Without clear module boundaries and acceptance criteria, “done” was vague. Features bled into each other. Testing was an afterthought. And when something broke, it was hard to isolate where.

The after

Every project now goes through a nine-phase process before any code is written. The output is seven documents that live in the repository root and form a persistent briefing for every Claude Code session:

DATA_MODEL.md — every entity, every relationship, the rationale behind key design decisions. The AI never has to guess at the schema.

ARCHITECTURE.md — the structural pattern, the tech stack with rationale, what is explicitly deferred and why.

MODULES.md — the project broken into independently buildable and testable modules, each with clear scope and acceptance criteria. The definition of done for every stage.

TECH_STACK.md — exact packages, versions, repository structure, development scripts.

SECURITY.md — authentication, authorisation, input validation, rate limiting. Constraints the AI must respect throughout.

README.md — prerequisites, setup steps, development commands.

CLAUDE.md — the briefing document. What the project is, what the absolute constraints are, what is out of scope, what common mistakes to avoid. This is what the AI reads first at the start of every session.

You don’t need to know how to write these from scratch

If producing seven structured documents before writing a line of code sounds like a high bar — it doesn’t have to be. Claude can help you create them. Describe your project, answer the questions it asks, and the documents emerge from the conversation. The nine-phase process is designed to draw out the decisions you need to make, in the right order, before any building happens. You bring the domain knowledge. The process provides the structure.

Ask why before you agree

One of the most valuable habits I’ve developed is refusing to accept a proposal without understanding the reasoning behind it. When the AI suggests an architectural approach I haven’t seen before, I ask it to explain why before I agree.

On one project — an app I built for my son — the initial proposal was to use the platform’s native sync capability for cross-device data sharing. Clean, elegant, no external services. I accepted it, and it failed. The native sync layer had real constraints that the data model couldn’t accommodate.

Instead of retrying the same approach, I stopped and asked a different question: do we actually need a shared database here, or just a messaging layer?

That question opened up a completely different option space — lightweight messaging protocols, push notification services, minimal shared state. Each with different tradeoffs. Working through them properly led somewhere important: pure messaging without persistence breaks the moment one device is offline. Which means you need state somewhere. Which means the question isn’t “messaging or database” but “what kind of persistence, and how does it behave under real conditions?”

And then one more question changed everything: what if this isn’t just for my family? What if it goes on the App Store?

That single question changed the data model entirely. A single-family app and a multi-tenant product have fundamentally different structural requirements. If I’d accepted the first proposal and moved on, I’d have been looking at a painful rebuild six months later.

The conversation that produced the right architecture took twenty minutes. Rebuilding the wrong one would have taken weeks.

The principle behind it

Any enterprise architect will recognise what’s happening here. Define scope before you build. Establish boundaries before you add features. Make decisions explicitly and document the rationale. And never let a proposal pass without understanding why it was made.

These aren’t AI development principles. They’re architecture principles. They happen to apply here too.