"This is easy!" Onboarding with the AI doing the heavy lifting
Part 2 of 5. The first afternoon in an unfamiliar system with an AI tool feels like understanding. Mostly, it isn't. Here's how to use the peak without paying for it later.
I started part 1 by opening Claude Code in a repository I'd never seen. Claude produced a readable explanation of the module within minutes. I read it, nodded, and felt oriented. By the end of that first session, I would have told you that I understood the system well enou gh to start.
That feeling has a place on the confidence curve often labeled "Dunning-Kruger," the one that shoots up to a Peak of Confidence, drops into a Valley of Realization, and climbs slowly back out. Day one in a new codebase is the peak, where confidence runs well ahead of understanding. The ease you feel has been measured in developers, and if you're not careful, it can fool you into believing you understand more than you do.
The ease is measured, and it is an illusion
That ease was first measured outside of software. In a 2002 study, Yale researchers Leonid Rozenblit and Frank Keil asked people how well they understood everyday mechanisms, like how a zipper works or how a toilet flushes. People rated their understanding high. Then they were asked to write out, step by step, how the thing worked, and their ratings dropped. Rozenblit and Keil named that drop the illusion of explanatory depth.
The same illusion shows up when developers work with AI. In METR's trial, experienced developers believed AI had made them 20% faster – but it actually made them 19% slower. In Anthropic's study, engineers learning a new library with AI scored 50% on a comprehension quiz, against 67% for those who worked without it. The engineers who delegated the code generation entirely to AI scored the worst. Struggling novice programmers studied by Prather and colleagues "finished with an illusion of competence."
None of these studies say that the tooling is bad, or that the fast explanation was wrong. Instead, they point out that the feeling of understanding from using AI is not evidence of understanding. That evidence comes from reading the code to verify the explanation. So, the first question to ask of any explanation is whether or not the explanation comes from the code at all.
Grounding is what makes the fast explanation usable
Anecdotal evidence and personal experience show that a model that isn't looking at your code will often explain it anyway, drawing on patterns from its training rather than the code in front of it. The explanation may sound right. It may even be right – for some other codebase. But without evidence pointing directly at the code in question, that explanation is not likely to be grounded in the right information.
Research on AI-guided codebase exploration points at the same limitation, noting that language models' "lack of grounding and integration with structured views limits their effectiveness." The defense is to keep every explanation anchored to real files and lines.
If the explanation names a file and a line, you can open it and check. If it doesn't, treat it as a lead, not an answer.
The most important discipline: reading the code
The most important discipline when at the Peak of Confidence is reading the code yourself: open the entry points named in the explanation and confirm they do what it claims. Places where the code and the model’s explanation disagree will likely become pitfalls later once you're working in the code.
You may not need to verify everything on day one. However, reviewing and verifying the parts you're about to rely on will help you build a sense of which pieces in the explanation may not be entirely accurate or may be missing important detail.
This verification is what builds real understanding, and it's the difference between the person who feels oriented and the person who is.
Pitfalls at the peak
The habits that cause trouble at the peak all come down to one mistake: treating the explanation as the understanding.
Handing off the reading. Delegating the typing to AI can be a deliberate choice. Delegating the reading what. Anthropic's study of engineers learning a new library warns about: engineers who handed off the most scored the worst. If you're skimming the explanation and moving on, you've delegated the reading.
Treating a confident explanation as a correct one. An explanation can sound confident whether or not it's right. That confidence is a property of the writing style, not of the explanation itself.
Skipping the write-down because it felt obvious. On day one everything feels obvious, but ask the model again in a fresh session and the explanation will likely come out different. Save the explanation, and correct it as you verify it. It's the seed of the document part 4 is about.
Use the AI heavily, and keep it anchored
None of this means holding back on leaning on AI at the peak. Heavy use on day one is likely the right call, as long as every explanation stays tied to the repository. Three habits keep it there. Give the model the shape of the project before asking it anything, so it isn't guessing from the average codebase. Point it at things you can name directly, like a file, a directory, a module, or a pull request, rather than asking about the system in general. Most importantly, ask for the why first: why the code exists and why it's built the way it is. This will orient you faster than a walkthrough of how it works.
When a target is too large to explain well in one pass, split it. Get one explanation of the area, then a narrower one for each piece that the ticket touches.
Tools for the peak
Han, an open-source set of Claude Code skills, has skills built for those habits.
- /project-discovery scans the repository's languages, frameworks, tooling and layout, and writes a short reference into CLAUDE.md or AGENTS.md that every later session starts from.
- /code-overview takes a file, directory, module, workflow or pull request, reads the real source, and writes an overview that leads with why. When the target is too big, it says what it skipped, so you can re-run it narrower.
- /ddd-analysis uses the principles of domain-driven-design to map the bounded contexts and domain language across the repository when the vocabulary is unfamiliar. It's discovery only, with no restructuring advice.
Outside Han, Claude Code's Explanatory output style adds short "Insights" about implementation choices and codebase patterns while the model does the coding for you. That's the right amount of help at the peak. But don't assume this is the right answer for every situation. As part 3 covers, using the wrong process, skills or other tools at the wrong time can lead you further down a bad path.
What the valley is going to feel like
Changing the code makes the explanation in hand less accurate. It got you oriented, but orientation isn't something you can make a change from. Finding that out is where the drop into the Valley of Realization begins. That drop isn't a sign that the tooling failed, though. Understanding code builds in layers, and the first layer is control flow: what calls what, in what order. A fast explanation gives you that layer. The data flow, the goals, and a full model of what the code is for have to be earned by working in the code.
Part 3 is about that work: using the AI as a mentor that explains the code, while you write the changes yourself.
River Lynn Bailey is a Senior Software Consultant at Test Double, and has extensive experience in AI coding tools and delivery, built on a career of delivering quality software solutions
