Architecture decisions are hard to reverse. Picking the wrong data model, service boundary, or caching strategy compounds over months. Claude Code is useful here — not as an oracle, but as a thinking partner.
Present the problem, not a proposed solution
Don't: "I want to do X, what do you think?" — Claude will mostly agree, then list caveats.
Do:
I need to solve [problem]. Here are the constraints:
- [constraint 1]
- [constraint 2]
What are the main approaches? For each one, give me the tradeoffs.
Don't tell me which one to pick yet.
Getting tradeoffs first forces Claude to enumerate options rather than justify the first thing it mentions.
The constraint list matters most
"Should I use a queue or direct API calls?" has a different answer depending on ordering requirements, latency tolerance, whether you're on serverless. Spend time on constraints before asking the question.
Challenge the recommendation
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?
The initial recommendation is the median answer. Follow-up challenges surface the cases where the median answer is wrong for your specific situation.
Scale the decision
If this works and we have 10x the users in a year, where does this break?
If the team triples, what becomes harder to maintain?
What's the migration path if we need to change this in 6 months?
Most architectural mistakes come from not thinking about complexity scale as the codebase grows.
Document the decision (ADR in 30 seconds)
Write an ADR for the decision we just made. Include:
- Context: the problem we were solving
- Decision: what we chose
- Alternatives considered: why we didn't choose them
- Consequences: what this makes easier, what it makes harder
Keep it under one page.
This 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.
Architecture decision prompts are in the Agent Prompt Playbook — tradeoff analysis, ADR generation, scaling projections. $29.
Top comments (0)