What this prompt does
This prompt turns Claude Code into a senior reviewer doing a deliberate architecture pass instead of a vague "look at my code" request. The five numbered focus areas — pattern analysis, coupling and cohesion, scalability bottlenecks, security architecture gaps, and impact-ranked improvements — force the model to walk a checklist rather than fixate on the first file it opens. That ordering matters: you assess structure before prescribing changes, which is how an experienced engineer actually reviews a system. I lean on this exact sequence when I inherit a Laravel codebase cold — structure first, fixes last.
It works because it gives Claude the two things architecture advice is useless without: direction and constraints. By naming your [application_type] and [tech_stack], you anchor the review in real framework idioms instead of textbook UML. By stating current [scale] and [target_scale], you convert "is this scalable?" into a concrete delta the model can reason about — a system fine at 1k users and a system fine at 1M are different designs. Crucially, security sits inside the same pass rather than as a bolt-on afterthought, so auth, secrets, and trust boundaries get judged against the same architecture you're scaling. The closing instruction to ship concrete code for the top 3 recommendations stops the output from drifting into a strategy memo you can't act on.
When to use it
- Before a major scaling push — you know
[target_scale]is coming and want bottlenecks surfaced first. - Inheriting a legacy or unfamiliar codebase and needing a fast structural map of patterns and coupling.
- Pre-funding or pre-acquisition technical due diligence where someone will ask "will this hold up — and is it safe?"
- After organic growth has left you with a tangle of services and you suspect cohesion has rotted.
- When you need a security architecture read — exposed endpoints, secret handling, trust boundaries — alongside the structural review, not in a separate engagement.
- Planning a refactor and needing changes ranked by impact so you fix what actually moves the needle.
Example output
ARCHITECTURE REVIEW — Order Service (Laravel 11 + MySQL + Redis)
Scale: 5k orders/day → target 150k/day (figures echoed back from your inputs)
1. Pattern: Fat controllers + active-record models; no service layer.
Business logic leaks into HTTP layer → untestable, hard to reuse.
2. Coupling: OrderController directly touches Stripe SDK + Mailer.
High efferent coupling; a payment-API change ripples into HTTP code.
3. Scalability bottleneck: synchronous email/PDF on checkout request.
p95 latency tracks third-party uptime, not your code.
4. Security gap: Stripe webhook route has no signature verification;
API keys read via env() at runtime → spoofable callbacks, leaky config.
TOP 3 (ranked by impact):
#1 Move side-effects to queued jobs (Horizon)
dispatch(new SendInvoice($order)); // was inline, blocking
#2 Verify webhook signatures + move secrets to config
$request->header('Stripe-Signature'); // reject unsigned callbacks
#3 Extract OrderService; inject PaymentGateway interface
Pro tips
- Be specific with
[scalability_concern]: "write throughput" or "fan-out reads" yields sharper bottleneck analysis than a generic "performance." - Make the
[scale]→[target_scale]gap real with numbers and units (req/s, GB, concurrent users). A 10x jump and a 1000x jump demand different architectures, and the model calibrates to the multiplier — the figures in the report are derived from yours, not invented. - Run it against the actual repo, not a description. Point Claude Code at the codebase so coupling and security claims cite real files instead of guessing — this is the single biggest quality lever.
- Treat the impact ranking as a hypothesis, not gospel — ask it to estimate effort alongside impact, then have it justify why #1 beats #2 before you commit a sprint to it.
- Pair it with a follow-up: take the top recommendation and feed it into a focused refactor or test-generation prompt so the review produces shipped code, not a backlog item.
