Codebase Onboarding

Systematically analyze an unfamiliar codebase and produce a structured onboarding guide. Designed for developers joining a new project or setting up Claude Code in an existing repo for the first time.

When to Use

• First time opening a project with Claude Code

• Joining a new team or repository

• User asks "help me understand this codebase"

• User asks to generate a CLAUDE.md for a project

• User says "onboard me" or "walk me through this repo"

How It Works

Phase 1: Reconnaissance

Gather raw signals about the project without reading every file. Run these checks in parallel:

1. Package manifest detection

   → package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,

     Gemfile, composer.json, mix.exs, pubspec.yaml

2. Framework fingerprinting

   → next.config.*, nuxt.config.*, angular.json, vite.config.*,

     django settings, flask app factory, fastapi main, rails config

3. Entry point identification

   → main.*, index.*, app.*, server.*, cmd/, src/main/

4. Directory structure snapshot

   → Top 2 levels of the directory tree, ignoring node_modules, vendor,

     .git, dist, build, __pycache__, .next

5. Config and tooling detection

   → .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,

     docker-compose*, .github/workflows/, .env.example, CI configs

6. Test structure detection

   → tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,

     pytest.ini, jest.config.*, vitest.config.*

Phase 2: Architecture Mapping

From the reconnaissance data, identify:

Tech Stack

• Language(s) and version constraints

• Framework(s) and major libraries

• Database(s) and ORMs

• Build tools and bundlers

• CI/CD platform

Architecture Pattern

• Monolith, monorepo, microservices, or serverless

• Frontend/backend split or full-stack

• API style: REST, GraphQL, gRPC, tRPC

Key Directories

Map the top-level directories to their purpose:

src/components/  → React UI components

src/api/         → API route handlers

src/lib/         → Shared utilities

src/db/          → Database models and migrations

tests/           → Test suites

scripts/         → Build and deployment scripts

Data Flow

Trace one request from entry to response:

• Where does a request enter? (router, handler, controller)

• How is it validated? (middleware, schemas, guards)

• Where is business logic? (services, models, use cases)

• How does it reach the database? (ORM, raw queries, repositories)

Phase 3: Convention Detection

Identify patterns the codebase already follows:

Naming Conventions

• File naming: kebab-case, camelCase, PascalCase, snake_case

• Component/class naming patterns

• Test file naming: *.test.ts, *.spec.ts, *_test.go

Code Patterns

• Error handling style: try/catch, Result types, error codes

• Dependency injection or direct imports

• State management approach

• Async patterns: callbacks, promises, async/await, channels

Git Conventions

• Branch naming from recent branches

• Commit message style from recent commits

• PR workflow (squash, merge, rebase)

• If the repo has no commits yet or only a shallow history (e.g. git clone --depth 1), skip this section and note "Git history unavailable or too shallow to detect conventions"

Phase 4: Generate Onboarding Artifacts

Produce two outputs:

#### Output 1: Onboarding Guide

# Onboarding Guide: [Project Name]

## Overview

[2-3 sentences: what this project does and who it serves]

## Tech Stack

<!-- Example for a Next.js project — replace with detected stack -->

| Layer | Technology | Version |

|-------|-----------|---------|

| Language | TypeScript | 5.x |

| Framework | Next.js | 14.x |

| Database | PostgreSQL | 16 |

| ORM | Prisma | 5.x |

| Testing | Jest + Playwright | - |

## Architecture

[Diagram or description of how components connect]

## Key Entry Points

<!-- Example for a Next.js project — replace with detected paths -->

- **API routes**: `src/app/api/` — Next.js route handlers

- **UI pages**: `src/app/(dashboard)/` — authenticated pages

- **Database**: `prisma/schema.prisma` — data model source of truth

- **Config**: `next.config.ts` — build and runtime config

## Directory Map

[Top-level directory → purpose mapping]

## Request Lifecycle

[Trace one API request from entry to response]

## Conventions

- [File naming pattern]

- [Error handling approach]

- [Testing patterns]

- [Git workflow]

## Common Tasks

<!-- Example for a Node.js project — replace with detected commands -->

- **Run dev server**: `npm run dev`

- **Run tests**: `npm test`

- **Run linter**: `npm run lint`

- **Database migrations**: `npx prisma migrate dev`

- **Build for production**: `npm run build`

## Where to Look

<!-- Example for a Next.js project — replace with detected paths -->

| I want to... | Look at... |

|--------------|-----------|

| Add an API endpoint | `src/app/api/` |

| Add a UI page | `src/app/(dashboard)/` |

| Add a database table | `prisma/schema.prisma` |

| Add a test | `tests/` matching the source path |

| Change build config | `next.config.ts` |

#### Output 2: Starter CLAUDE.md

Generate or update a project-specific CLAUDE.md based on detected conventions. If CLAUDE.md already exists, read it first and enhance it — preserve existing project-specific instructions and clearly call out what was added or changed.

# Project Instructions

## Tech Stack

[Detected stack summary]

## Code Style

- [Detected naming conventions]

- [Detected patterns to follow]

## Testing

- Run tests: `[detected test command]`

- Test pattern: [detected test file convention]

- Coverage: [if configured, the coverage command]

## Build & Run

- Dev: `[detected dev command]`

- Build: `[detected build command]`

- Lint: `[detected lint command]`

## Project Structure

[Key directory → purpose map]

## Conventions

- [Commit style if detectable]

- [PR workflow if detectable]

- [Error handling patterns]

Best Practices

• Don't read everything — reconnaissance should use Glob and Grep, not Read on every file. Read selectively only for ambiguous signals.

• Verify, don't guess — if a framework is detected from config but the actual code uses something different, trust the code.

• Respect existing CLAUDE.md — if one already exists, enhance it rather than replacing it. Call out what's new vs existing.

• Stay concise — the onboarding guide should be scannable in 2 minutes. Details belong in the code, not the guide.

• Flag unknowns — if a convention can't be confidently detected, say so rather than guessing. "Could not determine test runner" is better than a wrong answer.

Anti-Patterns to Avoid

• Generating a CLAUDE.md that's longer than 100 lines — keep it focused

• Listing every dependency — highlight only the ones that shape how you write code

• Describing obvious directory names — src/ doesn't need an explanation

• Copying the README — the onboarding guide adds structural insight the README lacks

Examples

Example 1: First time in a new repo

User: "Onboard me to this codebase"

Action: Run full 4-phase workflow → produce Onboarding Guide + Starter CLAUDE.md

Output: Onboarding Guide printed directly to the conversation, plus a CLAUDE.md written to the project root

Example 2: Generate CLAUDE.md for existing project

User: "Generate a CLAUDE.md for this project"

Action: Run Phases 1-3, skip Onboarding Guide, produce only CLAUDE.md

Output: Project-specific CLAUDE.md with detected conventions

Example 3: Enhance existing CLAUDE.md

User: "Update the CLAUDE.md with current project conventions"

Action: Read existing CLAUDE.md, run Phases 1-3, merge new findings

Output: Updated CLAUDE.md with additions clearly marked