Joining a new codebase used to mean two weeks of grep, a printed architecture diagram, and a patient senior developer. In 2026, the patient senior developer is partly an AI tool with a Tree-sitter parser and a knowledge graph. The methodology has not changed much: map the territory before you build in it. The tools have. This article walks through a six-phase onboarding loop and which AI tool earns its keep at each step.
TL;DR, a six-phase AI-assisted onboarding loop
When you join a new codebase, work through these phases in order before opening a pull request: map the repository, identify the tech stack, discover architectural patterns, trace one real user journey end to end, spot improvements without suggesting them yet, and document what you learned in your own words. Each phase has a different AI tool that earns its keep. Pick one tool per phase. Do not run six AI assistants in parallel. That is noise, not insight.
- Map the repository
- Identify the tech stack and versions
- Discover the architectural patterns
- Trace one real user journey end to end
- Spot improvements without suggesting them yet
- Document what you learned
Why onboarding still hurts, and where AI actually helps
The two failure modes of unaided onboarding are predictable. The first is getting lost in the folder structure, opening twenty files at random, and never building a coherent mental model. The second is chasing call sites manually through a deeply layered call stack, losing the thread halfway, and starting over. Both burn a week.
AI tools are genuinely good at a narrow set of things here. They recognise patterns across many files at once. They summarise a module's responsibility in a paragraph. They trace a dependency graph in seconds and tell you which functions are unused. None of that is magic. It is pattern recognition at scale, which is what these models are built for.
What they cannot do is judge architectural decisions, infer business intent from code alone, or replace a fifteen-minute conversation with the original author. The conversation is the fastest path to understanding why the code is shaped the way it is. The AI is the fastest path to understanding what it does. You need both.
Phase 1, map the repository before reading any code
Before you open a single source file, look at the shape of the project. Read the README, the package manifests, the lockfiles, and the top-level folder names. Note the build system, the test runner, the deploy target, and the entry points. The goal is a one-page mental model of the territory before any line-by-line reading begins.
This is where a knowledge-graph tool earns its keep. The output is a structural snapshot of the codebase that a human would take days to assemble.
Generating a knowledge graph with Understand-Anything
Understand-Anything is an open-source tool from Lum1104 that builds a code knowledge graph by combining Tree-sitter parsing with LLM annotation. Tree-sitter produces the deterministic structural edges (imports, function calls, inheritance), while the LLM layer adds semantic labels and grouped descriptions. The output is a navigable graph the team can commit, so the next person to join skips the analysis step entirely.
Understand-Anything ships as a plugin across Claude Code, Cursor, VS Code with Copilot, and Gemini CLI. The trade-off is indexing time. A large monorepo can take several minutes on the first run. After that, the graph updates incrementally on each commit, so the cost is paid once.
When the repo is public, try DeepWiki first
DeepWiki generates a browsable wiki and Q&A interface for any public GitHub repository, with no setup on your side. It is excellent for a first read. The caveat is staleness: the generated wiki lags behind the latest commits, so for fast-moving repositories, treat it as a starting point and verify anything load-bearing against the actual source.
Phase 2, identify the tech stack and its versions
A codebase is shaped by its dependencies, and dependencies are shaped by their versions. React 18 and React 19 are different libraries in practice. The same goes for Vue 2 and Vue 3, Express 4 and Express 5, and almost every framework with a recent major release. Read the manifests carefully. Note the unusual or legacy dependencies: a state-management library nobody picks in 2026, a router that has been deprecated for two years, an HTTP client that signals an older era of the codebase. Then run the build once. See what fails.
Why a repo-map matters more than a big context window
Aider's repo-map is the canonical example of compressing a codebase into a structural skeleton that fits in a context window. The repo-map is not the full source. It is the list of files, the symbols they export, and the relationships between them. A 100k-line codebase needs a map, not a recitation. Dumping the whole repository into a prompt is wasteful and unreliable: the model loses precision past a certain length and starts hallucinating relationships that do not exist.
Continue handles the in-editor version of the same idea, giving you "what is this library and how is it wired here" answers grounded in the actual import graph. Both tools share a limitation: they cannot validate API versions on their own, so cross-check anything version-specific against the lockfile before trusting the answer.
Phase 3, discover the architectural patterns in play
Once you know the stack, the next question is how the codebase organises itself. Is it feature-driven, layer-driven, hexagonal, MVC, or vertical slice? Where does the state management sit? How is the data layer wrapped? Where does authentication live, and how is it threaded through requests? These patterns determine whether your future contributions fit the grain of the project or fight it.
Single-repo pattern discovery is where Understand-Anything's graph view shines, because you can ask "show me every place a fetch wrapper is called" and watch where the pattern holds and where it breaks down. For organisations with many repositories, Sourcegraph Cody extends the same idea to a cross-repo code graph, which is useful inside a monorepo or across a fleet of services.
When the AI flags a pattern that does not match anything in your mental model, dig in. Some patterns are unfamiliar but sound, like render-function injection via context, and some are signs of a codebase that drifted over years of unrelated changes. AI tools surface the project's organisational shape, whether that is feature-driven folder layouts or a layered MVC, and they let you compare what you find against the canonical examples you already know.
When patterns conflict, find the most recent one
Long-lived codebases almost always show two or three competing patterns layered on top of each other. The data layer was wrapped one way in 2020 and again last quarter. AI tools surface every variation faithfully, which is what makes them useful and what makes them confusing. Newer code shows the team's current preference. Pick that as your canonical example and treat the older variants as legacy you should not extend.
Phase 4, trace one real user journey end to end
Pick a single feature: login, create-order, dashboard load, file upload. Follow it from the UI event through the state mutation, through the API call, through the server handler, through the database. Note the boundaries. Note the surprises. This phase is where AI earns its keep most clearly, because tracing a deep call stack across files by hand takes hours and produces an unreliable mental model.
Greptile is built for exactly this kind of full-codebase reasoning. Ask it "trace the signup flow from the login button to the database row, listing every file and line involved" and it will return an ordered list with citations. Aider does the same in a terminal session if you prefer that workflow. Both tools rely on indexing the whole codebase, so they pay an upfront cost in exchange for trustworthy traces.
When you spot @/components/... imports the file system does not obviously resolve, check the import-alias configuration before assuming the AI invented them. It probably did not.
The question format that actually works
Prompts that ask the AI to "explain this codebase" produce summaries. Prompts that ask it to enumerate files involved in a trace produce traces. Be specific. Name the entry point: "the click handler in LoginForm.tsx". Name the suspected exit point: "the row insert in the users table". Ask explicitly for files, line numbers, and the order of operations. The output you get back is then verifiable in the source, which is the only kind of output worth trusting at this stage.
Phase 5, spot the improvements, without suggesting them yet
By this point, you will have a list. Duplicated logic. Inconsistent error handling. Missing tests. Functions nothing calls. A configuration file that mixes secrets with feature flags. Resist the urge to open pull requests yet.
Greptile and similar AI code-review tools, along with Understand-Anything's orphan-node detection, will produce a long list of "improvements" worth flagging. Pair the AI's flags with judgment about which ones are worth raising and when. Keep the list private for now. Tag items as structural, stylistic, or broken. The three categories need different conversations later.
The ninety-day rule for architectural suggestions
The first ninety days are for understanding, not refactoring. AI tools will produce a list of suggestions that look obvious on paper. Most do not survive contact with the reasons the code looks the way it does. The unused function caught a regression nobody documented. The inconsistent error handling exists because two downstream services expect different shapes. Wait until you have the context. Then raise items one at a time, in the order they matter, in code review where the team can push back.
Phase 6, document what you learned, in your own words
Write the onboarding document you wished existed when you joined. Sketch the architecture diagram. List the conventions. Note the surprises. The act of writing forces understanding, which is why this phase exists and why you cannot skip it.
Understand-Anything's auto-generated documentation is a fine starting point, and so is DeepWiki's output for public projects. Both produce a structural draft you can edit. Edit it heavily. Replace the generic descriptions with the specific reasons you found, and the diagrams with the boundaries that actually matter for your team's workflow.
The test of understanding is explanation
If you cannot explain a subsystem to a new colleague without the AI's help, you have not learned it yet. The AI got you to the door of understanding. The walk through it is yours.
Tool tier comparison, knowledge graphs, context packers, and platform suites
The 2026 landscape of AI codebase tools falls into three tiers. Each has a different shape, a different cost, and a different sweet spot.
| Tier | Tools | Strengths | Weaknesses |
|---|---|---|---|
| Knowledge-graph engines | Understand-Anything, DeepWiki | Structural fidelity, symbol-level navigation, AST-grounded answers | Need indexing, slower to first answer, can stale |
| Context packers and pair-programmers | Aider, Continue, Claude Code | Conversational, in-editor, edit-aware, fast feedback loop | Context-window limited, lose precision at scale |
| Platform suites | Sourcegraph Cody, Greptile, GitHub Copilot Workspace | Org-wide graph, PR-aware, integrated review | Cost, vendor lock-in, sometimes opaque |
Knowledge-graph engines win when the question is structural: where is X used, what calls Y, what does this module own. Context packers win when the question is conversational: help me edit this, what does this function do, rewrite the test in this style. Platform suites win when the team needs the same answer across many repositories. Pick one tool per tier. Running all three at once gives you three half-believed answers instead of one solid one.
When AI gets it wrong, failure modes and how to catch them
AI tools fail in predictable ways. Five worth naming.
The first is hallucinated APIs from outdated training data. The model remembers an old function signature and writes against it. The fix is to cross-check every API claim against the actual installed version in the lockfile.
The second is confusing similarity for identity. Two functions named formatDate in different files do different things. AI summaries sometimes collapse them into one description, and you read the wrong one. Open both files. Confirm the bodies match the summary.
The third is inventing call relationships. This is worst in dynamic languages such as JavaScript and Python, where dispatch happens through string keys or runtime metaprogramming. The static graph misses these edges, and the LLM sometimes fills in plausible-looking ones that do not exist. Verify the call graph by grepping for the function name across the repository.
The fourth is missing dead code. The AI assumes that the code that exists is alive. It usually is not. Orphan-node detection in a knowledge-graph tool catches most of this, but the AI's prose summaries rarely flag dead branches.
The fifth is smoothing over genuinely weird code. The weird code is usually weird for a reason. AI explanations sometimes paper over it with a tidy description that hides the constraint. When something reads strangely in the explanation, open the source. The weirdness is the lesson.
Treat every AI summary as a hypothesis. Confirm in the source before you build on it.
My recommended stack for the first two weeks
If I am joining a new codebase tomorrow, the tooling sequence I reach for looks like this.
Days one and two, Understand-Anything for the structural map, or DeepWiki if the repository is public. The goal is one screenshot of the graph and a one-page summary of where the major modules live.
Days three through seven, Aider or Claude Code for conversational tracing. One terminal session per feature traced. Notes saved in a personal markdown file as I go.
Week two, Sourcegraph Cody if the project is part of a monorepo with more than two teams. Otherwise, stay with Aider, because the context-switching cost of adding another tool is real. The same goes for understanding the surrounding stack, where reading something like a state management library in play shortens the learning curve more than any AI summary will.
Ongoing, Greptile or a similar AI PR-review tool, paired with the habit of reading every pull request the team opens. The reviews teach you the team's taste faster than any document can.
The biggest mistake teams make is over-tooling. Pick one per tier and stick with it.
Conclusion
The methodology outlasts the tools. Tree-sitter parsing and LLM annotation are this year's stack. Next year it will be something different, and you will swap one tool for another inside the same six-phase loop. Map, identify, discover, trace, spot, document. The loop was true in 2010 and it will be true in 2030. AI tools are an accelerator, not a replacement for the patient act of reading code and asking why it is shaped the way it is.