AI-Assisted Architecture Review: Using Claude for System Design

Why Architecture Review Needs AI Assistance

Architecture reviews are high-leverage but time-consuming. A senior engineer spending two hours reviewing a design document can save the team months of rework. But senior engineers are scarce, and most teams cannot afford to have their most experienced people review every design decision.

Claude cannot replace the judgment of a senior architect who understands the business context, team capabilities, and organizational constraints. But it can serve as a tireless first-pass reviewer that catches common anti-patterns, identifies missing considerations, and surfaces relevant trade-offs before the human review.

Design Document Analysis

The most immediate application is analyzing design documents and providing structured feedback.

flowchart LR
    INPUT(["User intent"])
    PARSE["Parse plus<br/>classify"]
    PLAN["Plan and tool<br/>selection"]
    AGENT["Agent loop<br/>LLM plus tools"]
    GUARD{"Guardrails<br/>and policy"}
    EXEC["Execute and<br/>verify result"]
    OBS[("Trace and metrics")]
    OUT(["Outcome plus<br/>next action"])
    INPUT --> PARSE --> PLAN --> AGENT --> GUARD
    GUARD -->|Pass| EXEC --> OUT
    GUARD -->|Fail| AGENT
    AGENT --> OBS
    style AGENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style OBS fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff

import anthropic

client = anthropic.Anthropic()

ARCHITECTURE_REVIEW_PROMPT = """You are a senior software architect conducting a design review. Analyze the following design document and provide structured feedback.

Review the design across these dimensions:

1. **Scalability**: Will this design handle 10x and 100x current load? Where are the bottlenecks?
2. **Reliability**: What are the failure modes? Is there a single point of failure? How does the system degrade gracefully?
3. **Security**: Are there authentication/authorization gaps? Data exposure risks? Input validation concerns?
4. **Operational complexity**: How difficult is this to deploy, monitor, and debug in production?
5. **Data consistency**: Are there race conditions? Is the consistency model appropriate?
6. **Cost**: Are there cost-inefficient patterns? Over-provisioning? Missing caching?

For each dimension:
- Rate it: STRONG / ADEQUATE / NEEDS_WORK / CRITICAL_GAP
- Provide specific, actionable feedback
- Reference relevant patterns or alternatives

Also identify:
- Assumptions that should be validated
- Questions the design does not answer
- Similar systems or prior art worth studying"""

async def review_design_document(document: str) -> dict:
    """Review an architecture design document."""
    response = await client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=8096,
        thinking={"type": "enabled", "budget_tokens": 8000},
        messages=[{
            "role": "user",
            "content": f"{ARCHITECTURE_REVIEW_PROMPT}\n\n"
                       f"## Design Document\n\n{document}"
        }]
    )

    return {
        "review": response.content[-1].text,
        "model": "claude-sonnet-4-20250514",
        "input_tokens": response.usage.input_tokens,
        "output_tokens": response.usage.output_tokens
    }

Trade-Off Analysis

One of Claude's strongest capabilities is exploring trade-offs between architectural alternatives. It can systematically compare options across multiple dimensions.

TRADEOFF_TOOL = {
    "name": "save_tradeoff_analysis",
    "description": "Save a structured trade-off analysis between architectural options.",
    "input_schema": {
        "type": "object",
        "properties": {
            "decision_title": {"type": "string"},
            "context": {"type": "string"},
            "options": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "description": {"type": "string"},
                        "pros": {
                            "type": "array",
                            "items": {"type": "string"}
                        },
                        "cons": {
                            "type": "array",
                            "items": {"type": "string"}
                        },
                        "scalability_score": {
                            "type": "integer",
                            "minimum": 1, "maximum": 5
                        },
                        "complexity_score": {
                            "type": "integer",
                            "minimum": 1, "maximum": 5
                        },
                        "cost_score": {
                            "type": "integer",
                            "minimum": 1, "maximum": 5
                        },
                        "time_to_implement": {"type": "string"},
                        "risks": {
                            "type": "array",
                            "items": {"type": "string"}
                        }
                    },
                    "required": ["name", "description", "pros", "cons"]
                }
            },
            "recommendation": {"type": "string"},
            "recommendation_reasoning": {"type": "string"}
        },
        "required": ["decision_title", "context", "options", "recommendation"]
    }
}

async def analyze_tradeoffs(decision: str, constraints: str) -> dict:
    """Generate a structured trade-off analysis."""
    response = await client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=4096,
        tools=[TRADEOFF_TOOL],
        tool_choice={"type": "tool", "name": "save_tradeoff_analysis"},
        messages=[{
            "role": "user",
            "content": f"""Analyze the architectural trade-offs for this decision:

Decision: {decision}
Constraints: {constraints}

Consider at least 3 viable options. Score each on scalability,
complexity, and cost (1=worst, 5=best). Provide a recommendation
with clear reasoning."""
        }]
    )

    for block in response.content:
        if block.type == "tool_use":
            return block.input

    raise ValueError("No structured output generated")

Example Usage

