You just pointed Claude at your company’s monorepo — 2,400 files, 380,000 lines of code, six microservices, a shared library, and a frontend that nobody fully understands anymore — and asked it to “analyze the architecture.” What you got back was a surface-level summary that could have been written by someone who skimmed the README for thirty seconds.

Here’s the thing: that’s not Claude failing. That’s you using a scalpel like a sledgehammer.

Large-scale codebase analysis is one of the highest-leverage things you can do with Claude. Architecture mapping, dependency graphing, pattern detection, technical debt identification — this is where AI tooling genuinely saves weeks of human effort. But it requires a strategy. Not a bigger context window. Not a magic prompt. A strategy.

And that strategy looks nothing like “dump everything in and ask a question.”

Why You Can’t Just Feed Claude the Whole Repo

Let’s get the math out of the way. Claude’s context window is 200,000 tokens. That sounds enormous until you look at real codebases:

Real-World Codebase Sizes (approximate token counts):
------------------------------------------------------
Small startup app (50 files):           ~40,000 tokens
Mid-size SaaS platform (500 files):     ~400,000 tokens
Enterprise monorepo (5,000+ files):     ~4,000,000+ tokens
Kubernetes source code:                 ~12,000,000+ tokens
Linux kernel:                           ~100,000,000+ tokens

A mid-size platform already blows past the context window by 2x. An enterprise monorepo doesn’t even fit in 20 context windows. And remember, you need room for your prompt, the conversation history, and Claude’s response. Realistically, you’ve got maybe 150,000 tokens of usable space for code.

So no, you cannot feed Claude the entire repo. Not even close. Not for any codebase that actually needs “large-scale analysis.”

This is the hidden layer that trips up even experienced developers: large codebase analysis requires a top-down decomposition strategy, not a big-context brute force approach. You’re not trying to get Claude to hold the whole codebase in memory. You’re orchestrating a series of focused analyses that build up a composite understanding.

Think of it like an experienced architect reviewing a new codebase on their first week at a job. They don’t read every file. They start with entry points, trace the critical paths, identify the architectural patterns, and then drill into the areas that matter. That’s exactly the approach you need with Claude.

The Top-Down Analysis Strategy

Here’s the playbook that actually works. It’s a four-phase process, and each phase feeds into the next.

Phase 1: Structural Reconnaissance

Before Claude reads a single line of code, give it the shape of the codebase. Directory trees, package manifests, configuration files — these are tiny in token count but massive in information density.

Prompt: Structural Reconnaissance
==================================

Here's the directory structure of our application (output of `tree -L 3 --dirsfirst`):

src/
├── api/
│   ├── routes/
│   │   ├── auth.ts
│   │   ├── billing.ts
│   │   ├── projects.ts
│   │   └── users.ts
│   ├── middleware/
│   │   ├── auth.middleware.ts
│   │   ├── rate-limit.middleware.ts
│   │   └── validation.middleware.ts
│   └── index.ts
├── services/
│   ├── billing/
│   ├── notifications/
│   ├── projects/
│   └── users/
├── models/
│   ├── billing.model.ts
│   ├── project.model.ts
│   └── user.model.ts
├── shared/
│   ├── config/
│   ├── database/
│   ├── queue/
│   └── utils/
└── workers/
    ├── email.worker.ts
    ├── billing.worker.ts
    └── cleanup.worker.ts

Here's our package.json dependencies section:
[paste dependencies]

Here's our tsconfig.json:
[paste config]

Based on this structure, provide:
1. An architectural overview (what patterns is this using?)
2. The likely request flow from API to database
3. Key integration points between modules
4. Areas that look like potential complexity hotspots
5. What files should I feed you next to deepen the analysis?

This single prompt — consuming maybe 2,000 tokens of input — gives Claude enough to map the high-level architecture. It can identify that you’re running an Express/Fastify API with a service layer pattern, background workers for async processing, and a shared infrastructure layer. And critically, it tells you what to look at next.

That last point is the key insight. Let Claude guide the analysis. It’s remarkably good at identifying which files are architecturally significant based on naming conventions, directory structure, and configuration files.

Phase 2: Entry Point Analysis

Every codebase has a small number of files that reveal disproportionate information about how the system works. These are your entry points:

Main application file (app.ts, main.py, index.js): Shows bootstrapping, middleware registration, dependency injection setup
Route definitions / API endpoints: Reveals the public interface and how requests flow inward
Database schemas / models: Shows the data model, which is the skeleton everything hangs on
Configuration files: Exposes environment-specific behavior, feature flags, external integrations
Docker / deployment configs: Reveals the runtime architecture, service boundaries, infrastructure dependencies

Feed these to Claude one category at a time. Don’t lump them together. Each category is a focused analysis session.

