Architecture decisions are hard to reverse. Picking the wrong data model, the wrong service boundary, the wrong caching strategy — these compound over months into technical debt that slows everything down.
Claude Code is useful here not as an oracle but as a thinking partner. Here's how I structure those conversations.
Present the problem, not a proposed solution
The instinct is to say "I want to do X, what do you think?" Claude will mostly agree with whatever you proposed, then list some caveats.
More useful:
I need to solve [problem]. Here are the constraints:
- [constraint 1]
- [constraint 2]
- [constraint 3]
What are the main approaches? For each one, give me the tradeoffs.
Don't tell me which one to pick yet.Getting the tradeoffs first, before a recommendation, forces Claude to actually enumerate the options rather than justifying whichever one it mentioned first.
The constraint list matters most
Architecture tradeoffs only make sense in context. "Should I use a queue or direct API calls?" has a different answer depending on whether you need ordering guarantees, whether the caller can tolerate latency, whether you're running on serverless where background jobs are hard.
Spend time on the constraints before asking the question. Claude's recommendation quality scales directly with how well you've specified the actual problem.
Challenge the recommendation
After getting a recommendation, push on it:
You recommended [approach]. What's the strongest argument against it?
What assumptions is that recommendation based on?
Under what conditions would a different approach be better?This is where good thinking happens. The initial recommendation is the median answer. The follow-up challenges surface the cases where the median answer is wrong for your specific situation.
Scaling the decision
Most architectural mistakes come from not thinking about scale — not just user scale, but complexity scale as the codebase grows:
If this works and we have 10x the users in a year, where does this approach break?
If the team triples, what becomes harder to maintain with this design?
What's the migration path if we need to change this in 6 months?Claude is good at projecting failure modes forward. It's seen enough systems to know what tends to go wrong.
Document the decision
After reaching a conclusion, ask Claude to write an Architecture Decision Record:
Write an ADR for the decision we just made. Include:
- Context: the problem we were solving
- Decision: what we chose
- Alternatives considered: the other options and why we didn't choose them
- Consequences: what this means for future work
Keep it under one page.This is one of the highest-value uses of Claude Code. It takes 30 seconds to prompt, produces documentation that would take 30 minutes to write, and creates a record of why decisions were made that will matter in 6 months when you've forgotten.
What architecture decisions Claude handles well
- Data modeling — normalization vs denormalization tradeoffs
- Service boundaries — what belongs in one service vs two
- Caching strategy — what to cache, where, for how long
- API design — REST vs GraphQL vs RPC, request/response shapes
- State management — server state vs client state, what lives where
What it handles less well
- Team-specific constraints (your team's actual skills and capacity)
- Organizational tradeoffs (politics, existing investments, vendor relationships)
- Anything requiring knowledge of your specific production metrics
For the second list, Claude can still help you think — but the inputs have to come from you.
The Agent Prompt Playbook includes the architecture decision prompts I use most — tradeoff analysis, ADR generation, scaling projections. $29.