codebase-onboarding · git:20260314.a3b7738 · 2026-03-14 · sha256 c1725c6f8e8320dd

codebase-onboarding git:20260314.a3b7738A

Immutable. This exact content never changes and is served at /api/v1/blob/c1725c6f8e8320dd.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_ofisoz2ltnsvlx56/c1725c6f8e8320ddb9a5b42b0e0855f6e399223ce74a0c090708c344e323c5c2.json

Then /plugin install codebase-onboarding@markdownregistry-ofisoz2ltnsvlx56 in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: codebase-onboarding
description: >-
  Guides the agent in rapidly understanding an unfamiliar codebase — its structure,
  conventions, dependencies, and key patterns. Use this skill when working in a new
  repository for the first time, when the agent needs to understand how a project is
  organized before making changes, when onboarding to a codebase with no documentation,
  or when the user says "look at this repo" or "understand this project."
---

# Codebase Onboarding

Understand the codebase before you change it. A 10-minute investigation prevents a 2-hour mess.

## When to Use

- Working in a new or unfamiliar repository
- Before making changes to code you haven't read
- When a project lacks documentation
- User asks you to understand a project or repo
- When subagents need context about the codebase

## How to Use

### Step 1: Survey the Landscape

Get the big picture in 60 seconds:

```bash
# Project structure (top 2 levels)
find . -maxdepth 2 -type f | head -50
# or: tree -L 2

# What language/framework?
cat package.json 2>/dev/null    # Node.js
cat requirements.txt 2>/dev/null # Python
cat go.mod 2>/dev/null          # Go
cat pom.xml 2>/dev/null         # Java
cat *.csproj 2>/dev/null        # .NET

# README — the author's intent
cat README.md | head -100
```

### Step 2: Identify the Architecture

Look for these patterns:

| Signal | What It Tells You |
|--------|-------------------|
| `src/controllers/` or `src/routes/` | MVC or route-based architecture |
| `src/features/` or `src/modules/` | Feature-based / domain-driven |
| `packages/` or `apps/` | Monorepo |
| `src/components/` | Component-based frontend |
| `cmd/` and `internal/` | Go standard layout |
| `src/main/java/` | Java/Spring project |
| `Dockerfile` + `docker-compose.yml` | Containerized services |

### Step 3: Understand the Build and Run

Find the entry points:

```bash
# How to install
cat Makefile 2>/dev/null
cat package.json | grep -A5 '"scripts"' 2>/dev/null

# How to run
grep -r "main\|entry" package.json tsconfig.json webpack.config.* 2>/dev/null

# How to test
grep -r "test\|spec" package.json Makefile 2>/dev/null
```

### Step 4: Read the Key Files

Priority reading order:
1. **Config files** — `.env.example`, config/, settings — understand the knobs
2. **Entry point** — `main.ts`, `app.py`, `cmd/main.go` — follow the startup path
3. **Routes/API** — How the outside world interacts with the system
4. **Models/Types** — The data structures that drive the domain
5. **Tests** — Tests tell you what the code is *supposed* to do

### Step 5: Map the Conventions

Before making changes, note:
- **Naming conventions** — camelCase? snake_case? How are files named?
- **Error handling pattern** — Exceptions? Result types? Error codes?
- **Testing pattern** — Co-located? Separate `__tests__/` directory? What framework?
- **Import style** — Absolute? Relative? Path aliases?
- **State management** — Where does state live? How is it shared?

### Step 6: Document for Future You

If the project lacks a CONTRIBUTING.md or architecture doc, create a brief mental model:

```markdown
## Quick Map

- **Language**: TypeScript (strict mode)
- **Framework**: Next.js 14 (App Router)
- **Testing**: Vitest, co-located test files
- **Key patterns**: Server Components default, Server Actions for mutations
- **Entry point**: src/app/layout.tsx
- **API layer**: src/app/api/
- **Data models**: src/lib/models/
- **Build**: `npm run build`, Deploy: Vercel
```

## Examples

**Bad — Blind Editing:**
> User: "Add a new API endpoint to this project"
> Agent: *Creates a file in the wrong directory, wrong naming convention, wrong framework patterns*

**Good — Onboard First:**
> User: "Add a new API endpoint to this project"
> Agent: "Let me understand the project first. This is a FastAPI app with routes in `src/api/routes/`, models in `src/models/`, and a consistent pattern of Pydantic schemas for request/response. Tests are co-located. I'll follow the existing pattern in `src/api/routes/users.py` as a template for the new endpoint."

## Guidelines

- Reading code is faster than guessing and rewriting
- Match existing patterns even if you'd do it differently
- When uncertain, look at 3 similar examples in the codebase before writing code
- Use subagents for parallel codebase exploration when the project is large

## Anti-Patterns

- **Assuming project structure** — Not all Python projects use Django patterns
- **Ignoring conventions** — Introducing camelCase into a snake_case codebase
- **Skipping the README** — Authors usually explain the important things
- **Reading every file** — Survey strategically, don't read the entire codebase linearly
- **Asking the user what you could discover yourself** — "What framework is this?" when `package.json` is right there