---
name: codebase-onboarding
description: Study a new codebase and make a clear guide with its structure, key entry points, code rules, and a starter CLAUDE.md. Use when joining a project, explaining a repo, or setting up Claude Code for the first time.
origin: ECC
---

# Codebase Onboarding

## Credit

This skill was created by **ECC**. It is shared under a permissive open-source license. Keep this credit when you copy or change the skill.

## When to Use

Use this skill when:

- Claude Code opens a project for the first time.
- A user joins a new team or repo.
- A user asks, "Help me understand this codebase."
- A user asks for a project `CLAUDE.md`.
- A user says, "Onboard me" or "Explain this repo."

## Goal

Learn the project without reading every file. Find the main parts, show how they work together, and write a short guide that helps a new person begin.

Do not change project files unless the user asks. Do not run code that can post, deploy, delete data, or change live systems.

## Step 1: Check Existing Rules

Before reading the code:

1. Find `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, and `README` files.
2. Read the rules that apply to the current folder.
3. Check for nested rule files in key folders.
4. Follow project rules even if they differ from this skill.

If a good `CLAUDE.md` already exists, review it. Do not replace it without need. Suggest small fixes instead.

## Step 2: Scan the Project

Gather useful facts without opening every file. Run safe checks at the same time when possible.

### Find package files

Look for files such as:

- `package.json`
- `go.mod`
- `Cargo.toml`
- `pyproject.toml`
- `requirements.txt`
- `Gemfile`
- `pom.xml`
- `build.gradle`
- `composer.json`

Read lock files only when you need an exact tool or package version.

### Find tools and frameworks

Look for files such as:

- `next.config.*`
- `nuxt.config.*`
- `angular.json`
- `vite.config.*`
- `tsconfig.json`
- `Dockerfile`
- `docker-compose.*`
- `.eslintrc*`
- `eslint.config.*`
- `.prettierrc*`
- `Makefile`
- CI files under `.github/workflows/`

Do not name a framework from a file name alone. Check the package file or source code too.

### Find entry points

Look for common entry files:

- `main.*`
- `index.*`
- `app.*`
- `server.*`
- CLI command files
- Web route files
- Worker or job files
- Mobile app start files

A repo may have more than one entry point. List each one and say what starts it.

### View the folder shape

Show the top two folder levels first. Skip large or made files such as:

- `.git/`
- `node_modules/`
- `vendor/`
- build output
- cache folders
- coverage reports
- large data files

Open deeper folders only when they hold key code.

### Find tests

Look for:

- `tests/`
- `test/`
- `__tests__/`
- `*.test.*`
- `*.spec.*`
- test tool config files

Find how tests are run. Do not run slow tests unless the user asks or the cost is clear.

## Step 3: Map the Code

Find the main parts and how data moves between them.

For each main part, state:

- Its job
- Its folder
- What calls it
- What it calls
- What data it reads or writes

Trace at least one common path from start to end. For example:

```text
HTTP request -> route -> service -> database -> response
```

If the repo has more than one app, make a small map for each app. Then show any shared code.

Do not guess. Mark facts that are not clear as `Needs review`.

## Step 4: Find Project Rules

Read a few normal source files from each main area. Find rules for:

- File and folder names
- Function and class names
- Import paths
- Error handling
- Logs
- Settings and environment values
- Tests
- Comments and docs
- Code format

Separate written rules from patterns you only saw in code:

- `Stated rule`: Found in a rule or config file.
- `Seen pattern`: Found in several source files.
- `Needs review`: Seen once or not fully clear.

Do not copy secrets. List environment variable names only. Never show their values.

## Step 5: Handle Special Cases

- **Empty repo:** Say what is present and give a short setup list.
- **Very large repo:** Start with root files and active apps. Ask which app matters most if the scope is still too wide.
- **Many apps:** List each app, its start file, and shared parts.
- **Old code:** Note old and new patterns. Do not call one the main rule without proof.
- **Made code:** Mark generated files and do not use them to infer style.
- **Missing docs:** Say which facts came from code.
- **Broken setup:** Report the exact missing file, tool, or step. Do not hide the error.
- **Unknown language:** Use package files, start scripts, and folder names to guide the scan.
- **No tests:** State that no tests were found. Do not claim the project has no test plan.
- **Dirty worktree:** Do not remove or replace the user's changes.

## Output

Give the user these sections:

### Project Summary

Explain what the project does in three to six short lines.

### Project Map

Show the main folders and their jobs.

### Entry Points

List each app, server, CLI, worker, or job entry point. Include the command that starts it when known.

### Main Flow

Show one or more common paths through the code.

### Tools and Commands

List confirmed commands for setup, start, test, lint, format, and build. Say `Not found` when a command is unknown.

### Code Rules

List stated rules, seen patterns, and points that need review.

### Risks and Open Questions

List missing docs, unclear code paths, old parts, unsafe scripts, or setup gaps.

### Starter CLAUDE.md

Draft a short `CLAUDE.md` with:

- Project purpose
- Main folders
- Safe setup commands
- Test and check commands
- Code rules
- Files that should not be changed
- Known risks
- Any project-specific safety rules

Show the draft first. Write it to the repo only if the user asked for a file change.

## Example

User request:

```text
Onboard me to this repo and draft a CLAUDE.md.
```

Example result:

```markdown
## Project Summary

This is a small web app for tracking tasks. The browser app sends requests to a Node.js API. The API stores tasks in PostgreSQL.

## Project Map

- `src/web/`: Browser pages and UI parts
- `src/api/`: HTTP routes and request checks
- `src/services/`: Main task rules
- `src/db/`: Database access
- `tests/`: Unit and API tests

## Entry Points

- `src/server.ts`: Starts the API with `npm run dev`
- `src/web/main.tsx`: Starts the browser app
- `src/jobs/cleanup.ts`: Removes old task logs

## Main Flow

Create task request -> API route -> task service -> database -> JSON response

## Tools and Commands

- Install: `npm install`
- Start: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Code Rules

- Stated rule: Use TypeScript strict mode.
- Seen pattern: Service files end with `.service.ts`.
- Needs review: Some old routes return errors in a different shape.

## Risks and Open Questions

- The cleanup job has no test.
- The needed Node.js version is not written in the repo.
```

## Quality Check

Before you finish, confirm that:

- Each claim points to a file or clear code path.
- All key entry points are listed.
- Commands come from project files, not guesses.
- Generated and third-party files were skipped.
- No secret values were shown.
- Unknown facts are marked clearly.
- No project file was changed without the user's request.