Originally published at claudeguide.io/debug-large-codebase-claude-code
How to Debug a 10K+ Line Codebase with Claude Code
Debugging a large codebase with Claude Code requires five practices: a CLAUDE.md architecture map, progressive disclosure (start with the bug report, drill down file by file), subagent delegation per module, git bisect automation for regressions, and structured log parsing. Claude Code's 1M token context window fits roughly 40,000 lines of code — enough to hold an entire medium-sized service, but not an entire monorepo. Strategy determines what goes in that window. For a complete Claude Code overview, see the Claude Code Complete Guide.
Why Large Codebases Are Hard for AI Agents
A 10K+ line codebase breaks the naive "dump everything and ask" approach in three ways:
Context saturation. Claude Code's context window is large (200K tokens by default in claude.ai Projects, up to 1M via the API), but filling it with entire repositories degrades reasoning quality. Studies on long-context LLM performance show accuracy degradation when the needle (relevant code) is buried deep in irrelevant hay. A 50K-line Rails app might have 3K lines directly relevant to a given bug.
File discovery. Claude cannot browse a filesystem it hasn't seen. Without explicit instruction, it will ask you to share files — or worse, hallucinate file contents based on naming conventions. The agent needs a map.
Dependency graphs. A bug in a 15-file chain (user action → service → worker → database adapter → cache layer) requires Claude to trace the call graph across the entire chain. Without knowing the graph structure upfront, it wastes turns asking "where is X defined?"
The strategies below solve each problem systematically.
Strategy 1: CLAUDE.md as a Codebase Map
CLAUDE.md is read automatically at the start of every Claude Code session. For a large codebase, it is the single highest-leverage file you can create. Treat it as a codebase orientation document for a new senior engineer joining the team.
A debugging-optimized CLAUDE.md includes:
# Architecture
## Service layout
- `src/api/` — Express route handlers, thin layer only
- `src/services/` — Business logic, all DB calls go here
- `src/workers/` — BullMQ background jobs
- `src/models/` — Sequelize ORM models
- `src/lib/` — Shared utilities (logger, cache, http client)
## Data flow
User HTTP request → `src/api/routes/*.ts`
→ `src/services/*.service.ts`
→ `src/models/*.model.ts` (Postgres via Sequelize)
→ `src/lib/cache.ts` (Redis, 5-minute TTL)
Background work: `src/workers/*.worker.ts` (BullMQ, Redis queue)
## Critical dependencies
- All external API calls go through `src/lib/http-client.ts` (has retry logic)
- All errors must be thrown as `AppError` from `src/lib/errors.ts`
- Environment config is centralized in `src/config/index.ts`
## Known complexity areas
- `src/services/billing.service.ts` — Stripe webhook idempotency logic is subtle
- `src/workers/report.worker.ts` — Memory-intensive, spawns child processes
- `src/lib/cache.ts` — Cache invalidation has three layers (local, Redis, CDN)
## How to run tests
npm test — full suite
npm run test:unit — fast, no DB
npm run test:integration — requires Docker Compose up
Why this architecture section is worth every minute it takes to write: When you open a debugging session with "there's a memory leak in production," Claude Code reads this file first. It immediately knows that memory-intensive work lives in report.worker.ts, that the cache has three invalidation layers, and that errors should come through AppError. Without the map, it spends the first 10 messages asking you to share files.
For existing codebases without a CLAUDE.md, generate a draft with:
/init
Claude Code will inspect your repository and produce a starting CLAUDE.md. Edit it to add the "Known complexity areas" section manually — that section requires your human knowledge of where the bodies are buried.
Strategy 2: Progressive Disclosure
The worst debugging prompt: "Here is my entire codebase. Find the bug."
The best debugging prompt structure:
1. Start with the symptom only
2. Share error logs / stack traces
3. Share the one file most likely to be the entry point
4. Let Claude ask what it needs next
5. Share files on demand, not upfront
Session opening template:
Production bug: users report that PDF exports are empty (blank pages)
since yesterday's deploy. This started after commit a3f9b12.
Stack trace from Datadog:
[PASTE STACK TRACE HERE]
Entry point is likely src/workers/report.worker.ts — sharing that now.
[PASTE FILE CONTENTS]
What else do you need to trace this?
This approach is more effective than dumping 20 files because:
- Claude can identify which files it actually needs from the stack trace
- The session starts focused on the symptom, not the entire codebase
- You avoid wasting 30K tokens of context on irrelevant files
Progressive file-sharing rule: Only share files that Claude explicitly asks for, or files you know are in the call path. Trust Claude's file requests — if it asks for src/lib/pdf-renderer.ts, share it. If it asks for something you know is irrelevant, redirect it.
Strategy 3: Subagent Delegation
For bugs that span multiple modules or repositories, spawn subagents to investigate in parallel. Claude Code supports this natively via the Task tool when running in agent mode, or you can orchestrate it yourself using --print mode in parallel shell sessions. For a detailed guide to parallel subagent patterns, see How to Use Claude Code Subagents for Parallel Research.
Pattern: module-parallel investigation
bash
# Terminal 1 — investigate the API layer
claude --print "Read src/api/routes/export.ts and src/api/middleware/*.ts.
Find all code paths that trigger a PDF export job.
Report: what parameters are passed to the worker?"
40 slash command templates. Token-optimized variants. JSONL file for direct import. Tested in production sessions.
[→ Get Claude Code Power Prompts 300 — $29](https://shoutfirst.gumroad.com/l/agfda?utm_source=claudeguide&utm_medium=article&utm_campaign=debug-large-codebase-claude-code)
*30-day money-back guarantee. Instant download.*
Top comments (0)