How to onboard engineers to a large codebase (and which tools help)

Key takeaways

Give a new engineer a map before code: which services exist, who owns them, and how a request moves through them. Reading files comes after that.
Questions about the code should go to a tool that can answer with file and line references, so a senior engineer is asked only when the code cannot answer.
Record the architecture walkthrough once and host it privately. The tenth new hire should not need a tenth live session.
The first task should touch real code in one service and end in a merged change by day four or five.
On a 1.5M-line repository, an agent with grep and file reads spent 2.80M tokens per question in our runs. Search over an index cut that to 767K. A newcomer's agent has the same problem as the newcomer.

To onboard an engineer to a large codebase, split the first week into three jobs: build a map of the system, learn to ask the code questions and get answers with sources, and ship one small change. Each job has its own tools. A service catalog gives the map, code search or a code-aware agent answers questions, and recorded walkthroughs carry the context that lives only in senior engineers' heads.

CodeAlive is our product, and the benchmark numbers below come from our own runs. Some tools mentioned here are made by companies we cross-mention with.

What should a new engineer do in the first week?

The first week should end with one merged change and a mental map of how the main services talk to each other. A plan we have seen work:

Day	Goal	What the engineer does	Done when
1	Environment and map	Clones the main repositories, runs the build and tests, watches the recorded architecture walkthrough	Tests pass locally and they can name the five services that matter most
2	Follow one request	Picks one user action and traces it from the API entry point to storage, asking the code questions along the way	They can draw the path with file names
3	Read the rules	Reads the instruction files (`AGENTS.md`, `CLAUDE.md`), the contribution guide and two recent merged pull requests in their area	They know how a change gets reviewed and released
4	First task	Takes a small, real ticket in one service: a bug with a reproduction or a missing test	A pull request is open
5	Ship and reflect	Addresses review comments, merges, and writes down what was hard to find	The change is merged and the list goes to whoever owns onboarding

The list from day five is the most useful artifact of the week. Every item on it is a gap in documentation, search or recordings that the next hire will hit too.

In what order should they read a large codebase?

Start from ownership and boundaries, then entry points, then one vertical slice. Reading a large repository top to bottom does not work: at 500K lines nobody gets through it, and most of it is irrelevant to the first task.

Service list and owners. Which repositories exist, what each one does, who to ask.
Entry points. HTTP handlers, queue consumers, scheduled jobs, CLI commands.
One request end to end. The same path the engineer traces on day two.
Tests for that path. Tests show the expected behaviour more directly than comments.
Instruction files and recent pull requests. These show the conventions in use today, which often differ from the wiki.

How should a newcomer ask questions about the code?

Ask the code first, with a tool that returns sources, and ask a person only when the answer is about intent or history. "Where is the retry policy for payment webhooks?" has an answer in the code. "Why did we pick this retry policy?" usually does not.

Many teams now hand newcomers a coding agent such as Claude Code, Cursor or Codex on day one. That works well inside one repository. On a large one, the agent's built-in search becomes the bottleneck. In our CodeAlive harness vs OpenCode runs on Sapling (about 1.5M lines), OpenCode with grep and file reads used 2.80M tokens and 297 seconds per question. Our research agent, working from an index, used 767K tokens and 104 seconds and scored 12.8 points higher on the same model.

Relationships matter too. In our GraphRAG for code runs, showing the call graph next to the code raised the share of relevant files found from 78.3 to 82.4 on the 1.5M-line repository, and changed little on a 513K-line one. So "who calls this?" questions benefit from a graph mainly in large codebases.

These are single internal runs on two repositories, not a published leaderboard. The direction is what matters for onboarding: the bigger the codebase, the more a newcomer's questions depend on search that does not read everything.

Which tools help with which onboarding step?

No single tool covers the whole week. This table maps steps to tool types and examples, in no ranking order.

Onboarding step	Tool type	Examples	Gives the newcomer
Map of services and owners	Service catalog	Backstage	Who owns what, where it lives
Questions about code across repositories	Code search and code context	Sourcegraph, CodeAlive	Answers and matches with file references
Context that lives in people's heads	Recorded walkthroughs, private video hosting	Kinescope	Architecture talks they can rewatch
Understanding a legacy system	Code understanding service	Swimm	A verified map of rules and flows
Daily work in one repository	Coding agent	Claude Code, Cursor, Codex	Edits, tests and local search

