Codebase Onboarding

Auto-Scan

!find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/__pycache__/*" -not -path "*/target/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" 2>/dev/null | wc -l

Project Files

!ls package.json requirements.txt pyproject.toml go.mod Cargo.toml *.csproj *.sln Gemfile composer.json mix.exs Makefile Dockerfile docker-compose* 2>/dev/null

Directory Structure

!tree -L 2 -I "node_modules|.git|vendor|__pycache__|target|dist|build|.next" 2>/dev/null || find . -type d -maxdepth 2 -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null

README

!cat README.md 2>/dev/null | head -50

Git Activity

!git log --oneline -20 2>/dev/null !git shortlog -sn --no-merges 2>/dev/null | head -10

Onboarding Guide Generation

Section 1: Project Overview

• What this project does (from README + code analysis)
• Who maintains it (from git history)
• How active it is (recent commits, contributors)

Section 2: Tech Stack

Detect and document:

• Language(s) and version(s)
• Framework(s)
• Database(s)
• Package manager
• Test framework
• Build tools
• CI/CD system

Section 3: Directory Map

Annotated directory tree:

src/
├── components/   # UI components
├── services/     # Business logic
├── utils/        # Shared utilities
├── types/        # Type definitions
└── config/       # Configuration

Section 4: Key Entry Points

• Application entry point (main file, index, app)
• API routes / endpoints
• Database schema / models
• Configuration files
• Environment variables needed

Section 5: How to Run

• Prerequisites (runtime versions, tools)
• Installation steps
• Development server command
• Test command
• Build command

Section 6: Architecture Patterns

• Code organization pattern (MVC, hexagonal, feature-based, etc.)
• State management approach
• Data flow (request lifecycle)
• Error handling strategy
• Authentication/authorization approach

Section 7: Where to Start

Based on the codebase analysis:

• "If you need to fix a bug, start here: ..."
• "If you need to add a feature, start here: ..."
• "If you need to understand the data model, look at: ..."

Section 8: Gotchas & Tribal Knowledge

• Non-obvious conventions found in the code
• Common pitfalls (from error handling patterns and comments)
• Areas with tech debt (complex, undocumented, or heavily modified files)

Rules

• Base everything on actual code — don't assume
• Flag areas that lack documentation
• Be honest about code quality and tech debt
• Include exact file paths for every reference