Learn Unfamiliar Codebase

Learn Unfamiliar Codebase Skill

Overview

This skill provides a systematic approach to rapidly onboarding onto, understanding, and navigating large, unfamiliar codebases. It is designed to move an agent from zero knowledge to productive contribution in the shortest time possible by prioritizing high-signal files and architectural patterns.

Phase 1: The First-Pass Strategy (High-Level Context)

Do not dive into source code immediately. Understand the box before looking inside.

1. Documentation & Manifests

Read these files first to understand what the project is, what it depends on, and how it is built.

• README.md, CONTRIBUTING.md, ARCHITECTURE.md
• Package manifests: package.json (Node), pom.xml (Java), Cargo.toml (Rust), go.mod (Go), Podfile / Package.swift (iOS), requirements.txt / pyproject.toml (Python).

Goal: Answer "What are the core dependencies?" (e.g., React, Express, CoreData, Django).

2. Directory Structure Analysis

Use directory listing tools to get a bird's-eye view. Look for standard conventions.

• src/, lib/, app/ -> Source code.
• tests/, spec/, __tests__/ -> Testing structure.
• config/, scripts/, docker/ -> Infrastructure.

Goal: Answer "How is the code organized?" (e.g., by feature, by layer/type, monolith vs. microservices).

Phase 2: Finding Entry Points

To trace execution, you must know where it begins.

• Web Apps: Look for index.js, main.ts, App.tsx, pages/_app.tsx (Next.js).
• Backend APIs: Look for server.js, main.go, manage.py, Program.cs, routes configurations.
• Mobile Apps: Look for AppDelegate.swift, @main struct App, MainActivity.java.
• CLIs: Look for bin/, cli.js, main.rs.

Phase 3: Identifying Architectural Patterns

Analyze the code organization to determine the architectural style. Look for:

1. MVC (Model-View-Controller): Are there directories explicitly named models, views, controllers?
2. Clean Architecture / Hexagonal: Are there layers for domain, usecases, infrastructure, adapters?
3. Feature-Based Modular: Is code grouped by domain concept? (e.g., src/features/authentication/, src/features/users/).
4. State Management: Look for Redux (store/, reducers/), Vuex, Context APIs, or core database abstraction layers (ORMs, DAOs).

Phase 4: Tracing Data Flow

Pick a single, core user journey (e.g., "User Login" or "Fetch Dashboard Data") and trace it vertically through the stack.

1. Trigger: Where is the API call made or the button clicked? (e.g., LoginButton.tsx)
2. Routing/Controller: Where is the request received? (e.g., auth.controller.ts)
3. Business Logic: Where is the data processed? (e.g., AuthService.ts)
4. Data Access: How is it saved/fetched? (e.g., UserRepository.ts, auth.sql)
5. Return: How does the state update and UI reflect the change?

Phase 5: Key Questions to Answer

Maintain a mental or physical checklist of these questions as you explore:

• What framework is driving the application?
• What is the primary database/persistence layer?
• How is authentication/authorization handled?
• Where are environment variables and configurations stored?
• How are errors handled and logged?
• Are there any heavily used custom abstractions or "magic" internal libraries?

Systematic Exploration Checklist

Use this checklist to ensure a thorough investigation:

• Read README.md and dependency manifests.
• Map out the top-level directory structure.
• Locate the main entry point of the application.
• Identify the routing mechanism (API routes or UI routes).
• Locate the database schema or data models.
• Identify the state management pattern (frontend) or service layer (backend).
• Find the testing suite and review a few core tests (tests often explain intended behavior better than code).
• Trace one complete CRUD operation from UI/Controller to Database and back.

Tooling Tips for the Agent

• Use grep_search extensively to search for specific strings like API_URL, login, CREATE TABLE.
• Use grep_search to find where specific functions are imported or called.
• Use view_file to read the exact implementation of core models or services.
• If overwhelmed, stop and write a brief summary artifact mapping out what you know so far.