Architecture analysis and system design with Claude Code

Claude Code supports architecture work in plan mode, where it reads the codebase but cannot edit files until a plan is approved. It maps dependencies, compares design options against patterns the code already uses, drafts architecture decision records (ADRs), and plans phased migrations. Its output is a hypothesis that a dependency tool and a citation audit confirm.

Your team has a week to decide whether to split the order service out of the monolith. There are twelve Slack threads and no written proposal, and nobody has mapped what actually calls what. This page is for the developer or tech lead who owns that decision and needs a grounded proposal by Friday, one whose claims can be checked without reading 400 files.

What you’ll walk away with from architecture analysis in Claude Code

A session setup (plan mode, effort level, model) that keeps architecture analysis read-only and thorough.
Six copy-paste prompts: map the system, reconcile the map with a dependency tool, compare options, write the ADR, audit the evidence, and plan the migration.
A verification table that tells you which check proves each kind of claim and who signs off.
A way to turn the decision into a CI rule, so later agent sessions cannot quietly erode it.

How do you set up a Claude Code session for architecture work?

Architecture analysis should change nothing until a person has agreed with it. Plan mode enforces that: Claude reads files and runs only approved commands, and edits stay blocked until you accept a plan.

Start the session in plan mode at a higher effort level. In your terminal, run:
Terminal window
```
claude --permission-mode plan --effort high
```
In a session that is already running, press Shift+Tab to cycle permission modes until plan mode is active, or type /plan followed by the question. --effort accepts low, medium, high, xhigh and max (checked against claude --help, v2.1.283).
Keep the default model and tune effort first. Claude Opus 5.5 is the Claude Code default on every paid plan from v2.1.280 (the latest release channel), and it runs at medium effort by default. For a trade-off analysis, raise effort with /effort high or /effort xhigh before you change model. Switch to Claude Fable 5.1 (/model fable) only for the longest, hardest analyses, and only when your own comparison says Opus at higher effort falls short. Versions and prices live on the models hub; deep reasoning and effort levels explains the effort trade-off.
Scope the question. Name the directories, services or flows that matter. An unscoped “analyse our architecture” on a large repository fills the context window with files that do not bear on the decision. For an unfamiliar codebase, run the codebase analysis workflow first; this page assumes you already know your way around.
Put the tool-checkable facts on disk before you ask for opinions. The next section shows how.

Map the current architecture with evidence you can check

Ask for a map in which every claim cites a file and line. Citations are what make the map auditable: a claim without one is a guess.

Map the architecture of this repository for a decision about extracting order processing into its own service. Stay read-only.

Produce:
1. Modules and their responsibilities, one line each.
2. Every path from an HTTP request that touches orders, down to the database and back, including background jobs and webhooks.
3. External dependencies (databases, caches, queues, third-party APIs) and which modules own them.
4. Shared state and cross-cutting concerns (auth, transactions, logging) that order code relies on.
5. Circular dependencies and modules with too many responsibilities.

Rules: cite path:line for every claim. If you infer something from naming or configuration rather than from a call site, mark it INFERRED. List anything wired at runtime (dependency injection, plugin registries, reflection, config-driven routing) in a separate "Not visible statically" section instead of guessing.

A language model counts imports badly and misses dynamic wiring, so treat the dependency part of that map as a draft. A static analysis tool computes the same graph deterministically. For a JavaScript or TypeScript codebase, run these in your terminal (checked on 2026-09-26 with dependency-cruiser 18.4.0 and madge 8.0.0):

mkdir -p docs/architecture

# Afferent (Ca) and efferent (Ce) coupling and instability per module and folder
npx dependency-cruiser@18.4.0 src --no-config --output-type metrics > docs/architecture/metrics.txt

# Circular dependencies
npx madge@8.0.0 --circular src > docs/architecture/cycles.txt

# The whole graph as a Mermaid flowchart
npx dependency-cruiser@18.4.0 src --no-config --output-type mermaid -f docs/architecture/deps.mmd

For Python, import-linter plays the same role (pip install import-linter, then lint-imports against the contracts in your config; checked at 2.15 on PyPI); the fitness functions guide has configurations for TypeScript, Python and Java. Then make Claude reconcile its map with the tool output:

Read docs/architecture/metrics.txt and docs/architecture/cycles.txt. They come from dependency-cruiser and madge and are the source of truth for static imports.

