| name | Architecture Review |
| description | This skill should be used when the user asks to "review architecture", "assess design", "evaluate scalability", "check technical debt", "review system design", "analyze patterns", "assess microservices boundaries", "evaluate technology choices", or discusses architectural decisions. Provides systematic architecture review methodology and pattern analysis. |
| version | 1.1.0 |
| disable-model-invocation | false |
Architecture Review
When to Use
- Evaluating system designs or proposing architectural changes
- Assessing technology choices or migration strategies
- Reviewing microservices boundaries and integration patterns
- Identifying and prioritizing technical debt
- Writing or reviewing Architecture Decision Records (ADRs)
When NOT to use:
- Code-level review (style, naming, test coverage) — that's a code review, not architecture
- Simple implementation questions ("how do I use X library")
- Operational troubleshooting (debugging a specific failure)
Our Conventions
- No project-specific conventions established yet. Add patterns here as the team adopts them.
- Project-specific CLAUDE.md or README conventions take priority over these defaults.
Review Methodology
Phase 1: Context First
Before evaluating anything, answer:
- What problem does this system solve and for whom?
- What are the scale requirements (users, data volume, request rate)?
- What constraints exist (team size, budget, timeline, existing tech)?
- What is the expected evolution path over 6-12 months?
Skip this and the review will be shallow.
Phase 2: Systematic Assessment
For each major component, evaluate:
- Does the pattern fit the actual requirements (not hypothetical future ones)?
- Are boundaries and data ownership clear?
- What are the failure modes?
- What operational burden does this add?
Phase 3: Prioritized Output
Organize findings as:
- Critical — must fix before production (security holes, data loss risks, single points of failure)
- Important — should address within next cycle (scalability bottlenecks, missing observability)
- Minor — nice-to-have improvements
- Strengths — what to reinforce and not accidentally break
Common Pitfalls
- Reviewing against hypothetical scale: Don't penalize a monolith serving 1K users for not being microservices-ready. Review against actual requirements and the 6-12 month horizon.
- Confusing operational complexity with bad design: Microservices trade development simplicity for deployment complexity. That's a deliberate trade-off, not a flaw — unless the team can't operate it.
- Missing the distributed monolith: Services that must deploy together, share a database, or make synchronous call chains are a distributed monolith — all the operational cost with none of the benefits.
- Ignoring team context: An elegant hexagonal architecture is wrong if the team has 3 months of experience. Architecture must match team capability.
- Skipping failure mode analysis: Every integration point is a failure point. Ask: "what happens when X is down?" for every external dependency.
- ADRs that don't record alternatives: The value of an ADR is capturing why you chose this approach over others. A decision without alternatives is just documentation.
Decision Guide
| Situation | Approach |
|---|
| Small team, unclear domain boundaries | Modular monolith — extract services later when boundaries prove stable |
| Components need independent scaling/deployment | Microservices, but only after confirming team can operate them |
| High-throughput async workflows | Event-driven architecture with idempotent consumers |
| Read and write patterns differ dramatically | CQRS — but only if the complexity is justified by measurable performance needs |
| Choosing between technologies | Weighted decision matrix; time-box PoC to 2-3 days testing the hardest integration point |
| Irreversible decision (DB schema, public API) | Full ADR with alternatives; get team consensus |
| Reversible decision (internal library, pattern) | Decide quickly, document lightly, iterate |
| Prioritizing technical debt | Impact/effort matrix: high-impact/low-effort first, deprioritize low-impact/high-effort |
References
references/review-checklist.md — Comprehensive checklist covering business alignment, quality attributes, operational readiness, and technology choices. Use as a systematic walkthrough for formal reviews.
