Onboarding New Engineers to Large Underdocumented Legacy Codebases

A new hire reads every doc the team can point to, clones the repo, and is still blocked by lunch on day three. That is not a motivation problem or a reading-speed problem. The bottleneck is senior-engineer translation capacity, not the new hire's effort: someone has to explain why the auth module looks the way it does, why a migration will not run the same way twice, why a particular service exists in two implementations with no record of which one is current. The senior engineer appears in every scene of onboarding because they are the only repository of context that was never written down. Documentation does not remove that dependency, it just shifts it: when docs describe a workflow that was refactored months ago, a new hire burns hours debugging an issue that does not exist, then goes back to the same senior engineer to get corrected. Writing more documentation treats a symptom. The actual constraint is how much of a senior engineer's attention is available to translate institutional memory into something a new hire can act on, and that constraint does not loosen just because a wiki page gets updated.

What the productivity gap measures across the onboarding window

The interval between a new engineer's first day and their first independent, correct change looks like a measure of individual competence. It is really a measure of how much senior-engineer time was available to spend on them. Four figures make that visible. At hiring volumes of ten to fifteen engineers per quarter, the hours a senior engineer or platform lead spends hand-holding new hires add up to something close to a full-time equivalent, absorbed entirely by translation. None of these four numbers describes the new hire. They describe the system the new hire was dropped into, a distinction that makes the rest of this piece a question of infrastructure.

The five-stage structure a new engineer should follow in week one

Once the gap is understood as a structural one, the fix is a structure. Five sequential stages, each eliminating a specific category of blocking question, separate teams that compress ramp time from teams that do not. Stage 1 is access provisioning: SSO credentials, source control access, CI/CD visibility, cloud permissions, communication channels, and monitoring dashboards, all granted on day one rather than left sitting behind a ticket queue. Stage 4 is the first real task and first commit, a scoped, customer-affecting piece of work (not a training exercise) that goes through code review and merges to main, validating that environment, access, and workflow all function end to end, targeted for days one and two. Stage 5 is team and process integration: sprint ceremonies, release cadence, on-call rotation, and key collaborators, unfolding over weeks one and two until hand-holding is minimal.

Stage 3 is where most teams lose the time this structure is supposed to save. Codebase orientation defaults, in practice, to a senior engineer walking the new hire through the system by hand, which reintroduces the exact bottleneck the five-stage structure was built to eliminate. The stage that is supposed to run in two to four hours stretches into days because the only available map lives in one person's head. A well-maintained software catalog, or a code intelligence layer that serves the same function, replaces that walkthrough: service ownership, dependency maps, API docs, and runbooks all sit in one place that a new hire can query directly, without waiting for a human intermediary to become available.

Exploring an underdocumented codebase systematically before touching a line of code

Most legacy codebases do not have a software catalog, and plenty do not have an architect left on staff who remembers why a given service was built the way it was. A new engineer facing a cloned repo, no catalog, and no runbook needs a decision rule, not a menu of optional techniques, and that rule has three moves: isolate, map, then simulate. Component isolation means treating each bounded part of the system, a service, a pipeline, a module, as a self-contained unit to be understood fully before tracing how it connects outward. Dependency mapping comes next: tracing data and control flow between components visually, before changing anything, because undocumented dependencies are the single most common source of production surprises. Role simulation closes the loop: engaging with the system as an end-user or downstream consumer before editing it surfaces boundary conditions and edge cases that reading code alone will not reveal, things like high-load behavior, missing-data handling, or backward-compatibility constraints that look, on the surface, like redundant code.

Commit histories and issue trackers function as a substitute for documentation that was never written. The risk of skipping that step is concrete: removing what looks like dead or redundant code without checking its history can delete a compatibility shim that a legacy system still depends on, and the result is a production outage with no obvious cause, discovered only after the fact.

What AI Coding Agents Can and Cannot Do in a Large Legacy Codebase

AI coding agents are genuinely useful for navigation and explanation. Pointed at a repository, an agent can explain what a block of code does, trace every file that touches a given feature area, surface call chains and dependencies, and produce a first-draft explanation of an unfamiliar pattern faster than a human reading the same files cold. Legacy codebases expose a specific and well-documented weakness in that capability. Agents also get lost navigating complex pipelines that were never designed to be read start to finish by anyone, human or model.

The harder problem agents do not solve is understanding why the old system behaves the way it does, proving that a new implementation is behaviorally identical to the one it replaces, and owning the risk if it is not. Writing new code was never the hard part of legacy work. Reasoning about intent and behavioral equivalence is, and that reasoning still depends on context an agent only has if someone gives it to them. One falsifiable reading of that split is that gains are real on new code and shrink or reverse on mature codebases, which describes the legacy onboarding scenario precisely. An agent with access only to the files on a developer's laptop, or a narrow context window, cannot answer the questions that matter most in a large legacy system, because those questions require knowing how the whole system fits together, not just what one file contains.

Full codebase context as the precondition for useful agent output on legacy code

Whether an agent gets lost in a legacy pipeline or is actually useful is not a matter of which model is running underneath. It comes down to whether the agent has structured, indexed access to the entire codebase at the moment it is asked a question. When Meta pointed a swarm of agents at its legacy data pipelines, the agents lacked the structured context to navigate them, so engineers built a pre-compute engine: a swarm of more than 50 specialized agents that generated curated context files encoding tribal knowledge, giving every subsequent agent a coherent map of the system it was operating in. Context has to be built and indexed ahead of time, not reconstructed from scratch inside a chat window every time someone asks a question.

