System Design with Claude Code
Your team is debating whether to split the monolith into microservices. Half the engineers want to go all-in on event-driven architecture. The other half think a modular monolith is better. There are twelve Slack threads, no written proposal, and the deadline for a decision is next week. Meanwhile, nobody has actually mapped the current system’s dependencies, identified the bottlenecks, or documented the trade-offs. Architectural decisions made from gut feel end up costing months of rework. Decisions made from analysis take hours.
What You’ll Walk Away With
Section titled “What You’ll Walk Away With”- A Claude Code workflow for analyzing existing system architecture, generating dependency maps, and producing architectural decision records (ADRs)
- Copy-paste prompts that create system design documents, evaluate trade-offs between architectural approaches, and generate migration plans
- A practical approach to using plan mode for safe, read-only architectural analysis before making any changes
Analyzing Your Current Architecture
Section titled “Analyzing Your Current Architecture”Before making architectural decisions, you need to understand what you have. Claude Code can read your entire codebase and produce an architectural map.
Start this analysis in plan mode (Shift+Tab twice or claude --permission-mode plan) so Claude Code reads everything without modifying anything. Plan mode is ideal for architectural analysis because you want insight, not changes.
After the analysis, drill into specific areas:
Focus on the authentication and authorization system. Trace every path from login through to route protection. Show me: which middleware enforces auth, which routes bypass it, how tokens are validated, where sessions are stored, and what happens when a token expires mid-request. Identify any inconsistencies.Generating Architectural Decision Records
Section titled “Generating Architectural Decision Records”ADRs document the “why” behind technical decisions. Claude Code can generate them from a conversation.
Claude Code examines your actual service communication patterns to ground the ADR in reality. If your order service makes 5 synchronous HTTP calls during checkout, the ADR references those specific calls rather than talking about generic “inter-service communication.”
Evaluating Architecture Trade-offs
Section titled “Evaluating Architecture Trade-offs”When you are choosing between approaches, Claude Code can lay out the trade-offs systematically.
We are evaluating three approaches for our data access layer: 1) Repository pattern with Prisma, 2) CQRS with separate read/write models, 3) Domain-driven design with aggregates. For each approach: analyze how it would fit our current codebase (look at our existing data access patterns), estimate the refactoring effort in developer-days, identify which parts of our app would benefit most and which would suffer, and rate each approach on: testability, performance, complexity, and onboarding difficulty for new engineers. Present this as a comparison table with a recommendation.The value here is not that Claude Code makes the decision for you — it is that Claude Code does the analysis legwork. Reading through 200 files to understand current data access patterns, counting affected modules, and estimating effort takes a human engineer days. Claude Code does it in minutes.
Designing New Systems
Section titled “Designing New Systems”When starting a new service or feature, Claude Code can generate the initial architecture from requirements.
We need to build a notification system that: sends email (via Resend), push notifications (via Firebase), and in-app notifications (via WebSocket). Requirements: 1) users can configure which channels they receive notifications on per notification type, 2) notifications must be delivered at-least-once with retry, 3) we need to support notification templates, 4) sending must not block the API response, 5) we need delivery tracking (sent, delivered, failed). Design the system architecture: data models, API endpoints, background job structure, and the flow from "trigger notification" to "delivered". Then generate the initial file structure with stub implementations.Dependency Mapping and Coupling Analysis
Section titled “Dependency Mapping and Coupling Analysis”Understanding coupling between modules is critical for maintainability. Claude Code can quantify it.
This analysis reveals structural problems that are invisible in day-to-day development. A utility module that half the codebase depends on but changes weekly is a ticking time bomb.
Refactoring Planning
Section titled “Refactoring Planning”When you know what needs to change, Claude Code can plan the refactoring path.
We need to extract our user management logic from the monolith into a separate service. Currently, user-related code is spread across: src/controllers/user.ts, src/models/user.ts, src/services/auth.ts, src/middleware/auth.ts, and referenced in 34 other files. Plan the extraction: 1) identify every file that would move to the new service, 2) map the API boundary (which functions are called from outside the user module), 3) design the inter-service communication (REST, gRPC, or events for each call), 4) plan the database split (which tables move, how to handle joins that cross service boundaries), 5) outline a phased migration where both old and new code work simultaneously during the transition.Claude Code’s advantage here is exhaustive analysis. It will find the reference in a test helper that manually queries the users table, or the admin script that directly imports a user model function. These edge cases are what make migrations fail.
API Design Reviews
Section titled “API Design Reviews”Before implementing an API, have Claude Code review the design.
Here is our proposed API design for the payments service (paste OpenAPI spec or route list). Review it for: 1) RESTful consistency (naming conventions, HTTP methods, status codes), 2) missing error responses (what happens when the payment fails, when the user is not found, when the amount is negative), 3) pagination for list endpoints, 4) idempotency keys for mutation endpoints, 5) versioning strategy, 6) backward compatibility with our existing client code (check what the frontend currently expects). Suggest improvements and generate the corrected OpenAPI spec.Documentation Generation
Section titled “Documentation Generation”Architecture documentation that lives in separate documents from code always gets stale. Claude Code can generate documentation directly from the source.
Generate architecture documentation from our codebase. Include: 1) a system overview with component descriptions, 2) a data flow diagram (as Mermaid syntax) showing how a request flows through the system, 3) a database schema diagram (as Mermaid ER diagram) from our migration files, 4) API documentation from our route handlers, 5) environment variable documentation (every env var referenced in the code with description and default value), 6) deployment architecture (from our Dockerfile, Kubernetes manifests, and CI config). Save to docs/architecture.md. This should be regenerated periodically, not maintained by hand.When This Breaks
Section titled “When This Breaks”Claude Code’s architecture analysis misses runtime behavior. Static code analysis shows import relationships but not dynamic dispatch, configuration-driven routing, or reflection-based patterns. If your app uses dependency injection or plugin architectures, tell Claude Code: “Our app uses an IoC container. The service registrations are in src/container.ts. Use that file to understand which concrete implementations are used at runtime.”
The generated ADR recommends an approach that does not fit your team. Claude Code optimizes for technical correctness but does not know your team’s experience. If Claude recommends event sourcing but nobody on your team has used it, add that constraint: “Our team has no experience with event sourcing. Only recommend approaches that use patterns our codebase already demonstrates.”
Dependency analysis flags too many issues. Every codebase has coupling. Focus on the top offenders: “From the coupling analysis, identify only the 5 modules that pose the highest risk (combination of high instability and high number of dependents). For each, give me a specific, actionable refactoring step that takes less than a day.”
The migration plan underestimates effort. Claude Code estimates effort based on code changes but cannot account for testing time, team coordination, and the inevitable edge cases. Multiply Claude’s estimates by 2-3x for planning purposes, and add explicit “verify in staging” checkpoints to the migration plan.
Generated documentation is too long. Architecture docs that nobody reads are useless. Add a length constraint: “Keep the overview to one page. Use bullet points, not paragraphs. The audience is a new engineer joining the team — they need to understand the system in 15 minutes.”