Codebase Onboarding
Analyze any codebase and generate production-quality onboarding documentation tailored to the audience. Produces architecture overviews with system diagrams, annotated key file maps, step-by-step local setup guides, common developer task runbooks, debugging guides with real error solutions, and contribution guidelines. Supports Markdown, Notion, and Confluence output formats.
Core Capabilities
- Architecture analysis — tech stack identification from manifests/lockfiles, system boundary mapping, Mermaid data-flow diagrams, dependency graphs, module ownership.
- Key file annotation — surface the 20 most important files and why they matter; mark entry points, config hubs, shared utilities, and files dangerous to modify without coordination.
- Setup guide generation — prerequisites with exact versions,
git clone-to-tests steps, env-var docs, infra setup (Docker/DB/cache), and a verification checklist. - Task runbooks — add an API endpoint, run/write tests, create & apply migrations, deploy to staging/production, add a dependency safely.
- Debugging guide — common errors with exact messages and fixes, log locations by environment, diagnostic SQL/CLI queries, local reproduction of production issues.
- Audience-aware output — tailored additions for junior developers, senior engineers, and contractors; Markdown / Notion / Confluence formats.
Keywords: codebase onboarding, developer experience, documentation, architecture overview, setup guide, debugging guide, contribution guidelines, code walkthrough, new hire onboarding
When to Use
- Onboarding a new team member (junior, senior, or contractor)
- After a major refactor that made existing docs stale
- Before open-sourcing a project
- Creating a team wiki page for a service you own
- Self-documenting before a long vacation or team transition
- Preparing for a compliance audit that requires documentation
Clarify First
Before generating the docs, confirm these inputs. If any is unknown or vague, ASK — do not assume:
- Target codebase path — which project to analyze (the input all three scripts scan)
- Audience — junior developer, senior engineer, or contractor (tailors which sections appear and at what depth)
- Output format — Markdown, Notion, or Confluence (sets the generated document format)
Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
Tools
| Tool | Purpose | Command |
|---|---|---|
architecture_mapper.py | Analyze project structure and generate a high-level architecture map | python scripts/architecture_mapper.py /path/to/project --json |
onboarding_generator.py | Scan a project directory and generate an onboarding guide | python scripts/onboarding_generator.py /path/to/project --json |
setup_validator.py | Validate a project's development setup completeness | python scripts/setup_validator.py /path/to/project --json |
All tools accept an optional directory argument (default: current directory) and --json for machine-readable output.
References
Load the reference that matches the task — keep this file lean and pull detail on demand:
- references/fact-gathering-and-patterns.md — the Phase 1 fact-gathering shell commands and the Phase 2 architecture-pattern classification table. Read when analyzing a codebase before writing docs.
- references/documentation-templates.md — the architecture overview, key file map, local setup, and debugging guide templates plus audience-specific (junior/senior/contractor) additions. Read when generating the actual onboarding documents.
- references/quality-and-best-practices.md — quality verification checklist, common pitfalls, best practices, a troubleshooting matrix, and success criteria. Read before shipping onboarding docs.
Scope & Limitations
This skill covers:
- Generating architecture overviews, key file maps, setup guides, task runbooks, and debugging guides from codebase analysis
- Audience-aware documentation tailored for junior developers, senior engineers, and contractors
- Output in Markdown, Notion, and Confluence formats
- Quality verification checklists and freshness audit processes
This skill does NOT cover:
- Automated API reference generation from code annotations — see
engineering/changelog-generatorfor release-oriented docs orengineering/api-design-reviewerfor API quality - Continuous documentation pipelines or CI-triggered doc builds — see
engineering/ci-cd-pipeline-builderfor pipeline automation - Security-focused documentation such as threat models or access control matrices — see
engineering/skill-security-auditorfor security auditing - Runbook generation for incident response and production operations — see
engineering/runbook-generatorfor operational runbooks
Integration Points
| Skill | Integration | Data Flow |
|---|---|---|
engineering/runbook-generator | Onboarding task runbooks can seed operational runbooks for production incident response | Onboarding runbook templates → Runbook Generator for ops-grade expansion |
engineering/api-design-reviewer | API route analysis from Phase 1 feeds into API design quality reviews | Discovered API endpoints → API Design Reviewer for consistency checks |
engineering/database-schema-designer | Database schema files identified during key file mapping inform schema design reviews | Schema file paths and ORM type → Schema Designer for migration planning |
engineering/tech-debt-tracker | Technical debt items surfaced during architecture analysis should be logged for tracking | Architecture analysis findings → Tech Debt Tracker backlog entries |
engineering/ci-cd-pipeline-builder | CI/CD config discovered in Phase 1 can be validated and improved by the pipeline builder | CI config paths and workflow list → Pipeline Builder for optimization |
engineering/dependency-auditor | Dependency counts and lockfiles gathered in Phase 1 feed directly into security and license audits | Package manifests and lockfiles → Dependency Auditor for vulnerability scanning |