Backstage

Backstage is an open-source developer portal. Its Software Catalog tracks ownership and metadata for services, websites, libraries and data pipelines, built from metadata YAML files stored next to the code.

Good for: organisations with dozens or hundreds of services, where "who owns this?" is the first question.
Not a fit when: you have a handful of repositories and nobody to maintain the portal. It is a platform to run, not a hosted page.

Sourcegraph

Sourcegraph offers code search across repositories with exact, exhaustive results, plus Deep Search for natural-language questions. Its site says it handles large monorepos and multi-repo architectures.

Good for: exact matches across many repositories, and finding every usage before a change.
Not a fit when: a small team needs one or two repositories searched. Local grep and an IDE are enough there.

CodeAlive

CodeAlive indexes repositories into semantic search plus a relationship graph of files, symbols, calls, dependencies and tests, and serves it over MCP and API to Claude Code, Codex, Cursor and other agents. The index updates on every push. A newcomer can ask "where do we handle X?" without knowing the name, from their own agent. How precise the graph is against the compiler is in our indexer comparison.

Good for: large or multi-repo codebases where new engineers ask questions through a coding agent, including about repositories they have not cloned.
Not a fit when: the codebase is small enough that the agent's own search already finds everything, or when you need exact exhaustive matches for a refactor, where literal code search is the right tool.

Kinescope

Kinescope is a video hosting platform for business. For onboarding, the relevant part is keeping internal recordings private: its site lists access control, signed links, domain locks and DRM, plus AI subtitles and chapters. Chapters make an hour-long architecture walkthrough navigable by topic. There is a Free plan with up to 100 minutes of video and two workspace members, without DRM; paid plans start at €10 per month with usage-based pricing (pricing).

Good for: teams that record architecture talks, incident reviews and "how we deploy" sessions and want them private and searchable by chapter.
Not a fit when: your team does not record anything yet, or a few short clips in your existing wiki are enough.

Swimm

Swimm today positions itself around legacy modernization. Its System Intelligence service maps business rules, flows and dependencies from the code, checked by domain experts, and its AI Operability service prepares a codebase for coding agents.

Good for: organisations onboarding engineers to a legacy system whose rules are buried in the code.
Not a fit when: you want a self-serve tool for a modern codebase. Swimm presents this as a service engagement.

Claude Code, Cursor and Codex

Claude Code reads the codebase, edits files and runs commands from the terminal, IDE, desktop app or browser. Cursor searches with Instant Grep, which builds its index locally, and can start an Explore subagent for broad searches. Codex is available as a CLI, an IDE extension and in the cloud.

Good for: the newcomer's daily work inside a repository that is checked out.
Not a fit when: the answer sits in a repository that is not on disk, or the repository is so large that searching it eats the context window. That is where an index over MCP helps, as described in context for Claude Code and Cursor.

What should the first task look like?

The first task should be small, real and inside one service: a bug with a reproduction, a missing test, or a log message that needs more context. It should not be a refactor across services or a "read the codebase" ticket with no output.

Pair the task with the day-two trace: if the engineer traced the checkout flow, give them a checkout bug. Ask them to open the pull request early so review starts before they have polished everything.

FAQ

How long should onboarding to a large codebase take?

A first merged change in week one is realistic with this plan. Feeling at home across a large multi-repo system takes longer and depends on the system; we do not have a number we would defend.

Should new engineers use AI coding agents in their first week?

Yes, for questions and small edits, with a rule that they read the code the agent points to. An agent that cites files teaches the layout; one that only produces patches does not.

Do we still need written documentation if we have code search?

Yes. Search answers "where" and "how". Decisions, trade-offs and history belong in written notes or recorded walkthroughs, because they are not in the code.

What should we record on video for onboarding?

An architecture overview, a walk through one request end to end, and how a change gets deployed. Re-record when the architecture changes.

Which tool should we set up first?

The one that matches the most common question in your day-five lists. If it is "who owns this?", start with a catalog. If it is "where is this implemented?", start with code search or an indexed MCP server for your agents.