stevefeldman/create-onboarding

Create Onboarding Guide

Generate a codebase-aware onboarding guide for new developers by analyzing the actual project, not from generic templates.

Instructions

1. Analyze the Repository

Before writing anything, read the codebase to extract real information:

• Read README.md, CLAUDE.md, CONTRIBUTING.md, and any existing docs.
• Examine the directory structure to understand project organization.
• Auto-detect the tech stack from configuration files (package.json, requirements.txt, Cargo.toml, go.mod, Gemfile, pom.xml, etc.).
• Identify build commands, test commands, and lint commands from config files and scripts.
• Check for containerization (Dockerfile, docker-compose.yml) or other environment setup.
• Review .env.example or similar files for required environment variables.

2. Document Environment Setup

Based on what you found in step 1, write concrete setup instructions:

• List required tools and versions (language runtime, package manager, database, etc.).
• Provide step-by-step installation and configuration commands.
• Document environment variables needed and where to get their values.
• Include a "verify your setup" section with commands to confirm everything works.
• Add troubleshooting tips for common setup issues found in the codebase.

3. Explain the Project Structure

• Describe what the project does and its business context (from README and code).
• Map the directory structure with explanations of what each top-level directory contains.
• Identify entry points (main files, route definitions, API handlers).
• Document key modules, their responsibilities, and how they interact.
• List the major dependencies and what each is used for.

4. Document Development Workflows

• Describe the branching strategy (examine existing branches and any documented conventions).
• Document how to run the project locally (dev server, watch mode, etc.).
• Explain the testing approach: how to run tests, what test framework is used, where tests live.
• Document the build and deployment process if visible from the repo.
• Describe code review and PR conventions.

5. Provide Key Code Patterns

• Show examples of the project's coding patterns (e.g., how a new API endpoint is added, how a new component is created).
• Document any custom abstractions, base classes, or utility functions new developers should know about.
• Point out configuration files and what they control.
• Note any non-obvious conventions or "gotchas" in the codebase.

6. Suggest First Tasks

• Identify good first issues or areas where a new developer can start contributing.
• Suggest small, self-contained changes that help learn the codebase (add a test, fix a linting issue, update docs).
• Recommend key files to read first to understand the system.

7. Create the FAQ

• Document common questions based on what might confuse a newcomer.
• Include answers to "how do I..." questions for common development tasks.
• Add links to relevant external documentation for the tech stack.

Output

Produce a single ONBOARDING.md file in the repository root containing all sections above. Use concrete commands, real file paths, and actual project details — not placeholders or generic advice.