AI Codebase Onboarding Documentation

Onboarding a new engineer onto a codebase usually goes one of two ways. Path one: a senior engineer schedules a series of one-on-one calls, walks the new hire through the architecture from memory, points at the dashboards, explains the deploy process, and answers questions for the first week. The new hire learns the system, the senior engineer loses ten hours of focus time, and most of what was said is in nobody's notes because both of them were on the call rather than typing. Path two: the new hire is pointed at the README and the wiki, neither of which has been updated for a year, and is left to reverse-engineer the system from the source code while occasionally interrupting teammates with questions. The new hire is productive in three to four weeks instead of one to two.

Both paths fail for a similar reason: the team does not have a single document that answers the questions a day-one engineer actually has. The questions are predictable: what does the system do, why does it exist, how do I run it locally, where does the code live, what are the load-bearing decisions, how do I deploy a change, who do I ask when stuck. A good onboarding document answers each of those concretely, in the order a new hire encounters them, with links to the supporting material. The document is written once, kept current as the system evolves, and replaces most of the verbal hand-off. The discipline is rare because writing the document well takes a focused day, and a focused day is exactly what the senior engineer who could write it does not have. The /atlas-onboard skill is built to compress that day into minutes.

Why onboarding docs rot, and what survives

Onboarding documentation rots faster than other documentation because it is written for an audience that no longer reads it once they have onboarded. The new hire who needed it in week one does not need it in week six, and they have no incentive to update it for the next person. The README that was current at launch ages every time the deploy process changes, every time a service is renamed, every time a tool is deprecated. The team notices the rot only when the next new hire spends a frustrating afternoon following instructions that no longer work.

The fix is documentation that is generated from the codebase rather than written from memory. A document that lists the services by reading the codebase will be current. A getting-started script that runs the project end-to-end will fail loudly when something is broken, which is the signal that the doc needs an update. The documentation that survives is the kind that has a tight feedback loop with the code itself. /atlas-onboard is built to generate that kind of documentation: derived from the actual repository, structured to match the questions a new hire asks, and easy to regenerate when the answer changes.

What good onboarding documentation contains

A good onboarding document has six sections. First, the elevator pitch: what the system does and why it exists, in two paragraphs that the new hire can repeat to their family at dinner. Second, the architecture map: a diagram of the components and the data flow, with labels that match the actual service names in the codebase. Third, the local development setup: the exact commands to run the project end-to-end, the dependencies to install, the environment variables to configure, the dummy data to load. Fourth, the codebase tour: where the API lives, where the data layer lives, where the frontend lives, where the tests live, where the infrastructure code lives. Fifth, the load-bearing decisions: a curated list of three to five ADRs the new hire should read first because the rest of the codebase only makes sense in light of them. Sixth, the operational shape: how deploys work, how alerts work, where the dashboards live, who to ask for what.

The order matters. A new hire reads the elevator pitch first to know what they are looking at, the architecture next to know how it is laid out, and the local development setup third because they want to run the project before they read more. The codebase tour comes after they have something running, the load-bearing decisions come once they have read enough code to have questions, and the operational shape comes last because they will not deploy in their first week. A document that mirrors that order is a document that gets read; one that does not gets skimmed.

How /atlas-onboard works

Step one: read the codebase

Before generating any documentation, /atlas-onboard reads the repository to identify the services, the data layer, the frontend, the testing setup, the infrastructure code, and the deploy configuration. It also reads the existing documentation (README, CONTRIBUTING, docs/) so it can build on what is already there rather than start from scratch. The reading produces the structured input to the document; what the document says is grounded in the actual repository, not in the team's idealized version of it.

Step two: generate the elevator pitch and architecture map

The elevator pitch is drafted from the README, the package.json description, the project's marketing or product docs if accessible, and the actual functionality observable in the code. The skill asks the team to confirm or rewrite the pitch in plain language because this is the section where the team's voice matters most. The architecture map is generated as a Mermaid diagram from the service inventory, with the labels matching the names the codebase uses. The diagram is regenerable; if a new service is added, rerunning the skill produces an updated diagram.

Step three: produce the runnable getting-started

The local development section is the one the new hire is most going to test. The skill produces the exact commands to clone the repo, install dependencies, configure environment variables, load seed data, and start the application end-to-end. The commands are tested as part of generation: if any step fails, the failure is surfaced rather than silently included. The section ends with a verification step ("open localhost:3000 and you should see the dashboard") so the new hire knows whether they are set up correctly.

