Using Claude for System Design Reviews

1. What a system design review with Claude actually delivers

A classic system design review happens in a meeting: an architect presents a diagram, the team asks questions, someone takes notes. The problem is well known: questions arise spontaneously, depend on who happens to be in the room that day, and rarely get fully captured. A system design review with Claude complements this format by introducing a second, consistent checking instance that walks through the same architecture using the same grid every time: scalability, consistency model, failure domains, security boundaries and operating cost.

Expectations matter here. Claude knows neither a company's internal politics nor the actual load distribution in production. A Claude system design review therefore does not replace the experienced architect who brings contextual knowledge about the team and the system's history. What it reliably replaces is the silent skimming over detail problems that simply find no time in a one hour meeting. In the same time a human needs to read the diagram once, Claude can cross check the document against dozens of known architecture patterns and anti-patterns.

In practice, the system design review works best as a preceding step before the human meeting. Claude identifies open questions and weak spots in the draft, the team then discusses these points specifically instead of starting from zero. This order, AI review before team review, has proven significantly more efficient in several projects than the reverse path.

2. Preparing architecture documents as proper input

The quality of a system design review with Claude depends directly on the quality of the input material. A pure diagram without a text description provides too little context, because Claude can interpret images but labels, arrows and implicit assumptions are captured more precisely in text form. A format that has proven effective describes components, data flows, expected load and explicit non-goals in prose, complemented by a simple diagram as a visual aid.

A second important building block is non-functional requirements. Without figures for expected latency, throughput and availability target, no system design review can meaningfully assess whether an architecture decision is appropriate. A system serving 50 requests per second needs different patterns than one serving 50,000. Claude typically asks targeted follow up questions when figures are missing, but whoever supplies these numbers from the start gets more precise and faster answers.

# Prepare a structured design doc for Claude Code before the review session
mkdir -p docs/design-reviews
cat > docs/design-reviews/order-service-v2.md << 'DOC'
# Order Service v2 - Design Doc

## Goal
Split monolithic order processing into a dedicated service.

## Non-functional requirements
- Expected load: 300 req/s peak, 40 req/s average
- Target p99 latency: 200ms
- Availability target: 99.9%
- Consistency: strong for payment state, eventual for order history

## Components
- API gateway -> Order Service (REST) -> Payment Service (gRPC)
- Order Service writes to PostgreSQL (primary), publishes events to Kafka
- Read model in Elasticsearch, updated via Kafka consumer

## Explicit non-goals
- No multi-region active-active in this iteration
- No support for offline order creation
DOC

# Ask Claude Code to review the doc against the actual codebase
claude "Review docs/design-reviews/order-service-v2.md against the current
codebase in src/OrderService. Focus on scalability bottlenecks, consistency
guarantees between the Postgres write and the Kafka publish, and failure
domains. List concrete risks with severity, not general advice."

For a Claude system design review, it also pays off to include existing code as additional context. Claude Code can work directly inside the repository and cross check the planned draft against the actual state of the codebase, instead of only evaluating the theory in the document. This surfaces discrepancies between planned and lived architecture that would remain invisible in a pure diagram review.

3. Analyzing scalability and bottlenecks systematically

Scalability is the area where a system design review with Claude works particularly reliably, because many scaling problems can be derived from known patterns. Claude typically checks: where is the single point of failure, which component becomes the bottleneck first as load rises, is there a central database write path that does not scale horizontally. These questions can be answered with high accuracy from a precise architecture description.

A concrete example from practice: in a system design review for a checkout flow, Claude identified that the planned draft synchronously validated every order confirmation against three external payment providers before responding to the customer. At 300 requests per second and an average external latency of 400 milliseconds per provider, this would have made the 200 millisecond p99 target impossible. The solution, asynchronous validation with optimistic confirmation, only became visible through this calculation in the review, not through the diagram alone.

It matters that Claude demands concrete numbers during the scalability analysis instead of accepting vague statements. A good prompt for a Claude system design review explicitly asks: "Calculate with the given load figures whether component X can handle the throughput, and show the calculation." Without this prompt, answers often stay at the level of general best practices, which is too little for a truly reliable system design review.

4. Consistency and availability: evaluating CAP tradeoffs

Every distributed system implicitly makes a decision between consistency and availability as soon as a network partition scenario occurs. A clean system design review with Claude makes this decision explicit instead of letting it silently disappear into the code. Claude can classify, per component, whether strong consistency, sequential consistency or eventual consistency applies, and whether that choice fits the business requirement.

A common pattern that surfaces in review: a team chooses eventual consistency for a payment data model because it is generally seen as a "scalable pattern", without considering that duplicate credits or lost cancellations are unacceptable from a business standpoint. A thorough system design review asks the pointed counter question here: what business consequence does a consistency loss have in this concrete data model, and is the team willing to accept that consequence?

{
  "review_finding": "consistency-tradeoff",
  "component": "PaymentLedgerService",
  "current_design": "eventual consistency via Kafka, read model updated async",
  "risk": "double-credit possible during consumer lag or replay",
  "business_impact": "financial correctness violated, manual reconciliation required",
  "recommendation": "strong consistency for ledger writes (synchronous DB transaction), eventual consistency acceptable for read-only reporting views",
  "severity": "high",
  "requires_human_decision": true
}