For the route definitions, you might ask Claude to map every endpoint, its HTTP method, which middleware it passes through, and which service it calls. For the database models, you want relationship mapping, index analysis, and data flow patterns. Each session produces a piece of the architecture map.

Phase 3: Module-by-Module Deep Dives

Once you have the high-level architecture mapped, you drill into specific modules. This is where you do your real analysis — and where chunking strategy matters most.

The wrong way: Feed Claude an entire service directory (30 files, 5,000 lines) and ask “what does this service do?”

The right way: Feed Claude the service’s entry point (index.ts or the main class), its public interface (exported functions/types), and ask it to explain the module’s responsibilities and API. Then, based on what it identifies as complex or interesting, drill into specific files.

Prompt: Module Deep Dive (Billing Service)
============================================

I'm analyzing our billing service. Here's what we know from
the architecture overview:
- It handles subscription management and payment processing
- It integrates with Stripe via webhooks
- It has background workers for invoice generation

Here's the service entry point (services/billing/index.ts):
[paste file]

Here's the public types/interfaces (services/billing/types.ts):
[paste file]

Analyze this module for:
1. What are the core responsibilities?
2. What external dependencies does it have?
3. What are the failure modes? (What happens when Stripe is down?)
4. Are there any code smells or architectural concerns?
5. Which internal files should I show you next for a complete picture?

Notice the pattern: you always include context from previous phases (“here’s what we know from the architecture overview”), you feed focused slices of code, and you let Claude direct the next step.

Phase 4: Cross-Cutting Concerns

After you’ve analyzed individual modules, the final phase looks at how they interact. This is where you catch the really valuable stuff: circular dependencies, inconsistent error handling patterns, missing abstractions, coupling that shouldn’t exist.

For this phase, you don’t need to feed Claude all the code again. You feed it the summaries and findings from the previous phases and ask it to identify cross-cutting issues.

Architecture Documentation Generation

One of the highest-value outputs of codebase analysis is architecture documentation. Most codebases have either no documentation, or documentation that was accurate eighteen months ago and has drifted into fiction since.

Claude excels at generating architecture docs from code because it can simultaneously hold the structural understanding (from Phase 1), the module-level details (from Phase 3), and synthesize them into coherent documentation.

The trick is to generate documentation in layers:

System context diagram (what are the major components and how do they communicate?)
Component diagrams (what’s inside each major component?)
Data flow diagrams (how does data move through the system?)
Decision records (why was it built this way? — Claude can infer this from patterns)

Ask Claude to output these as Mermaid diagrams or PlantUML. They render directly in most documentation systems, and they’re text-based, so they can live in your repo alongside the code.

Here’s where it gets really interesting: Claude can identify architectural patterns and anti-patterns automatically. Feed it a service and it’ll tell you “this is using a repository pattern with a service layer, but the controllers are bypassing the service layer in three places, which breaks the abstraction.” That’s the kind of insight that takes a human reviewer hours to find in an unfamiliar codebase.

Code Review Automation at Scale

Beyond architecture analysis, Claude is exceptionally effective for systematic code review across a codebase. Not the “review this PR” kind of review — the “audit our entire codebase for security issues, performance problems, and style inconsistencies” kind.

The strategy here is pattern-based scanning. You define what you’re looking for, then systematically feed Claude files that match certain criteria.

Prompt: Security Audit - Authentication Patterns
==================================================

We're auditing authentication handling across our codebase.
Here's our standard auth middleware:
[paste auth.middleware.ts]

Here's how it SHOULD be used (from our best-practice example):
[paste example route with proper auth]

Now here are 5 route files. For each one, identify:
1. Routes that are missing authentication middleware
2. Routes using authentication but missing authorization checks
3. Any direct database queries that bypass the service layer
4. Hardcoded secrets or credentials
5. SQL injection or NoSQL injection vectors

Route file 1 (routes/billing.ts):
[paste]

Route file 2 (routes/admin.ts):
[paste]

[... etc]

You can process an entire codebase this way in batches. Feed Claude 5-10 files per session, with clear criteria for what to look for, and aggregate the findings. It’s not a replacement for a dedicated SAST tool, but it catches things those tools miss — logical errors, business logic vulnerabilities, architectural security gaps.

The same approach works for performance review (find N+1 queries, missing indexes, synchronous operations that should be async), style enforcement (find inconsistent error handling patterns, logging gaps, naming convention violations), and accessibility audits in frontend code.

Technical Debt Identification and Prioritization

This is where codebase analysis with Claude really pays for itself. Technical debt identification requires understanding not just what the code does, but what it should do, and where the gap between those two things creates risk.

After running through the four-phase analysis above, you have enough context to ask Claude for a technical debt assessment. Here’s what makes Claude’s debt analysis uniquely useful:

Pattern detection across modules: Claude can identify when the same problem exists in multiple places. “Your billing service, user service, and notification service all implement retry logic differently. The billing service uses exponential backoff, the user service uses fixed delays, and the notification service doesn’t retry at all. This inconsistency is a reliability risk.”

Impact estimation: Because Claude understands the architecture, it can estimate which debt items are highest risk. A missing retry in the notification service is annoying. A missing retry in the billing service costs you money.

Dependency chain analysis: Claude can trace how debt in one module creates pressure on other modules. “The user service’s lack of pagination on the list endpoint forces the frontend to implement client-side pagination, which breaks when the user count exceeds 1,000.”

Ask Claude to categorize debt by type and severity:

Architectural debt: Structural issues that require significant refactoring
Code-level debt: Individual files or functions that need cleanup
Testing debt: Missing or inadequate test coverage
Documentation debt: Gaps between code behavior and documentation
Dependency debt: Outdated, vulnerable, or unnecessary dependencies

Then ask it to prioritize based on risk, effort, and business impact. You’ll get a roadmap that would take a senior engineer a week to produce manually.

Context Management: The Practical Details

Let’s talk about the mechanics of managing context across a multi-session analysis.

Session state: Claude doesn’t remember previous conversations. Between sessions, you need to carry forward the findings. The most efficient approach is to have Claude generate a structured summary at the end of each analysis session — a “state file” that captures the architecture map, key findings, and open questions. Feed that summary into the next session as context.

Token budgeting: For each analysis session, allocate your tokens roughly like this:

20% for context from previous sessions (architecture summaries, findings)
60% for new code being analyzed
10% for your prompt and instructions
10% for Claude’s response

File selection: Not all files are worth analyzing. Skip auto-generated code (migrations, protobuf outputs, bundled files), vendored dependencies, and test fixtures. Focus your token budget on hand-written application code, configuration, and infrastructure definitions.

Parallel analysis: If you’re using the API, you can run multiple analyses in parallel. Have one Claude instance analyzing the backend services while another analyzes the frontend components. Merge the findings afterward.

Claude Code: The Native Codebase Analysis Tool

If you’re using Claude Code (the CLI tool), you get a significant advantage: Claude can directly traverse your filesystem, read files on demand, and use tools like grep, find, and tree without you manually copy-pasting code.

This changes the workflow from “feed Claude files” to “tell Claude what to investigate.” You can say “analyze the authentication flow from the API routes through the middleware to the database” and Claude Code will read the relevant files, trace the imports, and build the analysis on its own.

Claude Code also maintains context within a session more efficiently, because it’s reading files selectively rather than having everything dumped into the context at once. It reads what it needs, when it needs it, and can go back to re-read files when it discovers new connections.

The top-down strategy still applies — start with structure, then entry points, then modules — but Claude Code automates a lot of the manual file selection work.

Common Mistakes and How to Avoid Them

Mistake 1: Starting at the bottom. Don’t begin by feeding Claude individual utility functions or helper files. Start at the top — entry points, configurations, route definitions — and work downward. Bottom-up analysis without architectural context produces observations without insights.

Mistake 2: One giant prompt. “Here are 50 files, analyze everything” produces shallow analysis. Focused prompts with clear objectives produce depth. Five targeted sessions beat one sprawling session every time.

Mistake 3: Not carrying context forward. Each analysis session should build on the previous ones. If you analyze the data models in session one and the API routes in session two, session two should include a summary of session one’s findings. Without this, Claude treats each session as isolated, and you lose the cross-referencing that makes the analysis valuable.

Mistake 4: Ignoring configuration files. Developers focus on application code, but configuration files — Docker configs, CI/CD pipelines, environment variable definitions, feature flag configs — reveal architectural decisions that don’t show up in the code itself. Always include them in your analysis.

Mistake 5: Skipping the “so what?” question. Identifying that a codebase uses X pattern or has Y dependency is observation, not analysis. Always push Claude to answer “so what?” — what are the implications? What risks does this create? What should change?

The Payoff

Done well, a Claude-powered codebase analysis produces:

A complete architecture map with component diagrams, data flows, and integration points
A dependency graph showing both internal and external dependencies
A pattern catalog documenting the architectural and code patterns in use (and their consistency)
A technical debt inventory prioritized by risk and effort
A security surface analysis identifying authentication gaps, injection vectors, and data exposure risks
Onboarding documentation that gets new developers productive in days instead of weeks

That’s not a weekend project for a senior engineer anymore. It’s a structured process you can run in a day with Claude, and refresh whenever the codebase changes significantly.

The key is remembering that large codebase analysis is a strategy problem, not a context window problem. Start at the top. Work down methodically. Carry context forward. Ask focused questions. Let Claude guide you to the files that matter.

Your codebase has a story to tell. You just need to ask the right questions in the right order.

Claude for Large-Scale Codebase Analysis