How to Use Claude for Software Architecture: From Codebase Audit to System Design

Most developers use Claude to write functions or debug errors. That's fine — but architects and senior engineers are quietly using it for something far more powerful: understanding, designing, and documenting entire systems.

If you've ever stared at an unfamiliar codebase wondering where the business logic actually lives, or spent three hours drafting an Architecture Decision Record (ADR) that nobody reads, Claude can compress that work dramatically. This guide shows you exactly how.

Why Claude Excels at Architectural Work

Claude's large context window (up to 200K tokens in Sonnet and Opus) is the feature that makes architectural work possible. You can feed it:

• An entire service's source files
• Multiple API contracts at once
• Existing documentation + new requirements in a single prompt

Most architectural problems aren't about writing new code — they're about understanding relationships, spotting coupling, and making trade-offs explicit. Claude is very good at all three.

The model that matters for architecture work:

• Claude Haiku 4.5 — Quick lookups, formatting existing docs, simple Q&A
• Claude Sonnet 4.6 — Most architecture tasks: codebase analysis, ADR drafts, design reviews
• Claude Opus 4.6 — Complex trade-off analysis, security architecture, greenfield system design where stakes are high

Step 1: Reverse-Engineer an Existing Codebase

The first architectural question is almost always: "What does this system actually do?"

Load the Codebase Context

With Claude Code, you can reference files directly in your prompt. For API use, you paste the relevant files or use a tool like repomix to bundle your codebase into a single file.

bash# Install repomix to bundle a repo for Claude
npm install -g repomix

# Generate a single file with your entire codebase
repomix --output repo-bundle.txt --ignore "node_modules,dist,.next"

Then in Claude:

Here is my entire codebase bundled into one file:

[paste repo-bundle.txt contents]

Tasks:
1. Identify the primary bounded contexts (DDD sense) — what are the major domains?
2. Map the data flow: where does a user request enter, and what systems does it touch?
3. Flag any places where the layering looks wrong (e.g., business logic leaking into controllers)
4. Identify the top 3 architectural risks

Get a C4-Level Architecture Overview

The C4 model (Context, Containers, Components, Code) is a widely-used framework for architecture diagrams. Claude can produce text descriptions you can feed directly into Mermaid or Structurizr:

Based on the codebase above, generate a C4 Container diagram description in Mermaid format.
Include:
- External users/systems
- Main application containers (services, databases, queues)
- Key interactions between containers
- Technology labels (e.g., "Next.js", "PostgreSQL", "Redis")

Output as a Mermaid diagram code block.

Example output Claude will generate:

mermaidgraph TB
    User["User\n[Browser]"]
    WebApp["Web Application\n[Next.js 15]"]
    API["API Server\n[Node.js/Express]"]
    DB["Primary Database\n[PostgreSQL]"]
    Cache["Cache\n[Redis]"]
    Queue["Job Queue\n[BullMQ]"]

    User -->|"HTTPS"| WebApp
    WebApp -->|"REST/JSON"| API
    API -->|"SQL"| DB
    API -->|"GET/SET"| Cache
    API -->|"Enqueue"| Queue
    Queue -->|"Process jobs"| API

This turns a multi-hour documentation task into a 30-second prompt.

Step 2: Write Architecture Decision Records (ADRs)

ADRs are documents that capture why an architectural decision was made. They're extremely valuable for team alignment and onboarding — and extremely tedious to write. Claude handles this well.

The ADR Prompt Template

I need to write an Architecture Decision Record for the following decision:

**Decision:** [e.g., "Use PostgreSQL instead of MongoDB for our primary data store"]

**Context:**
- Application type: [e.g., multi-tenant SaaS, ~10K users]
- Current stack: [e.g., Next.js 15, Vercel, Node.js]
- Team size and expertise: [e.g., 3 engineers, strong SQL backgrounds]
- Key constraints: [e.g., budget, performance SLAs, compliance requirements]

**Options we considered:**
1. [Option A]
2. [Option B]
3. [Option C — the one we chose]

Write a complete ADR in the standard MADR format:
- Title
- Status (Accepted)
- Context and Problem Statement
- Decision Drivers
- Considered Options
- Decision Outcome
- Pros and Cons of each option
- Links to related decisions

Claude will produce a draft like this in seconds — one that would typically take an experienced architect 30-45 minutes to write from scratch. Your job becomes reviewing and correcting rather than writing from zero.

Batch-Generate ADRs for Legacy Systems

If you're documenting an undocumented legacy system, you can ask Claude to identify decisions that should have ADRs:

Review this codebase. List 5-8 architectural decisions that were clearly made but never documented.
For each one, give me:
1. The decision title
2. What you can infer about why it was made
3. What the likely alternatives were

I'll then ask you to write full ADRs for the most important ones.