Compare them with the architecture map you produced. List:
1. Every dependency or cycle the tools found that your map missed.
2. Every dependency in your map the tools do not show, and whether it is a runtime-only link (explain the mechanism with path:line) or an error.
3. The five modules that most violate the stable-dependencies principle: the highest Ca combined with the highest I (%). List Ca, Ce and I for each, and what in the order flow depends on it.

Then rewrite the map with the corrections. Do not keep any claim you cannot cite.

Every disagreement between the two is either a runtime link, which you now know about, or an error in the map, which you have removed. That list is worth more than either input alone. When the corrected map reads right, approve saving it (or press Shift+Tab to leave plan mode) and have Claude write it to docs/architecture/current.md; the audit later on this page reads it from there.

Compare design options against your own code

A generic comparison of microservices, a modular monolith and event-driven designs is available anywhere. The useful comparison measures each option against your call graph, your team, and the patterns the codebase already demonstrates. Give Claude the constraints it cannot see.

We are choosing how to separate order processing from the monolith. Evaluate three options:
A) modular monolith: an orders module with an enforced public interface,
B) a separate orders service called over HTTP,
C) a separate service fed by a message queue with an outbox table.

Constraints you cannot see in the code: four backend engineers, none has run a message broker in production; we deploy twice a day; checkout latency must not increase.

Use one Explore subagent per option to find the code each option would change, so the analysis of one option does not crowd out the others.

For each option give: the files and call sites that change (path:line), which transactions currently span orders and other tables and what happens to each, the failure modes it introduces, how reversible it is after one month, and what we would have to learn. End with a table and a recommendation, and state which single fact, if it turned out false, would change the recommendation.

The last instruction matters most. The fact that would change the recommendation is the thing to verify before the meeting, and it is usually cheaper to check than the whole analysis. Explore is one of Claude Code’s built-in subagents; to give a subagent your own instructions or tool limits, see custom subagents.

Do not use agent effort estimates as commitments. The agent sees the code that changes, not your review queue, your deploy windows or the edge cases that surface in staging. Ask for the list of changes and size it with the team.

Record the decision as an ADR an agent can follow

An ADR written for humans explains why. An ADR that agents follow also states the rule in a form a tool can check, and names the check. Write it after the team has decided, not before; the ADR records a human decision, it does not make one. The canonical ADR format and the machine-checkable constraint pattern are in architecture decisions agents can follow.

The team decided on option A, a modular orders module with an enforced public interface. Write docs/adr/0007-orders-module-boundary.md, no longer than one page:

