Guide Architect Reviewer

A senior architecture reviewer agent that evaluates system designs, architectural decisions, and technology choices, helping you assess design patterns, scalability, integration strategies, and technical debt to build sustainable, evolvable systems.

When to Use This Agent

Choose Guide Architect Reviewer when:

• Reviewing architecture proposals or RFCs before approval
• Evaluating whether a system design meets scalability and reliability requirements
• Assessing technical debt and prioritizing architectural improvements
• Reviewing technology choices for new services or major migrations
• Conducting post-mortem architectural analysis after incidents

Consider alternatives when:

• Creating new system designs from scratch (use an SDD helper agent)
• Reviewing code-level implementation details (use a code reviewer agent)
• Evaluating infrastructure costs (use a cloud cost optimization agent)

Quick Start

Copy
# .claude/agents/guide-architect-reviewer.yml
name: Guide Architect Reviewer
description: Review and evaluate system architecture decisions
model: claude-sonnet
tools:
  - Read
  - Glob
  - Grep
  - WebSearch

Example invocation:

claude "Review the architecture of our order processing system in src/services/orders/ and identify scalability bottlenecks and coupling issues"

Core Concepts

Architecture Review Framework

Dimension	Key Questions	Red Flags
Coupling	How tightly are components connected?	Direct DB access across services, shared mutable state
Cohesion	Does each module have a single responsibility?	God classes, mixed domain logic, utility dumping grounds
Scalability	Can the system handle 10x growth?	Synchronous chains, single DB for all services, no caching layer
Resilience	What happens when components fail?	No circuit breakers, no retry policies, cascading failure paths
Operability	Can you debug and monitor in production?	No structured logging, missing health checks, no tracing
Evolvability	How easy is it to change?	Hardcoded configs, no feature flags, tight schema coupling

Architectural Smell Detection

Copy
## Review: Order Processing System

### Finding 1: Distributed Monolith (Severity: High)
**Evidence:** OrderService directly calls InventoryService,
PaymentService, and ShippingService via synchronous HTTP.
A failure in any downstream service blocks order creation.

**Impact:** System availability = product of all service
availabilities (99.9%^4 = 99.6%, losing 3.5 hours/year).

**Recommendation:** Introduce async messaging for non-critical
paths. Payment must be synchronous, but inventory reservation
and shipping notification can be event-driven.

### Finding 2: Shared Database Anti-Pattern (Severity: High)
**Evidence:** OrderService and ReportingService both read/write
the `orders` table directly. Schema changes require coordinated
deployments of both services.

**Recommendation:** Implement CQRS — OrderService owns the write
model, publish domain events, ReportingService maintains its own
read-optimized projection.

Review Scoring Matrix

Copy
interface ArchitectureScore {
  coupling: number;        // 1-5 (1=tightly coupled, 5=loosely coupled)
  cohesion: number;        // 1-5 (1=low cohesion, 5=high cohesion)
  scalability: number;     // 1-5 (1=won't scale, 5=horizontally scalable)
  resilience: number;      // 1-5 (1=fragile, 5=fault-tolerant)
  operability: number;     // 1-5 (1=opaque, 5=fully observable)
  evolvability: number;    // 1-5 (1=rigid, 5=easily adaptable)
  security: number;        // 1-5 (1=vulnerable, 5=defense-in-depth)
  overall: number;         // Weighted average
}

// Example scoring
const orderSystemScore: ArchitectureScore = {
  coupling: 2,       // Synchronous chains between services
  cohesion: 4,       // Services have clear domain boundaries
  scalability: 2,    // Single DB, no caching, sync calls
  resilience: 1,     // No circuit breakers, cascading failures
  operability: 3,    // Basic logging, no distributed tracing
  evolvability: 3,   // Some abstractions, but shared DB limits changes
  security: 4,       // Auth/authz in place, secrets managed
  overall: 2.7,      // Needs significant architectural work
};

Configuration

Parameter	Description	Default
review_depth	Review thoroughness (quick, standard, deep)	standard
focus_areas	Specific dimensions to prioritize	All dimensions
severity_threshold	Minimum severity to report (low, medium, high, critical)	medium
include_recommendations	Include fix recommendations with findings	true
compare_patterns	Compare against known architectural patterns	true
output_format	Report format (markdown, json, html)	markdown

Best Practices

1. Start every review by understanding the business context and constraints. Architecture decisions that seem wrong in isolation often make sense given business constraints (team size, deadlines, regulatory requirements). Ask what problem the system solves, what the growth trajectory looks like, and what the team's operational capacity is before judging technical choices. A monolith may be the right choice for a team of three.

2. Focus findings on the highest-impact architectural boundaries. The most damaging architectural problems live at service boundaries, data ownership decisions, and infrastructure dependencies. A poorly structured function can be refactored in a day. A shared database between services or a synchronous dependency chain takes weeks to fix and causes production incidents in the meantime. Prioritize findings by blast radius.

3. Distinguish between incidental and essential complexity. Some complexity is inherent to the problem domain (financial regulations, distributed consensus). Other complexity is introduced by unnecessary abstractions, premature optimization, or cargo-culted patterns. Reviews should reduce incidental complexity while respecting essential complexity. "This is complex but necessarily so" is a valid finding.

4. Evaluate architecture against its stated requirements, not theoretical ideals. A system that handles 100 requests per second does not need a design review advocating for event sourcing and CQRS. Match recommendations to actual scale, reliability, and performance requirements. Over-engineering a system creates maintenance burden without delivering proportional value. Recommend the simplest architecture that meets stated requirements.

5. Document findings with evidence, impact, and effort estimates. Every finding should include concrete evidence from the codebase, a clear explanation of the risk or impact, and a rough effort estimate for remediation. This transforms reviews from opinion pieces into actionable engineering plans. Categorize findings by effort (quick wins, medium projects, major initiatives) to help teams prioritize effectively.

Common Issues

Review recommendations are ignored because they lack business justification. Technical findings like "this is tightly coupled" do not motivate business stakeholders to allocate engineering time. Translate architectural risks into business outcomes: "This coupling means deploying a pricing change requires coordinating three teams and carries a 15% rollback rate, adding 2 weeks to every pricing initiative." Connect technical debt to velocity, reliability, and revenue impact.

Architecture review happens too late to influence design decisions. When reviews occur after implementation is complete, findings become expensive rework rather than course corrections. Establish lightweight architecture review checkpoints at the RFC/proposal stage, after the first milestone, and before launch. Early reviews are cheaper to act on and prevent architectural problems from compounding.

Reviewers focus on technology choices over structural decisions. Debating whether to use Redis vs. Memcached or PostgreSQL vs. MySQL matters far less than whether the caching layer exists at the right abstraction level or whether the data model supports the query patterns. Effective architecture reviews focus on boundaries, data flow, failure modes, and operational characteristics rather than specific technology preferences.