Step 3: Design New Systems with Claude

For greenfield work, Claude is most valuable as an opinionated collaborator — not a yes-machine. The key is prompting it to surface trade-offs and disagree with you.

The Architecture Design Prompt

I'm designing a new [type of system] with these requirements:

**Functional requirements:**
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

**Non-functional requirements:**
- Expected load: [e.g., 50K requests/day, spiky]
- Latency SLA: [e.g., p99 < 500ms]
- Team: [e.g., 2 backend engineers]
- Budget: [e.g., $200/month infrastructure max]

**Constraints:**
- Must integrate with: [existing systems]
- Cannot use: [any restrictions]

Propose 2 architectures:
1. The "pragmatic" option — simplest thing that works
2. The "scalable" option — designed to 10x load

For each: describe the components, technology choices, deployment topology, and the top 3 risks.
Then tell me which one you'd recommend and why.

The critical part: ask for a recommendation. If you only ask Claude to "describe options," it will produce balanced, non-committal content. Asking it to commit forces it to reason about your specific constraints.

Validate Trade-Offs With a Devil's Advocate Pass

After you've chosen an architecture, run a second pass:

I've decided to go with [the architecture you chose]. Play devil's advocate.

What are the 5 most likely ways this architecture fails in production?
For each failure mode:
- What triggers it
- How bad is the blast radius (1-5)
- What would you change to prevent it

Be specific. Don't give generic advice like "add monitoring."

This surfaces blind spots before you've written a line of production code.

Step 4: Review Pull Requests at the Architecture Level

Code reviewers often catch bugs and style issues but miss architectural drift — when a PR subtly violates the intended structure. Claude can be your architectural lint check.

Architecture Review Prompt for PRs

Here is our documented architecture:
[paste ARCHITECTURE.md or your C4 description]

Here is the diff from a pull request:
[paste git diff output]

Review this PR specifically for architectural concerns:
1. Does it introduce any coupling that shouldn't exist?
2. Does it put logic in the wrong layer?
3. Does it create any new dependencies on external services that aren't documented?
4. Does it make any implicit architectural decisions that should be documented as ADRs?

Don't review code quality or style — only architecture.

This is a prompt worth saving as a Claude Project instruction or a CLAUDE.md snippet so any engineer can run it on demand.

Step 5: Generate Architecture Documentation Automatically

One of the highest-leverage uses of Claude is keeping architecture docs fresh. Most teams let docs rot because updating them is slow and unglamorous.

Auto-Generate a ARCHITECTURE.md

Given this codebase [paste bundle], generate a complete ARCHITECTURE.md file that covers:

1. **System overview** — What this system does in 2-3 sentences
2. **Key design principles** — What patterns/principles are consistently applied
3. **Directory structure** — What each top-level directory contains and why
4. **Data model** — Key entities and their relationships (text description, not SQL)
5. **Request lifecycle** — How a typical API request flows through the system
6. **External dependencies** — All third-party services and what we use them for
7. **Deployment architecture** — How this runs in production
8. **Known technical debt** — Areas of the code that need refactoring

Format as proper Markdown with headers. This file will be committed to the repo.

Commit this file, and then update it whenever you make significant changes. You can even automate this with a Claude Code hook that regenerates the doc on a schedule.

Practical Workflow: Architecture Session in Claude Code

Here's a real workflow to run when joining a new project or doing a quarterly architecture review:

bash# Step 1: Bundle the codebase
repomix --output /tmp/repo-bundle.txt

# Step 2: Open Claude Code with the bundle
claude --file /tmp/repo-bundle.txt

# Step 3: Run this sequence of prompts

"Give me a 5-minute onboarding for this codebase. What is it, what are the main modules, and what's the most confusing part of the structure?"

"What are the top 3 architectural risks? Be specific — cite file names and line numbers."

"List the 5 most impactful refactors, ordered by value/effort ratio."

"Generate a ARCHITECTURE.md based on everything you've seen."

This sequence takes about 10-15 minutes and replaces what would otherwise be 2-3 days of reading code and writing notes.

Common Mistakes to Avoid

Key Takeaways

• Claude's large context window makes full-codebase architectural analysis practical for the first time
• Use Sonnet 4.6 for most architecture tasks; upgrade to Opus 4.6 for greenfield design or security-critical decisions
• The best prompts ask Claude to commit to a recommendation, not just list options
• ADR generation is the highest-ROI architectural use case — turn 45 minutes into 5 minutes
• Always run a devil's advocate pass on architectural decisions before implementing them

Next Steps

If you're working toward AI architecture credentials, the Claude Certified Architect (CCA-F) exam tests exactly this kind of applied knowledge — how to structure Claude-based systems, select models for different tasks, and design multi-agent architectures.

Try our free CCA practice questions to see where you stand before diving deeper into study materials.