You ask Claude to refactor the auth flow in a 400k-line monorepo, and it confidently edits the wrong service: the deprecated legacy-auth package instead of the live one, because it never loaded the right context. On a large codebase, the binding constraint is no longer “can the model write the code” but “does it have the right slice of the repo in context, and only that slice.”
These 15 tips cover how to navigate, understand, and safely modify enterprise-scale codebases with Claude Code without drowning it in irrelevant context or letting parallel sessions clobber each other.
CLAUDE.md layout that gives Claude the right context per package without bloating every promptClaude Code uses agentic search to understand your project structure automatically. Instead of pasting files or explaining the layout yourself, you can ask a question like “Explain how the authentication system works” and Claude will search for the auth-related files, identify the key components, trace the dependencies, follow the flow, and give you a grounded explanation.
Agentic Search Capabilities
A typical onboarding question on a data platform looks like this:
Claude searches the repo, follows the import and call chains, and answers with the endpoint handlers, the transformation pipeline, the schema relationships, and the dashboard query patterns, instead of you spending a day reading files manually.
Claude Code excels where other tools fail with massive files:
Suppose you have an 18,000-line legacy React component (the kind that accretes in any long-lived app). The trick is to give Claude a precise anchor instead of asking it to hold the whole file in its head:
Update the handleSubmit function in src/components/CheckoutForm.tsx(around line 8500) so it debounces duplicate submissions. Show mejust that function before and after, not the whole file.Find every deprecated `useLegacyFormState` call in CheckoutForm.tsxand list the line numbers, so I can decide which to migrate first.First, walk me through the validation logic in this component.Then, in a follow-up, update only the error-handling branch.Instead of grepping yourself, let Claude trace structure for you. These are prompts you type into the Claude Code REPL, not shell commands:
localStorage.”The two queries that pay off most on a large codebase are dependency-impact analysis (before a risky change) and a cross-cutting performance audit:
Structure large refactoring projects effectively:
Initial Analysis
"Analyze the current authentication system and identify areas for improvement"Create a Plan
"Create a step-by-step plan to migrate from session-based to JWT authentication"Implement Incrementally
"Step 1: Create new JWT utility functions""Step 2: Update user model to support refresh tokens""Step 3: Modify login endpoint"Verify Each Step
"Write tests for the JWT utilities""Verify backward compatibility"Task Breakdown Strategy
Optimize Claude’s performance with targeted context:
# Less effective: Vague request"Optimize our application"
# More effective: Focused request"Optimize the database queries in the UserRepository class"
# Even better: Specific context"The getUsersWithOrders method in UserRepository has N+1 query issues. Optimize it using eager loading."The real constraint is the context budget, not a line count. Current models (Claude Fable 5, Opus 4.8, and Sonnet 4.6) carry a 1M-token window, but every file you pull in competes for it, and quality degrades as you fill it with irrelevant code. As a rough rule of thumb:
--add-dir, lean on hierarchical CLAUDE.md files, and work module by module.Run parallel Claude Code instances, each scoped to one area of the repo. Start each one in its own terminal with the relevant working directory:
# Terminal 1: Frontendclaude --add-dir ./frontend
# Terminal 2: Backend APIclaude --add-dir ./backend
# Terminal 3: Database migrationsclaude --add-dir ./database
# Terminal 4: Testsclaude --add-dir ./testsThen drive each session with a focused prompt, for example “Implement the new user dashboard” in the frontend instance and “Create REST endpoints for the dashboard data” in the backend one.
Benefits of parallel instances:
Use the filesystem as the handoff point between instances. One generates artifacts; the others consume them:
shared/types/api.types.ts.”shared/types/api.types.ts.”shared/types/ with usage examples.”Shared Workspace Patterns
project/├── .claude/│ ├── generated/ # AI-generated code│ ├── templates/ # Reference implementations│ └── workspace/ # Shared working files├── docs/│ └── ai-sessions/ # Session documentationStudy external patterns without copying their source into your repo (which drags in licensing baggage). Have Claude summarize the approach, then design your own:
Structure documentation for large monorepos:
monorepo/├── CLAUDE.md # Global rules and patterns├── packages/│ ├── frontend/│ │ ├── CLAUDE.md # Frontend-specific│ │ └── src/│ │ └── components/│ │ └── CLAUDE.md # Component guidelines│ ├── backend/│ │ ├── CLAUDE.md # Backend patterns│ │ └── src/│ │ ├── services/│ │ │ └── CLAUDE.md # Service patterns│ │ └── models/│ │ └── CLAUDE.md # Data model rules│ └── shared/│ └── CLAUDE.md # Shared code rulesExample hierarchical documentation:
# Monorepo Overview
## Architecture Principles- Microservices with shared libraries- Event-driven communication- TypeScript throughout
## Global Standards- Conventional commits- 100% test coverage for shared code- No circular dependencies# User Service
## Responsibilities- User authentication- Profile management- Permission handling
## Dependencies- Shared auth library- Database service- Event bus
## Patterns- Repository pattern for data access- JWT for authentication- Event sourcing for auditHelp Claude understand your system design:
# Architecture Documentation
## System Overview```mermaidgraph TD A[API Gateway] --> B[User Service] A --> C[Product Service] A --> D[Order Service] B --> E[PostgreSQL] C --> F[MongoDB] D --> E D --> G[Redis Cache] B --> H[Event Bus] C --> H D --> H```
## Design Patterns1. **Repository Pattern**: All database access through repositories2. **CQRS**: Separate read/write models for complex domains3. **Event Sourcing**: Audit trail for critical operations4. **Circuit Breaker**: For external service calls5. **Saga Pattern**: For distributed transactions
## Communication Patterns- **Sync**: REST APIs with OpenAPI specs- **Async**: RabbitMQ for events- **Real-time**: WebSockets for live updates
## Data Flow1. Client → API Gateway (authentication)2. Gateway → Microservice (authorized request)3. Service → Database (data operation)4. Service → Event Bus (state change)5. Other Services → Event Bus (react to changes)Ask sophisticated questions about code relationships:
# Dependency analysis"Show me all services that depend on the User model""What would break if I change the authenticate method signature?""Find circular dependencies in our import structure"
# Performance analysis"Identify all database queries in hot code paths""Find synchronous operations that could be async""Show me all uncached expensive computations"
# Security audit"Find all user input that isn't validated""Show me everywhere we construct dynamic SQL""Identify exposed sensitive data in API responses"
# Architecture validation"Verify all services follow our repository pattern""Find direct database access outside of repositories""Check if any frontend code imports backend modules"Manage token usage in large projects:
# 1. Clear frequently/clear
# 2. Focus conversations"Work only on the authentication module"
# 3. Use specific file references@auth/login.service.ts# Instead of: "the login service file"
# 4. Compress context/compact
# 5. Remove unnecessary files"Ignore test files for this task"Typical token usage by task:
- Simple bug fix: 2K-5K tokens- Feature implementation: 10K-20K tokens- Large refactoring: 50K-100K tokens- Architecture analysis: 20K-50K tokens
Cost optimization:- Use Claude Sonnet 4.6 for routine tasks- Reserve Claude Opus 4.8 for complex refactors and architecture analysis- Use Claude Fable 5 (/model fable) when velocity and quality matter most- Clear between unrelated tasks- Focus on specific modulesDocument each major module comprehensively:
# Payment Module Documentation
## OverviewHandles all payment processing including credit cards,PayPal, and cryptocurrency payments.
## Key Files- `payment.service.ts` - Main service orchestrator- `processors/` - Payment processor implementations- `models/transaction.model.ts` - Transaction data model- `webhooks/` - Payment provider webhooks
## Critical Business Logic1. **Retry Logic**: 3 attempts with exponential backoff2. **Idempotency**: Use transaction_id to prevent duplicates3. **Audit Trail**: Every operation logged to audit_log table4. **Refunds**: Max 90 days, requires manager approval
## Integration Points- User Service: For customer data- Order Service: For order fulfillment- Notification Service: For payment receipts- Audit Service: For compliance logging
## Testing Requirements- Unit tests: Mock all external providers- Integration tests: Use sandbox environments- Load tests: 1000 TPS minimum- Security tests: PCI compliance required
## Common Issues1. Webhook timeouts - implement async processing2. Currency conversion - cache rates for 1 hour3. Failed payments - clear user communication4. Partial refunds - complex state managementApproach large refactoring systematically:
Analyze Current State
"Analyze the authentication system and create a refactoring plan"Create Safety Net
"Write comprehensive tests for current authentication behavior"Refactor in Small Steps
"Step 1: Extract authentication logic into separate service""Step 2: Create interfaces for authentication providers""Step 3: Implement JWT provider""Step 4: Add OAuth providers"Maintain Backward Compatibility
"Create adapter layer for old authentication API"Migration Strategy
"Create migration plan for existing sessions"Incremental Refactoring Rules
Use Claude to find patterns and inconsistencies:
# Find inconsistent patterns"Find all different error handling patterns in our codebase""Show me all the different ways we're validating email addresses""Identify inconsistent naming conventions"
# Locate duplicate code"Find similar code patterns that could be refactored""Show me duplicate business logic across services"
# Architecture violations"Find all places where the presentation layer directly accesses the database""Show me services calling other services synchronously"
# Performance patterns"Find all N+1 query patterns""Locate all synchronous I/O in request handlers""Show me all uncached database queries"A security sweep is one of the highest-leverage uses of pattern recognition on a large codebase. A single prompt can surface every risky query construction at once:
A sweep like this typically surfaces a handful of distinct query-building styles and points you straight at the ones that interpolate untrusted input, instead of you auditing thousands of call sites by hand.
Develop systematic approaches for understanding large codebases:
# 1. High-level understanding"What does this project do? Explain the main purpose and architecture"
# 2. Identify entry points"Show me the main entry points for this application"
# 3. Trace critical paths"Trace the flow of a user login request"
# 4. Understand data model"Explain the core data models and their relationships"
# 5. Identify key patterns"What design patterns are used in this codebase?"# 1. Locate feature code"Where is the payment processing implemented?"
# 2. Understand dependencies"What does the payment system depend on?"
# 3. Find related tests"Show me all tests for payment processing"
# 4. Check documentation"Is there documentation for the payment system?"
# 5. Identify edge cases"What edge cases does the payment system handle?"# 1. Reproduce understanding"Explain how the user authentication flow works"
# 2. Locate problem area"Where might a login failure occur?"
# 3. Check recent changes"What changed recently in authentication?"
# 4. Find similar issues"Are there similar patterns that might have the same bug?"
# 5. Propose fixes"Suggest fixes for the authentication timeout issue"Large Codebase Checklist
/costKey principles for success:
Large codebases fail in specific, recognizable ways. Here’s what to watch for and how to recover.
Context-window overflow on a giant file. You ask Claude to edit a 20k-line file and it loses track, edits the wrong block, or truncates. Recovery: stop loading the whole file. Anchor the change to a function name and line range, or ask for the target region first (“show me just handleSubmit”), then edit that slice in a follow-up.
Agentic search misses dynamically-referenced code. Search finds static imports but not handlers wired up by string keys, reflection, or a registry built at runtime, so a “find every caller” sweep comes back incomplete. Recovery: name the indirection explicitly (“we register routes by string in router.config.ts; trace those too”) and cross-check with a literal grep before you trust the list for a risky refactor.
Parallel instances clobber a shared file. Two sessions both edit shared/types/api.types.ts and the second silently overwrites the first. Recovery: give each instance a non-overlapping directory scope, commit (or stash) between handoffs so the filesystem is the single source of truth, and never let two instances own the same file at once.
Stale CLAUDE.md drift. A CLAUDE.md still describes the old session-based auth after you migrated to JWT, so Claude follows instructions that no longer match reality. Recovery: treat CLAUDE.md as code, review it in PRs, and periodically ask Claude to reconcile it (“compare the auth section of this CLAUDE.md against the actual auth/ package and flag anything out of date”).
The repo is too big to reason about at all. Even scoped prompts wander because the package itself is a tangle. Recovery: don’t ask for a change, ask for a map first (“produce a dependency diagram of this package and identify the three highest-coupling modules”), then refactor against that map one module at a time.
With strategies for large codebases in hand, the next lever is your day-to-day loop. Continue to Workflow Optimization to turn these one-off techniques into repeatable habits, then see Performance and Cost Management for keeping token spend in check at scale.