codebase-onboarding

**Iron Law:** Read actual files before making any claims about the codebase. Never infer stack from directory names alone — read the config files. A wrong CLAUDE.md is worse than no CLAUDE.md. # Codebase Onboarding Skill Systematically maps an unfamiliar codebase in 4 phases, then generates two artifacts: a structured Onboarding Guide and a tailored CLAUDE.md. ## When to Use - Opening a new client project with Claude Code for the first time - Joining a new team repository - User asks "onboard me", "analyze this codebase", "generate a CLAUDE.md" - Updating an existing CLAUDE.md to reflect current project state ## Four-Phase Analysis Workflow ### Phase 1: Reconnaissance (read config files, not source) Gather signals without reading all source files. Run these in sequence: ```bash # 1. Package manifest detection ls pom.xml package.json pyproject.toml pubspec.yaml angular.json go.mod Cargo.toml Gemfile 2>/dev/null # 2. Framework fingerprinting — read the detected manifests cat pom.xml 2>/dev/null | grep -E "<artifactId>spring-boot|webflux|r2dbc" | head -5 cat package.json 2>/dev/null | grep -E "@nestjs/core|@angular/core|fastify|prisma" | head -5 cat pyproject.toml 2>/dev/null | grep -E "fastapi|langchain|langgraph" | head -5 cat pubspec.yaml 2>/dev/null | grep -E "^name:|flutter:|riverpod|go_router" | head -5 # 3. Entry point identification ls src/main/java 2>/dev/null || ls src/app 2>/dev/null || ls lib/main.dart 2>/dev/null || ls main.py 2>/dev/null # 4. Directory snapshot (top 2 levels, ignore noise) find . -maxdepth 2 -type d \ ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/build/*" \ ! -path "*/dist/*" ! -path "*/.dart_tool/*" ! -path "*/target/*" \ ! -path "*/__pycache__/*" ! -path "*/.gradle/*" 2>/dev/null | sort # 5. CI/CD and tooling detection ls .github/workflows/ Dockerfile docker-compose*.yml .env.example 2>/dev/null ``` **Stack fingerprint → skill mapping:** | Detected | Stack | Load Skill | |----------|-------|-----------| | `pom.xml` + `spring-boot` | Java 21 / Spring Boot 3.5.x WebFlux | `java-spring-api` | | `package.json` + `@nestjs/core` | NestJS 11.x / Fastify / Prisma | `nestjs-api` | | `pyproject.toml` + `fastapi` | Python 3.14 / FastAPI 0.135.2 | `python-dev` | | `pyproject.toml` + `langchain`/`langgraph` | Agentic AI / LangGraph | `agentic-ai-dev` | | `angular.json` | Angular 21.x / daisyUI | `angular-spa` | | `pubspec.yaml` + `flutter:` | Flutter 3.41.x / Dart 3.10.9 | `flutter-mobile` | ### Phase 2: Architecture Mapping After fingerprinting, read selectively: ```bash # For each detected stack, read key config files # Spring Boot cat src/main/resources/application.yml 2>/dev/null | head -40 find src/main/java -name "*Application.java" -o -name "*Router*.java" 2>/dev/null | head -5 # NestJS cat src/app.module.ts 2>/dev/null | head -40 find src -name "*.module.ts" 2>/dev/null | head -10 # Python/FastAPI cat main.py 2>/dev/null | head -40 find src -name "router*.py" -o -name "routes*.py" 2>/dev/null | head -5 # Flutter cat lib/main.dart 2>/dev/null | head -40 find lib -name "*.dart" -path "*/di/*" -o -path "*/config/*" 2>/dev/null | head -10 ``` Map these dimensions: - **Tech Stack** — Languages, frameworks, databases, build tools - **Architecture Pattern** — Monolith / microservices / monorepo; reactive vs imperative; API style - **Key Directories** — top-level folder to purpose mapping - **Data Flow** — trace a request: entry → validation → service → repository → database ### Phase 3: Convention Detection ```bash # Naming conventions — sample 5 files from each layer find src -name "*.java" | head -5 | xargs ls -1 2>/dev/null find src -name "*.ts" | head -10 | xargs ls -1 2>/dev/null find lib -name "*.dart" | head -10 | xargs ls -1 2>/dev/null # Error handling pattern — grep for try/catch patterns grep -r "catch\|@ExceptionHandler\|@ControllerAdvice\|GlobalExceptionHandler" src/ --include="*.java" -l 2>/dev/null | head -3 grep -r "catch\|ExceptionFilter\|@Catch" src/ --include="*.ts" -l 2>/dev/null | head -3 # Git conventions git log --oneline -10 2>/dev/null git branch -a 2>/dev/null | head -5 ``` ### Phase 4: Generate Artifacts Produce **both** outputs. Do not skip either. #### Artifact 1: Onboarding Guide Save to `docs/ONBOARDING.md` (create if missing, enhance if exists): ```markdown # {Project Name} — Onboarding Guide **Generated:** {ISO-8601 date} **Stack:** {detected stacks} ## Overview {1-2 sentences: what the project does and who uses it} ## Tech Stack | Layer | Technology | Version | |-------|-----------|---------| | {layer} | {tech} | {version} | ## Architecture {Architecture pattern: reactive/imperative, monolith/microservices} {Key architectural decisions detected from code} ## Directory Map | Path | Purpose | |------|---------| | `{path}` | {one-line purpose} | ## Request Lifecycle {Request flow: entry → validation → business logic → data access — traced from actual code} ## Conventions Detected - **Naming:** {file naming pattern observed} - **Error handling:** {pattern observed — @ControllerAdvice / ExceptionFilter / etc.} - **Testing:** {test framework and patterns found} - **Git:** {branch naming, commit style observed} ## Common Tasks ```bash # Build {actual build command} # Test {actual test command} # Run locally {actual run command} ``` ## Skills to Load {list skills from fingerprint table above} ``` #### Artifact 2: CLAUDE.md (create or enhance) If `CLAUDE.md` exists: **enhance, do not replace**. Add detected sections while preserving existing content. If missing: create at project root. Target: under 100 lines. ```markdown # {Project Name} ## Tech Stack {detected stack versions} ## Build & Run ```bash {commands from package manager} ``` ## Code Conventions - {naming pattern detected} - {error handling pattern} - {test framework} ## Key Entry Points - `{file}:{line}` — {description} ## Skills {stack-appropriate skills from this workspace} ``` ## Anti-Patterns - **Don't read every source file** — use Glob/Grep for reconnaissance; read selectively only when signals are ambiguous - **Don't infer from directory names** — a folder called `auth/` might contain Firebase logic, not custom auth. Read the files. - **Don't replace existing CLAUDE.md** — enhance and preserve existing guidance - **Don't guess version numbers** — read `pom.xml`, `package.json`, `pubspec.yaml` for exact versions - **Don't generate CLAUDE.md over 100 lines** — scannable in 2 minutes is the goal ## Error Handling If a manifest file is detected but unreadable: ``` BLOCKED: Cannot read {file} — permission denied or binary format. Proceeding without {stack} stack analysis. ``` If no manifest files found at project root: ``` No standard manifest detected at project root. Searching subdirectories... [run find . -name "pom.xml" -o -name "package.json" -maxdepth 3] If still none found: "This may not be a standard project root. Please cd to the correct directory." ``` ## Verify Step After generating both artifacts: ```bash # Confirm files exist and are non-empty wc -l docs/ONBOARDING.md CLAUDE.md 2>/dev/null ``` Report: "Generated: docs/ONBOARDING.md ({N} lines), CLAUDE.md ({N} lines)"