| name | architecture-review |
| description | Conduct architectural reviews for new or existing software projects. Use when: (1) starting a new project and need architectural foundations, (2) reviewing architecture decisions before implementation, (3) creating ADRs or design docs, (4) evaluating technology selections, (5) assessing non-functional requirements, (6) setting up project scaffolding with built-in quality. Combines enterprise ARB governance with modern agentic coding patterns. |
Architecture Review
Conduct rigorous architectural reviews that blend enterprise governance with modern, agent-friendly development patterns. Produce decisions that are documented, defensible, and immediately actionable.
Core Philosophy
Make decisions explicit. Every significant choice becomes an ADR.
Guardrails over gates. Provide golden paths and reference architectures, not bureaucratic approval queues.
Agent-native from day one. Structure projects so AI agents can understand, modify, and extend them reliably.
Start right, stay lean. Enterprise-grade foundations without enterprise-grade overhead.
Quick Start: New Project Review
When starting a new project, run through these phases in order:
Phase 1: Strategic Alignment (5 min)
Answer these before touching code:
- What problem does this solve? One sentence.
- Who are the users? Primary persona + scale expectations.
- What are the constraints? Budget, timeline, team size, compliance requirements.
- What exists already? Existing services, data stores, or platforms to integrate with.
- What is the deployment target? Cloud provider, on-prem, edge, hybrid.
Phase 2: Architecture Decision Cascade
Work through these decisions in order. Each produces an ADR.
Phase 3: Scaffold and Ship
After decisions are made, generate the project structure. See project-scaffolding.md for the canonical directory layout and day-one checklist.
Architecture Decision Record Template
Every significant decision gets an ADR. Store in docs/adr/ with sequential numbering.
# ADR-NNNN: [Short Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
## Context
What forces are at play? What is the problem?
## Decision Drivers
- Key factor 1
- Key factor 2
## Considered Options
1. **Option A** -- pros / cons
2. **Option B** -- pros / cons
## Decision
What we chose and why.
## Consequences
What becomes easier. What becomes harder. What risks remain.
Rules:
- One decision per ADR. Never combine.
- Immutable once accepted -- supersede, don't edit.
- Keep under 2 pages. Alternatives considered is the most valuable section.
- Link related ADRs to create a decision graph.
Quality Attributes Checklist
Evaluate every architecture against these attributes. Score each as: Addressed / Planned / Not Applicable / Risk.
| Attribute | Key Questions |
|---|
| Scalability | Can it handle 10x load? Horizontal or vertical strategy? |
| Security | Auth/authz defined? Data encrypted at rest and in transit? Threat model done? |
| Reliability | Target uptime? Redundancy and failover? |
| Performance | Latency budgets? Throughput targets? |
| Maintainability | Modular? Clear boundaries? Can a new developer (or agent) be productive in a day? |
| Observability | Structured logging? Distributed tracing? Alerting? |
| Testability | Can components be tested in isolation? What is the test strategy shape? |
| Deployability | CI/CD automated? Blue-green/canary capability? Rollback plan? |
| Cost efficiency | Resource utilization optimized? Pay-per-use aligned? |
| Agent compatibility | Can AI agents understand, modify, and extend this codebase? |
Anti-Patterns to Flag
Reject architectures exhibiting these patterns:
| Anti-Pattern | Signal |
|---|
| Big Ball of Mud | No clear module boundaries, circular dependencies |
| Over-Engineering | Google-scale infra for startup workloads |
| Blind Pattern Following | "We chose microservices because Netflix" without justification |
| Infrastructure Ignorance | Designs assuming unlimited bandwidth or zero latency |
| Under-Modularization | Monolithic components that can't deploy independently |
| Over-Modularization | Hundreds of nano-services creating operational overhead |
| Document Theater | Extensive paperwork that nobody reads or acts on |
| Domain Allergy | Architecture that ignores business domain and language |
Review Outcomes
Every review produces one of these decisions:
| Decision | Meaning |
|---|
| Approved | Proceed as designed |
| Approved with conditions | Proceed with specific modifications |
| Needs more info | Specific questions must be answered first |
| Redesign required | Does not meet quality standards |
Reference Materials
- Architecture Patterns -- Hexagonal, DDD, modular monolith, microservices decision framework
- API and Data Architecture -- REST/GraphQL/gRPC, database selection, caching, event streaming
- Security and Compliance -- Zero trust, OWASP, auth patterns, supply chain, compliance
- DevOps and Quality -- CI/CD, observability, testing strategies, resilience patterns
- Agentic Patterns -- Agent-native project structure, CLAUDE.md, parallel work, quality gates
- Project Scaffolding -- Day-one directory structure, checklist, and timeline
