Architecture
Get real design options and honest trade-offs, settle the interface in plan mode, and record the decision before it's lost.
-
How Do You Record a Design Decision With Claude? Right after you decide, while the discussion is still in the session, have Claude draft a one-page Architecture Decision Record in your repo. Level 3: Workflows
- 1Titlenumbered, and numbers are never reused
- 2Contextask for rejected options here
- 3Decision"We will write events to an outbox table"
- 4Statusmark it superseded, never edit it
- 5Consequencesgood, bad and neutral
-
How Do You Design an Interface With Claude First? Start in plan mode, so Claude reads your code and proposes the interface while edits are blocked. Level 3: Workflows
- 1/plan with your constraints
- 2Claude reads and proposes
- 3Ctrl+G to edit the plan
Keep planning until the shape is right, then approve -
How Do You Get Honest Trade-offs From Claude? Name your criteria in order of importance, then ask for a table with a concrete judgment in every cell and a label saying where each judgment came from. Level 3: Workflows
- REPOjudged from this code
- DOCSchecked a current source, with a link
- ASSUMEDneither, so verify before you commit
-
How Do You Get Real Design Options From Claude? Ask for three approaches, each built around a different priority, and tell Claude to stop before it builds anything. Level 3: WorkflowsThe decision
- Simplest that works
- Holds at 10x
- Ships by the date
- Don't build it yet
From question to written decision
These cards form a sequence. Generate real options, each built around a different priority. Compare them in a table against criteria you've ranked. Design the interface of the winner before any code exists. Then write the decision down in your repo, so the reasoning outlives the session. You won't need all four every time. A small choice might only need the table, and a choice nobody will question doesn't need a record.
What Claude can and can't judge
Claude can read your code and reason about how an option fits it. It can't know your load next year, your team's skills or what you'd accept as a downside, so those have to come from you. It may also be out of date on libraries and prices, since Anthropic lists a reliable knowledge cutoff of June 2026 for its current models. Ask it to mark which claims come from your code, which from a source it checked, and which are assumptions. In Claude Code, use plan mode for this work, so edits stay blocked while you decide.
Can Claude help with software architecture?
Yes, particularly at laying out options and consequences against your real code. Treat its answer as input. You have to supply the constraints and make the call, because Claude can't see your team or your future load.
How do I stop Claude writing code during a design discussion?
In Claude Code, use plan mode, which blocks edits until you approve. Press Shift+Tab or start your prompt with /plan. In the Claude app, say you want options only, and that it shouldn't build anything until you choose.
Which Claude model should I use for design work?
Try your default model with /effort high first. Anthropic's docs suggest Fable 5.1 for demanding reasoning, or when Opus 5.5 at higher effort still falls short. The opusplan setting uses Opus while planning and Sonnet while executing.
What is an ADR?
An Architecture Decision Record is a short file in your repo with a decision's context, the decision itself, its status and its consequences. The format comes from Michael Nygard's 2011 post. Claude can draft one from your discussion.