result = await analyze_tradeoffs(
    decision="How should we handle event processing for our order system?",
    constraints="500K events/day, 99.9% uptime, team of 4 backend engineers, "
                "existing AWS infrastructure, budget of $5K/month"
)

# Result includes structured comparison of options like:
# - Direct database polling
# - SQS + Lambda
# - Kafka / MSK
# - EventBridge
# Each with pros, cons, scores, and a reasoned recommendation

Automated Architecture Decision Records (ADRs)

Architecture Decision Records are a proven practice for documenting design decisions. Claude can help generate and maintain them.

ADR_TEMPLATE = """# ADR-{number}: {title}

## Status
{status}

## Context
{context}

## Decision
{decision}

## Consequences

### Positive
{positive_consequences}

### Negative
{negative_consequences}

### Neutral
{neutral_consequences}

## Alternatives Considered
{alternatives}

## References
{references}
"""

async def generate_adr(
    discussion_notes: str,
    existing_adrs: list[str],
    adr_number: int
) -> str:
    """Generate an ADR from meeting notes and discussion."""
    existing_context = "\n".join(
        f"- ADR-{i+1}: {adr[:100]}..." for i, adr in enumerate(existing_adrs)
    )

    response = await client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=4096,
        messages=[{
            "role": "user",
            "content": f"""Generate an Architecture Decision Record from these
discussion notes. Follow the standard ADR format.

## Existing ADRs (for context)
{existing_context}

## Discussion Notes
{discussion_notes}

## ADR Number
{adr_number}

Write the ADR in markdown. Be specific about the decision,
consequences, and alternatives. Reference existing ADRs where relevant."""
        }]
    )

    return response.content[0].text

Scalability Assessment

Claude can simulate load scenarios and identify bottlenecks in a proposed architecture.

async def assess_scalability(architecture_description: str, load_scenarios: list[dict]) -> str:
    """Assess architecture scalability under different load scenarios."""
    scenarios_text = "\n".join(
        f"- Scenario: {s['name']}: {s['description']} "
        f"(target: {s['target_rps']} req/sec, {s['target_latency_ms']}ms p99)"
        for s in load_scenarios
    )

    response = await client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=8096,
        thinking={"type": "enabled", "budget_tokens": 6000},
        messages=[{
            "role": "user",
            "content": f"""Perform a scalability assessment of this architecture.

## Architecture
{architecture_description}

## Load Scenarios
{scenarios_text}

For each scenario, analyze:
1. Which component becomes the bottleneck first?
2. What is the approximate maximum throughput before degradation?
3. What specific changes would be needed to handle the target load?
4. What are the cost implications of scaling to each scenario?

Use back-of-envelope calculations. Be specific about numbers:
connection pool sizes, database connections, memory usage estimates,
network bandwidth requirements."""
        }]
    )

    return response.content[-1].text

Integration with Code Review Workflows

Connect the architecture reviewer to your pull request workflow for design-level feedback on significant changes.

async def review_pr_architecture(
    pr_diff: str,
    pr_description: str,
    file_list: list[str]
) -> dict:
    """Provide architecture-level feedback on a pull request."""

    # Only trigger for significant changes
    if len(file_list) < 5:
        return {"skip": True, "reason": "PR too small for architecture review"}

    response = await client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=4096,
        messages=[{
            "role": "user",
            "content": f"""Review this PR from an architecture perspective.
Do NOT review individual code style or syntax.
Focus on:
1. Does this change introduce new architectural patterns?
2. Are there cross-cutting concerns (logging, auth, error handling) handled consistently?
3. Does this change affect system boundaries or API contracts?
4. Are there missing abstractions or unnecessary abstractions?
5. Will this change complicate future scaling or maintenance?

## PR Description
{pr_description}

## Files Changed ({len(file_list)})
{chr(10).join(file_list)}

## Diff (truncated to key files)
{pr_diff[:15000]}"""
        }]
    )

    return {
        "review": response.content[0].text,
        "review_type": "architecture",
        "files_analyzed": len(file_list)
    }

Limitations and Best Practices

What Claude is good at in architecture review:

• Identifying common anti-patterns (God objects, missing retry logic, N+1 queries)
• Exploring trade-offs between well-known architectural options
• Generating structured documentation from informal discussions
• Catching missing considerations (error handling, monitoring, rollback plans)
• Back-of-envelope capacity calculations

What Claude is not good at:

• Understanding organizational politics and team dynamics
• Knowing your specific infrastructure's quirks and limitations
• Making judgment calls that depend on business strategy
• Evaluating whether a design matches the team's skill level
• Predicting how requirements will evolve

Best practice: Use Claude as a pre-reviewer that enriches design documents with structured analysis before the human architecture review. The human reviewer then focuses on business context, team dynamics, and judgment calls that require organizational knowledge.

Summary

AI-assisted architecture review augments senior engineers by handling the systematic, pattern-matching aspects of design review. Claude excels at trade-off analysis, anti-pattern detection, structured documentation generation, and scalability assessment. The key is positioning it as a pre-reviewer that surfaces issues and structures analysis for human decision-makers, not as a replacement for the architectural judgment that comes from experience building and operating production systems.