Step four: codebase tour, decisions, and operations

The codebase tour names the directories that matter and what they contain, calibrated to the project's actual layout. The load-bearing decisions section curates three to five ADRs (or the equivalent decision documents) that the team thinks every new hire should read first; if the project has no ADRs, the skill flags this and recommends running /atlas-adr on past decisions. The operational shape section covers deploys, alerts, dashboards, and the team contact information ("infrastructure questions: ask in #infra; payment-related questions: ask in #billing").

Tonone's /atlas-onboard skill generates day-one engineer documentation: elevator pitch, architecture map, runnable local setup, codebase tour, load-bearing decisions, and operational shape.

When to use /atlas-onboard, and when not to

/atlas-onboard is the right call when onboarding a new team member, when documentation is missing or outdated and is slowing new contributors down, or when handing off a project to a new team. The skill is also useful as a routine: regenerating the document quarterly catches drift before the next new hire encounters it.

Skip the skill for projects that are temporary or do not have a long-term team (a one-off migration script, a short-lived spike). For mapping the system architecture in detail, /atlas-map produces the C4 diagram. For capturing decisions that are missing as ADRs, /atlas-adr is the right call.

A worked example: onboarding doc for a billing service

Suppose the brief is: produce onboarding documentation for the billing service so new engineers can ramp up in days, not weeks. Run /atlas-onboard and the output is the structured document.

# Billing Service: Onboarding

## What this is
The billing service handles subscriptions, invoices, and payment
collection for the application. It exists because invoice and payment
state need strong consistency and ad-hoc reporting that the rest of
the stack does not provide.

## Architecture

```mermaid
flowchart LR
  CW[Customer dashboard] --> API[billing-api]
  ADMIN[Admin tool] --> API
  API --> DB[(billing-db)]
  API --> STRIPE[Stripe]
  STRIPE -- webhooks --> WH[webhook-handler]
  WH --> DB
  CRON[dunning-cron] --> DB
  CRON --> STRIPE
```

Three services share the database: billing-api, webhook-handler,
and dunning-cron. They run independently and coordinate via the DB.

## Local setup

```bash
git clone [email protected]:acme/billing.git
cd billing
cp .env.example .env
pnpm install
docker compose up -d postgres redis
pnpm db:migrate
pnpm db:seed
pnpm dev
```

Verify: open http://localhost:4000/health, you should see
`{"status":"ok"}`. Run `pnpm test` to confirm tests pass.

## Codebase tour
- `apps/api/`: billing-api routes (REST, OpenAPI spec in /docs/openapi)
- `apps/webhook/`: Stripe webhook ingestion (idempotent on event id)
- `apps/cron/`: dunning-cron, scheduled jobs
- `packages/db/`: Prisma schema and migrations
- `packages/contracts/`: shared types and Zod schemas
- `infra/terraform/`: AWS infrastructure as code

## Read these decisions first
1. ADR-0014: why we use Postgres (not DynamoDB) for billing
2. ADR-0021: idempotency strategy for webhooks
3. ADR-0028: dual-currency invoice format

## Operations
- Deploys: GitHub Actions, push to main triggers staging,
  manual approval promotes to production.
- Alerts: PagerDuty rotation, see #billing-oncall in Slack.
- Dashboards: Datadog 'billing-overview', Grafana 'rds-billing'.
- Who to ask:
  - Infra/Terraform: #platform
  - Stripe integration: #billing
  - Schema/migrations: #data
  - General: #billing

The document is one page, end-to-end runnable, and grounded in the actual repository. A new hire who reads it can clone, run, and start exploring the codebase in their first afternoon. The team contact section routes follow-up questions correctly. The decisions section gives them the reasoning that the codebase only makes sense in light of.

Related skills

/atlas-onboard produces the onboarding doc. For the architecture map referenced in it, /atlas-map produces the C4 diagram. For ADRs that the document references but do not yet exist, /atlas-adr is the right call.

Install

/atlas-onboard ships with the Atlas agent in the Tonone for Claude Code package. Install Tonone, invoke /atlas-onboard from any Claude Code session inside the project, and the skill produces a complete onboarding document derived from the actual codebase.

Onboarding done well saves a week per new engineer and several hours per senior engineer who would otherwise be doing knowledge transfer in calls. The skill is built so the doc is cheap enough to keep current, which is the only way it stays useful.