I do backend and automation consulting, and the most useful thing I’ve built for myself lately is a set of Claude skills that encode how senior engineers actually review things, instead of getting the generic “here are some considerations” output. Here’s the architecture-reviewer one in full. Copy it, save it as a skill (or drop it in ~/.claude/skills/architecture-reviewer/SKILL.md for Claude Code), and it triggers whenever you ask Claude to poke holes in a design. — name: architecture-reviewer description: Stress-test a proposed or existing system architecture — find scalability bottlenecks, single points of failure, security gaps, cost traps, and operational blind spots, with prioritized fixes. Use this skill whenever the user shares an architecture (diagram, design doc, or description) and asks for review, feedback, “poke holes in this,” “what am I missing,” or “is this production-ready?” — # Architecture Reviewer Review architectures the way a senior architect reviews a colleague’s design: find what will actually hurt, rank it by blast radius, and propose the smallest fix that works. The goal is a better system, not a longer list — a review with 30 findings gets ignored; one with 8 prioritized findings gets acted on. ## Review lenses Walk the design through each lens; report only material findings: 1. Failure domains — What dies when each component dies? Single points of failure, missing retries/timeouts/circuit breakers, cascading-failure paths, split-brain scenarios. Trace the failure path of the money-critical flow specifically. 2. Scalability — The first bottleneck under 10x load (there’s always exactly one that hits first — name it). Stateful components that block horizontal scaling, N+1 patterns across service boundaries, hot partitions/keys. 3. Data — Sources of truth (is each fact owned once?), consistency model vs. what the business actually needs, backup/restore tested path, migration strategy, retention & PII handling. 4. Security — Trust boundaries and what crosses them, authn/authz model, secrets handling, blast radius of one compromised component, exposure surface (public endpoints, admin panels). 5. Operations — Can you tell it’s broken before customers do (metrics/alerts on symptoms, not causes)? Deploy and rollback path, config management, runbook-ability at 3am by someone who didn’t build it. 6. Cost — Components priced per-request/per-GB that scale with success (the bill that surprises), idle overprovisioning, egress traps, managed-service premiums vs. their ops savings. 7. Complexity budget — Components that exist for imagined requirements, distributed-system costs taken on where a monolith serves the stated scale, and whether the stated team can operate what’s drawn. ## Severity model - 🔴 Critical — will cause an outage, breach, or unbounded cost under normal-growth conditions. Fix before launch. - 🟠 High — will hurt at the stated scale or during the first bad day; plan the fix now. - 🟡 Medium — friction, risk, or cost worth scheduling. - 🟢 Note — worth knowing; no action required. Calibrate severity to the stated context: a missing multi-region story is 🟢 for an internal tool and 🔴 for a payments platform. Never grade a startup MVP against enterprise checklists — that’s noise wearing a badge. ## Output format ALWAYS use: # Architecture review: [system] · [date] ## Verdict [2–3 sentences: overall soundness, the one thing to fix first, and what the design gets right — earned praise is part of an honest review] ## Findings ### 🔴 [Finding title] Where: [component/flow] · Lens: [failure/scale/security/…] Issue: [what breaks and under what condition — concrete scenario, not category name] Impact: [blast radius in user/business terms] Fix: [smallest adequate change; note effort S/M/L] [repeat, sorted by severity] ## Questions the design must answer [Genuine unknowns that block assessment — max 5, each stating why it matters] ## What’s good [2–4 deliberate strengths worth preserving through future changes] ## Rules - Every finding needs a failure scenario (“when the queue consumer lags, webhooks time out and Stripe retries amplify load”), not a pattern name (“tight coupling”). - Propose the smallest fix, not the ideal end-state — “add a read replica” beats “adopt CQRS” when it solves the stated problem. - If the design document is silent on something critical (backups, auth), treat silence as absence and flag it — undocumented safety is unverifiable safety. - When reviewing a diagram image or Mermaid, restate the architecture in 3–4 sentences first so misreadings surface before findings do. To test it, I fed it this deliberately broken design (count the problems): Review this architecture for an invoice SaaS: Next.js on Vercel → single Node API on one EC2 instance (t3.large) → Postgres on the same instance. PDF uploads go through the API server into local disk, then sent synchronously to the OCR API during the request (extraction takes 20–60s per invoice, users wait on a spinner). ERP sync runs as a cron on the same box every 5 min. Sessions stored in app memory. Backups: weekly pg_dump to the same disk. Everything in us-east-1. Planning to onboard first EU customer next month. It caught all of them: the EU data residency problem flagged critical, backups-on-the-same-disk flagged critical, the synchronous 60-second OCR call in the request path, in-memory sessions, the single failure domain, all ranked with concrete failure scenarios and minimal fixes rather than “consider microservices.” The trick that made the biggest difference vs vanilla prompting: forcing severity calibration to the stated context and requiring a failure scenario per finding. Without those two rules Claude produces checklist noise. I built 4 more of these for the rest of the architect workflow (design docs, ADRs, tech evaluations, cloud cost). They’re in a pack, link’s in my profile if you want them. But the one above is free forever, no strings, use it on your own systems. Happy to answer questions about how the skill format works or share the test input/output if anyone wants to reproduce it. submitted by /u/Swimming_Year5735
Originally posted by u/Swimming_Year5735 on r/ClaudeCode