Onboard

Codebase Onboarding Doc Generator

Generate a comprehensive ONBOARDING.md file that helps a new developer get productive in a codebase quickly. The doc should answer the questions a new team member would ask in their first week.

Process

1. Discover the codebase

Run these investigations in parallel to build a mental model:

Project identity:

• Read README.md, CLAUDE.md, package.json, Cargo.toml, pyproject.toml, go.mod, or equivalent to understand the project's purpose, language, and framework
• Check for monorepo indicators (workspaces, lerna.json, nx.json, turbo.json, pnpm-workspace.yaml)

Architecture:

• Map the top-level directory structure (ls -la and one level deep)
• Identify the entry points (e.g., main.ts, index.js, app.py, cmd/, src/main.rs)
• Look for architectural patterns: routes/, controllers/, services/, models/, hooks/, components/, etc.
• Check for infrastructure config: docker-compose.yml, Dockerfile, terraform/, k8s/, .github/workflows/

Setup and tooling:

• Find setup scripts: Makefile, justfile, scripts/, bin/setup
• Check dependency files: package-lock.json, yarn.lock, Pipfile.lock, poetry.lock, Gemfile.lock
• Look for environment config: .env.example, .env.template, .envrc
• Check for database migrations: migrations/, prisma/, alembic/, db/migrate/

Testing and CI:

• Find test directories and config: jest.config, pytest.ini, vitest.config, .github/workflows/
• Check for linting/formatting config: .eslintrc, .prettierrc, ruff.toml, rustfmt.toml

Gotcha indicators:

• Read .gitignore for clues about generated files and local config
• Check for CONTRIBUTING.md or docs/ directory
• Look for non-obvious dependencies: .tool-versions, .nvmrc, .python-version, rust-toolchain.toml
• Scan recent git history for patterns: git log --oneline -30

2. Identify key files

Select 10-20 files that a new developer should read first. Prioritize:

• Entry points and main application wiring
• Core domain models or types
• Key configuration files
• The most-changed files (they're often the most important): git log --format= --name-only -100 | sort | uniq -c | sort -rn | head -20
• README and contributing guides

3. Detect common gotchas

Look for things that trip up new developers:

• Required environment variables without defaults
• Non-obvious setup steps (database seeding, code generation, certificate setup)
• Unconventional project conventions (custom scripts, unusual directory structure)
• Version pinning requirements (Node version, Python version, etc.)
• Known issues in CI/CD that affect local development
• Files or directories that look important but are generated (and shouldn't be edited)

4. Write ONBOARDING.md

Save the file to the repository root. Use this structure:

# Onboarding: [Project Name]

## What is this?
[2-3 sentence description of what the project does and who uses it]

## Architecture Overview
[High-level description of the system architecture. Include a text diagram if the system has multiple components or services.]

### Directory Structure
[Annotated tree of the important top-level directories — skip node_modules, vendor, etc.]

### Key Patterns
[Architectural patterns used: MVC, hexagonal, event-driven, etc. How data flows through the system.]

## Key Files to Read First
[Ordered list of 10-20 files with a one-line description of why each matters. Group by theme if helpful.]

## Local Setup

### Prerequisites
[Required tools and versions]

### Getting Started
[Step-by-step setup instructions — clone, install, configure, run]

### Running Tests
[How to run the test suite, including any setup needed]

### Common Commands
[Table or list of frequently used commands: build, test, lint, deploy, etc.]

## Common Gotchas
[Numbered list of things that trip up new developers, with solutions]

## Useful Links
[Links to relevant docs, dashboards, design docs, Slack channels, etc. — only if discoverable from the repo]

Writing guidelines

• Write for someone who is a competent developer but knows nothing about this specific codebase
• Be concrete — use actual file paths, actual command names, actual environment variable names
• If you're uncertain about something (e.g., whether a setup step is still current), flag it with a "Verify:" note rather than guessing
• Keep the total doc under 300 lines — long onboarding docs don't get read
• Don't include information you can't verify from the codebase itself