Claude Code로 대규모 코드베이스를 빠르게 파악하는 방법

Joining a new project with tens or hundreds of thousands of lines of code can take days to understand. With Claude Code, you can grasp the big picture in minutes. This article covers techniques for efficiently navigating large codebases.

1. Get the Full Picture Instantly

Start by having Claude Code survey the entire project.

claude -p "
Explain the overall structure of this project. Include:
- Directory layout and purpose of each
- Tech stack used
- Entry point and startup flow
- Main data flow
- Configuration files and their roles
"

In seconds, you get a “project map” more accurate than any README.

2. Visualize Dependencies

Finding where a specific module is called from is the biggest challenge in large projects.

claude -p "
Find every file that imports src/services/AuthService.ts.
Include both direct and indirect callers with depth.
"

Claude Code reads and understands code, catching indirect dependencies that grep misses.

3. Understand Code History

Combine with Git history to learn why things are the way they are.

git log --oneline -20 -- src/auth/ | claude -p "
Summarize how the auth feature evolved over these 20 commits.
Focus on design changes.
"

4. Identify Critical Files

Even in a 100K-line project, only 20-30 files truly matter. Find them.

claude -p "
Pick the 10 most important files in this project.
Explain each file's role and impact on other files.
Sort by risk level when modifying.
"

Now you know which files are safe to touch and which are landmines.

5. Read Design Patterns

Understanding the patterns used lets you write consistent new code.

claude -p "
Identify design patterns used in this project:
- Repository pattern
- Service layer
- Factory
- Strategy
- Observer
Show specific files and implementation locations.
"

6. Find Testing Gaps

Identify modules that lack test coverage.

claude -p "
List modules under src/ that have no corresponding test file.
Considering business logic importance, prioritize which
modules need tests most urgently.
"

You can spot structural gaps without even running a coverage tool. See also Claude Code Testing Strategies.

7. Parallel Investigation with Subagents

For large projects, investigate multiple directories simultaneously.

Spawn 3 subagents in parallel to investigate:
1. src/api/ - list all endpoints and auth methods
2. src/models/ - data models and relationships
3. src/middleware/ - middleware chain

Return a summary from each.

Three times faster without polluting your main context. See Subagent Patterns.

8. Save the Map in CLAUDE.md

Record what you learned in CLAUDE.md so context restores instantly next time.

# Project Structure Notes

## Entry Point
- src/index.ts -> Express server startup
- src/app.ts -> Route definitions

## Critical Modules
- src/services/AuthService.ts -> Auth core, high-risk changes
- src/repositories/ -> DB access layer, uses Prisma
- src/middleware/auth.ts -> JWT validation

## Data Flow
Request -> middleware -> controller -> service -> repository -> DB

## Known Tech Debt
- src/legacy/ is being refactored, do not touch
- src/utils/helpers.ts is a god object

See CLAUDE.md Best Practices.

Conclusion

• Survey the entire project in one shot
• Visualize direct and indirect dependencies
• Learn design history from Git
• Identify critical files and risk levels
• Read design patterns for consistency
• Find testing gaps structurally
• Parallelize investigation with subagents
• Save your map in CLAUDE.md as an asset

In 2026, you don’t read large codebases — you ask Claude Code. See the Anthropic Claude Code docs.