The Model Context Protocol, MCP, has become the mechanism that connects agents to live repositories, documentation, and internal APIs. Instead of pasting code into a chat window, an agent connects directly to the codebase, reads the relevant files, and answers against current source rather than a stale snapshot someone copied in an hour ago. Sourcebot is one concrete implementation of this pattern: it deploys inside an organization's own infrastructure through Docker, typically a multi-container setup running alongside Postgres and Redis, indexing every repository and exposing that context to both agents and human users through MCP-based connectors, so the full codebase becomes available to an agent without any source code leaving the organization's environment.

Querying the Codebase Without Interrupting Senior Engineers

New engineers are not the only people who need answers from the code. Product managers, compliance officers, data analysts, and support staff all need to know what the system actually does, and most of them cannot read source directly to find out. The default path today runs through a senior engineer: a PM who needs to know whether a given behavior lives in the code or the configuration asks a senior engineer, who then context-switches away from their own work to answer a question that an indexed, searchable repository could have answered directly. A natural-language interface backed by full repository indexing, rather than a narrow file context, lets that PM ask something like "where is the logic that determines which users see the new billing flow?" and get a file-level answer without any engineering time spent. This is not a convenience layer bolted onto the real work. Interrupt cost for the team, how often onboarding and stakeholder questions alike pull experienced engineers off their own work, is one of the four primary measures of onboarding cost named earlier, and it does not disappear once a new hire ramps up. It persists for as long as non-engineers have no direct way to query the system. Sourcebot's natural-language interface to repositories is built for exactly this constituency: engineers, PMs, support staff, and new hires alike can query across every repository in the organization without needing a senior engineer to mediate the question.

The self-hosting requirement that enterprise security teams will enforce before any of this deploys

None of the tooling described so far gets deployed at a company with sensitive source code unless the deployment model satisfies security review first. That review is not a procurement formality. Self-hosting inverts the risk: the tool runs inside the organization's own infrastructure, behind its own network controls, instead of depending on a vendor's data retention terms, and source code never crosses a vendor's boundary. MCP itself is not a security boundary. Research has found MCP servers exposed to the open internet with no authentication at all, and the protocol's adoption has outpaced the security tooling built around it. The deployment architecture of the MCP-connected tool, not the protocol, is the variable that determines risk. Regulated industries, the public sector, financial services, healthcare, have become the early adopters of self-hosted AI tooling precisely because their compliance obligations rule out cloud-hosted alternatives. Bring-your-own-model flexibility matters for the same reason: teams need to choose their own LLM provider and keep control over where code is sent at inference time, since locking into a vendor's hosted model quietly undoes the data-sovereignty guarantee that self-hosted indexing was supposed to provide.

The comprehension tradeoff: what faster navigation does not give a new engineer

Faster navigation carries a real risk, and it is not that the tooling fails to work. The empirical record on AI-assisted development already shows evidence of skill atrophy and code-quality degradation: faster output does not automatically produce engineers who understand what they built or who can debug it when conditions change. That is a real cost, and it does not go away just because time-to-first-commit looks better on a dashboard.

Redesigning what the remaining senior-engineer time is for is the answer. The structural gain from AI-assisted onboarding is that it frees senior-engineer time away from answering "where is X?" and redirects it toward "do you understand what you changed and why?", the higher-value form of mentorship the old model rarely had the bandwidth to deliver.

A repeatable onboarding infrastructure teams can build and maintain

These fixes need to be built as infrastructure that persists and can be reused for every new hire. A complete onboarding stack has four parts. Codebase intelligence provides dependency graphs, ownership data, hotspot analysis, and code search, the closest thing to a continuously updated map of the system as it actually exists today. Guided walkthroughs bind instructions to actual files and lines rather than README prose, so they stay accurate as the codebase changes under them. Documentation and runbooks are generated and maintained close to the code itself rather than in a separate wiki that drifts out of sync. Q&A and internal knowledge bases capture the searchable record of answers already given in Slack threads and code review, information that otherwise disappears the moment the conversation scrolls past.

This infrastructure's effectiveness is visible in the same four measures named earlier: time to first useful edit shortening, time to first independent decision shortening, interrupt cost for the team declining, and knowledge decay slowing as indexed search takes over from documents that go stale. Automated, self-service onboarding, where access provisioning and environment setup happen without a ticket or a wait on a senior engineer, can compress those first two stages from weeks to under a day, freeing the senior-engineer investment that remains for the comprehension work that actually matters. Sourcebot occupies the codebase intelligence layer in this stack: a single Docker container that indexes every repository, exposes search and navigation to engineers and non-engineers alike through a natural-language interface, and connects agents to the full codebase through MCP, all without requiring source code to leave the organization's own environment. A free tier that indexes real repositories lets an engineering team test that value against its own codebase before any procurement decision gets made, which removes the single biggest barrier to adopting a tool whose usefulness depends entirely on having indexed the whole repository first. Onboarding to a legacy codebase was never a problem that more documentation could solve on its own. It is a structural problem, and the fix is a structure built to last.