- Status: accepted. Date: today.
- Context: the current coupling, citing the reconciled map and docs/architecture/metrics.txt (path:line, not prose).
- Decision: one paragraph.
- Consequences: what gets easier, what gets harder, and what we give up by not choosing B or C.
- Enforcement: a dependency-cruiser rule that forbids any import of src/orders/** from outside src/orders/ except through src/orders/index.ts. Add the rule to .dependency-cruiser.cjs and show the command that fails CI when it is broken.
- Revisit when: the concrete signal that would reopen this decision.

Also add one line to CLAUDE.md under "Architecture" that points to this ADR.

Leave plan mode before you send this prompt, or approve the plan Claude proposes for it, because it writes files. The CLAUDE.md line puts the decision into every future session’s context. The dependency rule catches the sessions that ignore it.

How do you verify the analysis without reading every file?

Nobody should read the 400 files the agent read. You check the claims with the cheapest instrument that can prove each kind, and a named person signs off on the decision.

Claim in the output	How it is checked	Who signs off
“Module X imports Y”, cycles, coupling numbers	dependency-cruiser or madge output, reconciled as shown above	The developer who ran the tools
“This flow goes through file F at line L”	A fresh-session citation audit (prompt below)	The developer, from the audit report
Runtime wiring (DI, plugins, config routing)	A trace or a test that exercises the path; logs from staging	The owner of that subsystem
“Option A is cheaper to reverse than B”	The team’s own judgement, informed by the list of changes	The tech lead, in the ADR review
“The boundary holds after the change”	The dependency rule failing CI on a violating import	CI, on every pull request

You are auditing docs/architecture/current.md and docs/adr/0007-orders-module-boundary.md. You did not write them. For every path:line citation, open the file and check that the line supports the claim next to it. Report a table: claim, citation, verdict (SUPPORTED / WRONG LINE / NOT SUPPORTED / FILE MISSING), and the correct citation if you find one. Do not fix the documents. At the end, list claims that carry no citation at all.

Run the audit in a new session (claude --permission-mode plan), not in the one that wrote the documents. A session that wrote a claim tends to confirm it. Anything marked NOT SUPPORTED goes back to the authoring session, or out of the document. The ADR is merged only after the tech lead approves it in an ordinary pull request review, with the audit report attached. The general practice of accepting evidence instead of reading diffs is described in reading evidence instead of code.

Plan the migration in reversible phases

With the decision recorded, ask for a plan in which every phase ships on its own and has a check that proves it worked.

Plan the migration to the orders module boundary in docs/adr/0007-orders-module-boundary.md. Stay in plan mode.

Constraints: each phase is one pull request that can ship and be reverted alone; the app works after every phase; no big-bang cutover.

For each phase give: the files it touches (path), what moves or changes, the test or check that proves the phase is done (an existing test, a new test to write first, or a dependency-cruiser rule to tighten), and how to roll it back. Find the hidden callers first: test helpers, admin scripts, migrations and cron jobs that import order code or query order tables directly. List them in phase 1.

Hand the approved phases to feature planning or execute them with the refactoring workflow. To keep the dependency rule ratcheting tighter as phases land, use the baseline and --ignore-known pattern from the fitness functions guide.

Keep architecture documentation current

Architecture documents written by hand go stale. Split the document in two. The deterministic part (deps.mmd, metrics.txt, cycles.txt) is regenerated by the commands above in CI on every merge (madge 8.0.0 exits with code 1 when it finds a cycle, so the step fails the build; append || true when you only want the report), so it always matches the static import graph. The narrative part is short, written by Claude from those files, and re-audited only when the graph changes materially. To regenerate the narrative on a schedule, a Claude Code routine can open a pull request with the refreshed text for a human to approve.

A minimal GitHub Actions workflow for the deterministic part runs the same pinned commands after every merge to main and uploads the three files as a build artifact. The if: always() keeps the upload when madge fails the job on a cycle, so you still get the report that explains the failure. To keep the files in the repository instead, replace the upload step with one that commits docs/architecture/ back to the branch, and raise that job to contents: write; it runs only pinned tools on main, never an agent or pull request code.

name: architecture-docs
on:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  graph:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - name: Regenerate the dependency graph
        run: |
          mkdir -p docs/architecture
          npx dependency-cruiser@18.4.0 src --no-config --output-type metrics > docs/architecture/metrics.txt
          npx dependency-cruiser@18.4.0 src --no-config --output-type mermaid -f docs/architecture/deps.mmd
          npx madge@8.0.0 --circular src > docs/architecture/cycles.txt
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: architecture-docs
          path: docs/architecture/*

What breaks when Claude Code analyses architecture?

The map misses runtime wiring. Static reading does not see dependency injection containers, plugin registries or config-driven routing. Recovery: point Claude at the registration code (“service registrations are in src/container.ts; resolve concrete implementations from there”) and confirm the critical paths with a test or a staging trace.

Citations point at the wrong lines or files that do not exist. Recovery: run the citation audit in a fresh session, and delete any claim that stays unsupported. If more than a few citations fail, re-run the map with a narrower scope; a map that wide was built from summaries, not from reads.

The recommendation does not fit your team. The agent favours what is technically clean and does not know that nobody has run the broker it recommends. Recovery: state team experience and operational limits in the prompt, and ask it to prefer patterns the codebase already demonstrates.

The coupling report flags everything. Every codebase has coupling. Recovery: ask for the five modules with the highest combination of instability and dependents, with one change per module that fits in a day.

The context fills up on a large repository. Answers get vaguer and early findings are forgotten. Recovery: split the analysis by subsystem, use Explore subagents so each exploration runs in its own context, and write intermediate findings to files the next step reads.

The decision erodes after the ADR merges. Later sessions, human or agent, import across the boundary because nothing stops them. Recovery: the dependency rule in CI, plus the CLAUDE.md pointer. Long-term drift and the thresholds that should lower an agent’s autonomy are covered in keeping an agent-written codebase healthy.

Where to go next after the architecture analysis

Architecture decisions agents can follow The canonical ADR format with machine-checkable constraints

Architecture fitness functions Enforce layering, cycles and complexity budgets in CI with configs for three stacks

Feature planning with Claude Code Turn the approved migration phases into implementable plans

Refactoring with Claude Code Execute the migration phase by phase

Working in another tool? The same workflow in Codex is in system design with Codex, and in Cursor in system design with Cursor Agent. The rest of this stage is in the Claude Code planning overview.