How to architect a software project with AI before you write code

Ask an AI to "design the architecture" and you'll get a confident diagram with Kafka in it. It answers the question you asked, with no idea how many users you have, who runs it at 3 a.m., or what you're trying to avoid. The useful work is the other way around: the AI draws and asks, and you decide.

Here is the process, on a small example: appointment reminders for clinics. The boards are drawn with Hunch Board, but the steps work with any plan the AI can read.

1. Start from what would make it fail

Before any boxes, write a few lines that only you can write: who uses it, how much traffic you really expect, what must never go wrong, and what you already run. For the clinic: about 50 clinics, a few thousand messages a day, one developer, and a patient must never get the same reminder twice.

That last line will decide more of the design than any framework. Give the AI your constraints and it stops designing for a scale you don't have.

2. Let the AI interview you

You don't have to know everything at the start. Anthropic's guidance for Claude Code suggests asking Claude to interview you until it could write the spec. It's a good way to find out what you haven't thought about.

Here are my constraints: [your lines]. Interview me about what's still open, one topic at a time. Then write the plan to board.hunch. Don't choose anything for me: mark what I haven't decided with a [question] note. Keep it to the parts that matter.

3. Draw the first version, and look at it

A drawing shows things a paragraph hides: the box everything depends on, the arrow nobody owns, the part that exists only because it sounded right.

title Appointment reminders

clinic: Web app "Clinic panel" "Next.js"
api: Monolith "Reminders" "Next.js" "Pages and API in one deploy"
db: PostgreSQL "Appointments"
jobs: Scheduled job "Send reminders" "" "Every 15 minutes"
wa: WhatsApp "Patient messages"

clinic => api "books"
api => db "SQL"
jobs => db "due soon?"
jobs => wa "reminder"

note "One deployable until something needs to scale on its own." [decision status=accepted]
note "Can a patient reschedule by replying?" [question]

Keep it small. If a box wouldn't change how anyone builds the system, delete it. A short board that says what matters beats a complete one, and it's also what your AI will have to read on every task.

4. Ask how it breaks

Now use the AI for what it's really good at: thinking of failures you'd rather not. Ask it to attack the plan rather than praise it.

Read board.hunch. Using my constraints, list the three most likely ways this goes wrong in production. For each one give two options and what each costs me. Don't recommend yet.

For the clinic, the first answer is obvious once someone says it: if the job runs twice, a patient gets two messages. That's the rule we said must never break, and nothing on the first board deals with it.

5. Make the decisions yourself, on the board

A decision is the most valuable thing you can write down, because it's the one thing nobody can work out from the code later. Record what you chose, what you turned down, and why. And record what you won't do:

title Appointment reminders

clinic: Web app "Clinic panel" "Next.js"
api: Monolith "Reminders" "Next.js" "Pages and API in one deploy"
db: PostgreSQL "Appointments" "" "Each row has reminder_sent_at"
jobs: Scheduled job "Send reminders" "" "Every 15 minutes"
wa: WhatsApp "Patient messages"
hook: Webhook "Patient replies"

clinic => api "books"
api => db "SQL"
jobs => db "due soon?"
jobs => wa "reminder"
wa --> hook "reply"
hook => api "confirm or cancel"

twice: Decision "What if the job runs twice?"
stamp: Option "Stamp the row in one update" "" "Only one run can claim a reminder"
lock: Option "A lock in Redis" "" "One more thing to run"
twice => stamp "chosen"
twice => lock

note "Rescheduling by chat is out for now. A reply can only confirm or cancel." [out-of-scope]
note "How many hours before the appointment? Ask the clinics." [question]

Notice the [out-of-scope] note. Without it, an eager assistant may build rescheduling because it seemed helpful. Notice also the question that's still open: it's fine to start building with one, as long as it's written down and it can't change the shape of the system.

6. Go deeper only where it's risky

Most boxes don't need more detail. The risky ones do. On Hunch, any box can open into its own board, with one line on the outer file:

inside jobs boards/reminders.hunch

The outer board stays a map you can read in a minute, and the inner one can hold the flow, the states of a reminder, or the table it writes to. One level is usually enough, and two is plenty.

7. Build one slice, and update the plan

Pick the thinnest path that crosses the whole system. Here, that's one clinic, one appointment and one reminder that really arrives. Ask for that alone. It tests the plan against reality faster than any review, and something on the board will turn out to be wrong.

That's expected. Change the board along with the code, and the plan stays worth reading. There's more on why this improves what the AI writes in why a plan helps AI write better code.

Practice on designs you already know

Architecture is a skill, and studying other designs builds it faster. The community has study boards with their trade-offs written down, like a URL shortener, a rate limiter and a payment system. They're practice designs, not those companies' real systems. Clone one, ask the AI to attack it, and defend your changes.