Codebase Onboarding

Systematically analyze unfamiliar codebases and produce structured onboarding guides.

When to Use

• First time opening a project
• 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"

Quick Start

1. Scan package manifests and config files (identify tech stack and framework)
2. Map directory structure and entry points (top 2 levels)
3. Trace one request lifecycle (entry → validation → business logic → database)
4. Identify naming, error handling, and testing patterns
5. Generate onboarding guide and starter CLAUDE.md

Key Concepts

• Reconnaissance — Use file presence patterns to infer tech stack and structure
• Architecture pattern — Identify monolith vs. monorepo, frontend/backend split, API style
• Convention detection — Extract naming, error handling, async patterns from recent code
• Guided exploration — Don't read everything; use grep/glob selectively for ambiguity
• Two-artifact output — Onboarding guide (structure + conventions) + CLAUDE.md (project instructions)

Common Usage

Most frequent patterns:

• Understanding project structure and data flow
• Documenting tech stack and architecture
• Creating starter instructions for new team members
• Identifying where to make changes (API routes, UI pages, database, tests)
• Mapping conventions (naming, error handling, git workflow)

References

• references/reconnaissance.md — File patterns for framework/language detection
• references/artifacts.md — Onboarding guide and CLAUDE.md templates, best practices, anti-patterns