# Learn Unfamiliar Codebase

> Bilinmeyen veya büyük kod tabanlarını hızlıca anlama, analiz etme ve gezinme yeteneği.

- Skill: `gktuoktay/learn-unfamiliar-codebase` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gktuoktay/learn-unfamiliar-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gktuoktay/learn-unfamiliar-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: GktuOktay (https://skillmd.com/u/gktuoktay)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gktuoktay/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.