Ramping onto an unfamiliar codebase is weeks of asking interrupting questions and reading files in the wrong order.
Tier: Core · Workflow area: Documentation
An agentic assistant can walk the repo and produce what almost no team maintains by hand: a curriculum — entry points, the three flows that matter, the gotchas, and a reading order — verified by you before a newcomer sees it. For services companies this is a billable-week compression tool: the difference between an engineer productive in week one versus week three of a client engagement.
Skip for repos small enough to read in an afternoon, and do not substitute the tour for reading code — it is the map, not the territory.
Commission the survey, not prose. First pass is structural:
Explore this repo and produce a survey (facts only, no tutorial yet):
1. Deployables and entry points (main/handlers/cron/consumers) with paths.
2. The dependency direction between top-level packages — what imports what.
3. The 3 most-modified areas over the last 6 months (git log) — that is
where the newcomer will actually work.
4. Config surface: how env/secrets/feature flags enter the system.
5. Test layout and how to run the fast suite vs the full one.
Cite file paths for every claim. List anything you could not determine.
Pick the flows yourself. From the survey, choose the 2–3 end-to-end flows a newcomer must internalize (e.g. "order placement: API → validation → payment call → event → ledger consumer"). This selection is judgment the agent should not make alone — it will pick the architecturally interesting flows, not the ones the team touches daily (step 1's git-log ranking is your tiebreaker).
Generate the traced walkthroughs. Per flow:
Trace order placement end-to-end. Produce a walkthrough that:
- Lists each hop as: file:function → what it does in one sentence → what it
calls next, with exact paths and line-anchored links.
- Flags the 3 places a newcomer would get lost (indirection, DI magic,
naming that lies) and explains each in two sentences.
- Notes where behavior differs between local dev and production (stubs,
feature flags, sandbox payment mode).
- Ends with one safe exercise: a small change + the test that proves it.
Verify by walking it. Open every cited file; follow one flow yourself hop-by-hop. Agents most often err on: dead code presented as live, the old implementation of a recently refactored path, and confident descriptions of config precedence. Fix or annotate; the tour inherits your credibility.
Add the gotcha layer from humans. Ask the team for their top five "wish I'd known" items (the migration that half-finished, the module named utils that is load-bearing, the test that needs Docker). Have the AI weave them in — this folklore is the highest-value content and exists nowhere in the code.
Package as a path with checkpoints. Final structure: Day 1 (setup + system map), Day 2–3 (flow walkthroughs + safe exercises), Day 4–5 (first real ticket from the most-modified area). Commit to docs/onboarding/, and date-stamp it. Each new joiner's confusion notes become next month's revision — assign the newcomer the closing task of fixing what the tour got wrong.
The agent supplies coverage and patience; you supply flow selection and verification; the team supplies folklore. A tour missing any of the three either misleads, bores, or omits exactly what hurts.
Client codebases are the canonical restricted case. Run the agent only inside the sanctioned boundary: Copilot Business with the client's GitHub Enterprise, or Claude via Bedrock/Azure inside the client tenancy. No sanctioned agent at all? Two-layer fallback: (a) generate the survey mechanically with local tooling — tree, git log --stat, dependency-graph tools like pydeps/madge — and (b) feed those artifacts (structure, not source) to a local Ollama model to draft the tour skeleton, then trace flows by hand for the walkthrough layer. Slower, but the curriculum format and checkpoints still deliver most of the ramp-up compression.