# Codebase Onboarding

> Build a concise mental model of an unfamiliar repository: architecture, entry points, workflows, ownership hotspots, tests, risks, and next files to read. Use when starting work in an unknown or large codebase, before major refactors, or when asked to explain how a project works. Do not use for tiny edits in already-understood code.

- Skill: `hi-donwi/codebase-onboarding` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hi-donwi/codebase-onboarding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hi-donwi/codebase-onboarding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: hi-donwi (https://skillmd.com/u/hi-donwi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hi-donwi/codebase-onboarding

---


# Codebase Onboarding

## Overview

Learn the shape of the codebase before changing it.

## When to use

- New repository, unfamiliar module, large refactor, or architecture question.
- You need to identify entry points, ownership boundaries, or risky files.
- A task requires understanding before implementation.

## Process

1. **Map the repo quickly.** List top-level directories, package manifests,
   build files, test config, and docs.
2. **Find entry points.** App routes, server startup, CLI commands, workers,
   jobs, public APIs, schemas, and generated code boundaries.
3. **Use history when useful.** `git log`, churn, recent commits, and blame can
   reveal hotspots and bug-prone files.
4. **Trace one real flow.** Follow a representative request/user action from
   entry point to output/storage.
5. **Identify local conventions.** Naming, error handling, dependency injection,
   testing style, state management, and folder ownership.
6. **Produce an onboarding map.** Include architecture summary, key files,
   commands, risks, and recommended next reads.

## Red flags

- Editing before identifying the owning module and tests.
- Treating generated/vendor/build output as source.
- Ignoring docs or scripts that define local commands.
- Summaries with no file references.

## Verification

- The onboarding output names real files and commands.
- At least one representative flow was traced.
- Risks and unknowns are explicit.