codebase-navigator
Fast repository comprehension and safer edits through structured exploration
When & Why to Use This Skill
The Codebase Navigator skill streamlines repository comprehension and ensures safer code modifications through structured exploration. It systematically analyzes project architecture, identifies key entry points, and maps dependencies to provide a comprehensive overview of unfamiliar codebases, significantly reducing the risk of breaking changes during refactoring or feature implementation.
Use Cases
- Onboarding to a new project: Quickly understand the project structure, entry points, and key documentation to become productive in a fraction of the time.
- Pre-refactoring impact analysis: Map out dependencies and potential 'blast radius' before making significant architectural changes to ensure system stability.
- Bug investigation and root cause analysis: Trace execution paths and locate symbol definitions across the repository to efficiently identify and fix complex bugs.
- Architectural auditing and documentation: Document data flows, module boundaries, and external dependencies to maintain a clear and up-to-date understanding of system design.
| name | codebase-navigator |
|---|---|
| description | Fast repository comprehension and safer edits through structured exploration |
| version | 1.0.0 |
| author | Claude Memory System |
| tags | [codebase, navigation, analysis, architecture] |
Codebase Navigator Skill
Purpose
Enable faster repository comprehension and safer code modifications by systematically exploring architecture, ownership, and key documentation before making changes.
When to Use
- Starting work in an unfamiliar codebase
- Planning significant refactoring
- Before making architectural changes
- Investigating bug root causes
- Onboarding new team members
Process
1. Initial Exploration
Read in this order:
- README.md - Project overview
- CONTRIBUTING.md - Development guidelines
- CODEOWNERS - Ownership and expertise
- docs/architecture - System design
- docs/ADRs - Architecture Decision Records
2. Map Project Structure
- Identify entry points (main.ts, index.js, app.py)
- Map module boundaries
- Document data flow
- List external dependencies
3. Find Related Code
Use scripts/find_symbols.sh to locate:
- Function/class definitions
- Import statements
- Usage sites
4. Impact Analysis
Use scripts/impact_map.py to map:
- What depends on this module?
- What does this module depend on?
- Potential blast radius of changes
Scripts
find_symbols.sh
# Find all uses of a symbol
./find_symbols.sh "ClassName"
./find_symbols.sh "functionName"
impact_map.py
# Generate dependency graph
python impact_map.py --module src/auth
# Output: Visual dependency map + affected files
Output Format
Navigator generates a structured exploration report:
# Codebase Navigation Report
## Project Overview
- **Name**: my-project
- **Type**: fullstack (React + Node.js)
- **Entry Points**: src/index.tsx, server/app.ts
## Architecture
- **Pattern**: Layered (UI → Services → Data)
- **Key Modules**: auth, api, database, ui/components
## Ownership
- **auth/**: @security-team
- **api/**: @backend-team
- **ui/**: @frontend-team
## Dependencies
- React 18
- Express 4
- PostgreSQL 14
## Impact Analysis (for proposed change)
- **Direct dependencies**: 3 modules
- **Indirect dependencies**: 12 files
- **Test coverage**: 87%
- **Risk level**: Medium
Safety Checks
Before proposing changes:
- ✅ Read CODEOWNERS for affected files
- ✅ Check test coverage
- ✅ Map all dependencies
- ✅ Identify breaking changes
- ✅ Plan rollback strategy
Integration
Use before major operations:
- Refactoring: Map dependencies first
- Feature addition: Understand architecture
- Bug fixing: Trace execution path
- Code review: Verify impact
Codebase Navigator v1.0.0 - Explore before you code