hi-donwi Codebase Onboarding
Overview
Learn the shape of the codebase before changing it.
When to use
- New repository, unfamiliar module, large refactor, or architecture question.
- You need to identify entry points, ownership boundaries, or risky files.
- A task requires understanding before implementation.
Process
- Map the repo quickly. List top-level directories, package manifests, build files, test config, and docs.
- Find entry points. App routes, server startup, CLI commands, workers, jobs, public APIs, schemas, and generated code boundaries.
- Use history when useful.
git log, churn, recent commits, and blame can reveal hotspots and bug-prone files. - Trace one real flow. Follow a representative request/user action from entry point to output/storage.
- Identify local conventions. Naming, error handling, dependency injection, testing style, state management, and folder ownership.
- Produce an onboarding map. Include architecture summary, key files, commands, risks, and recommended next reads.
Red flags
- Editing before identifying the owning module and tests.
- Treating generated/vendor/build output as source.
- Ignoring docs or scripts that define local commands.
- Summaries with no file references.
Verification
- The onboarding output names real files and commands.
- At least one representative flow was traced.
- Risks and unknowns are explicit.