Codebase Navigator Skill Skill

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

Agent Skills: Codebase Navigator Skill

Skill Files