The outcome of such a system design review is rarely a finished decision, but a clearly formulated question with consequences that the team then answers deliberately. That is exactly the added value: Claude does not make the tradeoff decision itself, but it prevents that decision from being made implicitly and unnoticed.

5. Security architecture in review: threat modeling support

A complete system design review considers security aspects from the start instead of adding them as a separate step after implementation. Claude is well suited for a lightweight threat modeling exercise using the STRIDE scheme (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege), applied to every component and every trust boundary in the draft.

In a Claude system design review for a new authentication component, this method identified, for example, that an internal service to service conversation was planned without mTLS, because the team implicitly assumed internal network equals trustworthy. This assumption, known in security circles as a zero trust violation, would hardly have surfaced in a pure functional review, because the code itself worked correctly.

Important: Claude does not replace formal penetration testing or a specialized security audit by experts. A system design review with AI support is an additional, early filter that uncovers obvious structural weaknesses before the more expensive, later checks even begin.

6. Estimating cost and infrastructure impact

Architecture decisions have direct cost consequences that often get lost in a purely technical system design review. Based on the given load figures, Claude can provide rough estimates of infrastructure cost: how many instances of a given size are needed for the expected load, how much data volume accumulates at what retention, what costs arise from additional network transfer between regions.

These estimates are deliberately rough and do not replace a detailed cost calculation by the infrastructure team. The value lies in the fact that a system design review with Claude surfaces expensive design decisions early, for example a planned architecture with synchronous cross region replication whose network costs at realistic load would amount to a multiple of the actual compute cost. Such a note in review often changes the entire discussion before a single server gets provisioned.

7. Capturing review results as an Architecture Decision Record

A system design review whose results land nowhere evaporates by the time another team member asks the same question six months later. Architecture Decision Records, ADR for short, are the established format for permanently capturing decisions with context, alternatives and reasoning. Claude is excellent at automatically producing a cleanly structured ADR draft from a review discussion.

The process looks like this in practice: after the Claude system design review and the subsequent team discussion, Claude summarizes the decision made, the alternatives discarded and the concrete reasons in an ADR document. The team reviews and corrects this draft instead of writing it from scratch, which noticeably lowers documentation effort and increases the likelihood that ADRs actually get maintained.

# Generate an ADR draft from review notes with Claude Code
claude "Read docs/design-reviews/order-service-v2.md and
docs/design-reviews/review-notes-2026-07-28.md. Draft an Architecture
Decision Record in the MADR format under
docs/adr/0014-order-service-consistency-model.md. Include: Context,
Decision Drivers, Considered Options, Decision Outcome, Consequences.
Keep it factual, do not invent decisions that were not discussed."

8. Common mistakes in AI assisted design reviews

The most common mistake is blind trust in the completeness of the system design review. Claude only evaluates what is written in the input document. If a component is missing from the description, it also does not appear in the analysis, even if it exists in the real system and is critical. Whoever submits an incomplete document gets an incomplete review, regardless of how thorough the analysis is for the part that was described.

# Pseudo-checklist a reviewer runs before trusting an AI system design review
checklist = {
    "all_components_documented": False,   # missing components = blind spots
    "load_numbers_provided": False,       # vague load = vague analysis
    "non_goals_stated": False,            # scope creep risk otherwise
    "existing_code_referenced": False,    # design vs. reality drift
    "failure_domains_listed": False,      # partial reviews miss cascading failures
}

def is_review_input_reliable(checklist: dict) -> bool:
    """A design review is only as good as its input completeness."""
    return all(checklist.values())

A second mistake is ignoring organizational context. Claude knows no internal team capacities, no ongoing migration projects and no political constraints that make a technically optimal solution practically impossible. A system design review with Claude delivers the technical perspective, the human contextualization within the organizational framework remains the team's task. A third mistake: treating the review as a one time step instead of a recurring process. Architectures change, and a review that is a year old rarely reflects the current state.

9. System design review methods compared

The following overview positions the Claude system design review against established alternatives. None of the methods exclude the others, in practice the combination works best.

The practical flow that has proven effective: first a system design review with Claude as a fast, cheap first filter, then the team meeting with the already identified open questions, for highly critical systems complemented by a formal review board or external expertise for the final sign off.

10. Summary

A system design review with Claude works best as a preceding, systematic filter before the human architecture meeting. Claude checks scalability using concrete load figures, makes CAP tradeoffs explicit, applies lightweight threat modeling and estimates rough infrastructure costs. The quality of the review depends directly on the quality of the input document: a complete component list, concrete load figures and explicit non-goals are mandatory.

Claude does not replace an experienced architect or a formal architecture review board for highly critical systems, but it reliably prevents obvious structural weaknesses from silently migrating into implementation. The subsequent documentation as an Architecture Decision Record, also prepared with Claude, ensures that the decision and its reasoning remain traceable months later.

11. FAQ: Claude for System Design Reviews