Dig Before You Touch: A First-Week Protocol for Taking Over an Unfamiliar Codebase with AI

On October 22, 2026, a thread appeared on V2EX titled "Frontend dev wants to learn backend, but exhausted after reading this code." Among 114 replies, one sentiment kept surfacing: if you can't read it, just let AI write it. That sounds liberating — until you ask the harder question: if you can't read the code, on what basis do you trust the changes AI makes to it?

Vibe coding has pushed the speed of writing code to unprecedented heights. But it created a new scarcity in the process: the faster code gets written, the rarer the ability to read someone else's code becomes. Sooner or later you'll inherit an AI-generated legacy project, fork an open-source repo for a second life, or take over a codebase from a predecessor who left no notes. The method you use in your first week determines how much rework the next three months will cost you.

This guide is that method: treat AI as your excavation tool and spend five days truly taking over an unfamiliar codebase. The creed is one sentence — dig before you touch.

Scope note: what this guide is and isn't. This is a first-week methodology for onboarding onto an unfamiliar codebase — what to do, in what order, and what to deliver. Its deliverables are concrete: an architecture sketch, a sequence diagram of one core flow, a risk register, and a project context file. It does not teach line-by-line reading techniques (that's the territory of reading-ai-generated-code-guide), nor does it cover gradual refactoring of legacy code (that's legacy-code-gradual-refactor-agent). This guide is the work that comes before the change: if refactoring is surgery, this is the pre-op exam.

1. Why "What does this project do?" is the worst opening question

Most people's first move with a strange repo is to dump it into AI and ask: "What does this project do? Explain the architecture." AI will instantly return a fluent, well-structured answer full of correct-sounding terminology — and you'll base every subsequent decision on it. That's where the disaster starts.

The problem isn't that AI is dumb. It's that, with no evidence chain from the actual repository, it can only answer by guessing. And its guesses follow three fixed patterns — the three opening hallucinations:

Hallucination one: inventing architecture from directory names

It sees services/ and declares "this is a microservices architecture." It sees controllers/ and says "MVC." It finds a queue.ts inside utils/ and asserts "the project uses a message queue." Directory names are just names someone typed once — a folder called services/ might hold three unrelated helper functions while the real business logic lives in lib/. What AI learned from training data is the statistical correlation between directory names and architectures, not the facts of this repo.

Hallucination two: mistaking examples for the main logic

Many repos ship examples/, demo/, or playground/ directories, and READMEs with long "quick start" snippets. AI loves citing these because they're well-commented, cleanly named, and easy to read. But example code is a carefully simplified toy — the production path may differ by three middleware layers, two permission checks, and a feature flag. Understanding a project from its examples is like understanding a building's load-bearing structure from its showroom.

Hallucination three: conclusions you can't verify

The most dangerous one. AI will say "the project uses an event-driven architecture, decoupled via Redis Streams" — extremely professional-sounding. Follow its directions and you may discover there is no Redis at all, and the supposed "events" are just ordinary function calls with emit in their names. A fluent conclusion is not a verifiable conclusion, and an unverifiable conclusion is worse than no conclusion, because it sends you walking confidently with the wrong map.

Hence the first iron rule: never ask AI "what does this project do." Ask it "what evidence in this project shows what it does." Swap "give me conclusions" for "give me a map," and the whole excavation gets on the right track.

2. Step one: get a map, not conclusions

Archaeology always starts with surveying, never with interpreting. Same with a codebase: day one's goal isn't understanding, it's a map with evidence — every claim followed by a file path and line number, and any claim without evidence explicitly marked as unfounded.

The evidence-demanding prompt template

Copy this template verbatim as your first conversation with AI. Three design decisions matter: it forces evidence (path:line) behind every claim; it permits AI to say "not found" — which is far more valuable than fabrication; and it separates facts from guesses.

You are a code archaeologist. Survey this repository for me. Rules:

1. Every claim must be followed by evidence in the form "file path:line number".
2. Claims without evidence must be explicitly marked "GUESS:" and explain
   why you guessed that.
3. Do NOT cite example code in examples/, demo/, or docs/ as evidence
   for production logic.
4. End with a table: Module | Responsibility (one sentence) | Evidence |
   Confidence (high/medium/low).

Answer in order:
a. Where is the entry point? (scripts in package.json, main entry,
   the framework's route registration file)
b. Where does data come from and go to? (DB connections, external API
   calls, service addresses in environment variables)
c. What are the top-level modules, and what does each do?
d. What do you GUESS exists but can't find evidence for? (e.g. looks
   like it uses a queue but no config found)

Pay attention to item (d): making AI proactively list "guessed but unevidenced" items. That list is often more valuable than the map itself — it tells you where the repo's "looks-like-but-might-be-a-trap" spots are.

Acceptance criteria for the map

When AI hands the map back, don't trust it yet. Spend 30 minutes on three checks:

• Spot-check three pieces of evidence. Pick three random "high confidence" claims and open the cited files to the exact lines yourself. If one of the three doesn't hold, downgrade the whole map's confidence by a level.
• Find the entry point and run it. Start the project the way the map says (even if it's just npm run dev and seeing the homepage). A map for a project that won't run is cartography on paper.
• Read dependencies, not descriptions. Open package.json, requirements.txt, or go.mod. Dependencies don't lie: bullmq installed means there's really a queue; prisma means there's really a database. That's more reliable than any architecture prose.

By end of day one you should hold one document: where the entry is, what the modules are, where data flows, what's still a guess. It doesn't need to be pretty. It needs evidence behind every line.

3. Step two: trace one main flow

With the map in hand, step two is not reading every module — it's tracing exactly one flow: from the user entry point down to data storage, mastering the single most important call chain. Skimming ten modules is worth less than truly owning one flow, because a flow gives you the instinct for "if I change this, who gets hit," while skimming gives you loose trivia.

Which flow to pick

Pick the feature users touch most. For e-commerce that's checkout; for a content platform it's publishing; for a SaaS tool it's login. The most-used flow is also the most-tested path — its code is usually the cleanest, and 80% of your future changes will land somewhere on it.

Get AI to locate the flow's entry with a specific question: "After the user clicks the 'Place Order' button, which backend function is called first? Give me the file path and line number." Never ask "how does the order flow work" — questions that broad only buy you more unverifiable prose.

How to trace it

Start at the entry function and drill down layer by layer, recording at each step:

1. Which file and line the current function lives in, and its signature;
2. Which downstream functions it calls directly (direct calls only — don't expand yet);
3. What key arguments each call passes and what it returns;
4. Whether there are branches (if/else, try/catch, feature flags) and what the conditions are.

Follow it until data truly lands: which table it was written to, which external API was called, which message was published. Then draw the flow as a sequence diagram. Yours should look something like this:

The drawing tool doesn't matter (pen and paper, Excalidraw, Mermaid all work). What matters: every arrow corresponds to a real function call you saw with your own eyes. An arrow you can't draw means logic you don't truly understand yet — go back and trace it.

Three questions the flow must answer

When the trace is done, you should be able to answer off the top of your head:

• "If I need to change how the order total is calculated, which files do I touch?" — if you can't answer, the flow isn't owned yet;
• "Where's the most fragile link on this flow?" (e.g., stock deduction and order write not in the same transaction);
• "Which part most likely hides historical baggage?" (e.g., an if-branch whose condition makes no sense — write it down; step four will investigate it).

Day two's deliverables: one sequence diagram plus answers to the three questions. That diagram becomes your battle map before every future change.

4. Step three: verify understanding with changes

"I understand it now" is the least reliable self-assessment there is. There is exactly one way to test real understanding: change something and see if the result matches your expectation. Step three turns every "I think" into "I've verified" through a series of small experiments.

Experiment one: the minimal change

Make a harmless minimal edit somewhere: reword a log line, change a button label, add a console.log to a function. Then run it and check whether your change shows up where you expected.

It sounds silly, but it verifies the most basic thing of all: is the code you're editing actually the code that runs? Countless people have burned afternoons here — editing src/ while dist/ is what runs, or editing main while another branch is what's deployed. A five-minute experiment saves an afternoon of confusion.

Experiment two: deliberate sabotage

The most efficient trick of the excavation phase: comment out one call and see what breaks. Error messages are the best maps — the stack trace tells you precisely who calls this function, who it calls, and who breaks first without it.

The procedure:

• Pick a middle function on the flow and comment out its call to a downstream function;
• Run it, trigger the flow, read the error;
• Record: what the error says, which files the stack passes through, which link fails first;
• Restore the code and repeat with the next function.

Three to five rounds of this teaches you more about "who depends on whom" than three days of reading. One rule: do all experiments on a throwaway branch and delete it when done — never let experiment code pollute the repo.

Experiment three: lock "I think" into tests

Every time you verify an understanding, immediately pin it down with a minimal test or assertion. Discovered that "order total = item subtotal × discount + shipping"? Write an assertion that nails it. These tests don't need to enter CI (unless you want them to). Their value: the next time you or AI touch related code, the test tells you instantly whether your understanding still holds.

There's a side benefit: these tests become your first genuinely valuable contribution to the project — no maintainer rejects a "add tests" PR.

5. Step four: investigate "why is it written this way"

After tracing and verifying, you'll hit awkward code: seemingly redundant if-branches, magic numbers from nowhere, large commented-out blocks, oddly named compatibility shims. A beginner's first reaction is "this is badly written." A veteran's first reaction is — there might be a production incident behind this.

Git is the best excavation site

For every piece of awkward code, walk this process:

1. git blame: see who wrote this line and when;
2. git log -p --follow <file>: read the line's full change history, watching for "fix," "hotfix," "urgent," or "revert" in commit messages;
3. Find the linked PR / issue: commit messages usually carry numbers — follow them into the discussion, because many "whys" live in PR comments;
4. Check the timeline: if the commit landed at 3 AM with the message "fix," it was almost certainly a production firefight, and this awkward code is the scar tissue.

The classic pattern looks like this: an if (userId.startsWith("legacy_")) branch that seems entirely redundant. Blame shows it was added in a 3 AM hotfix two years ago; the linked issue reads "orders lost after legacy user migration." Deleting that branch means personally resurrecting a two-year-old incident.

The risk register: step four's deliverable

Organize the awkward code and its backstories into a risk register:

Location	What's awkward	Historical reason	Safe to touch?
order.ts:142	legacy_ prefix branch	Hotfix for the 2024 migration incident	No — keep for compatibility
pay.ts:88	Silently swallows errors after 3 retries	Unknown, no commit history	Unconfirmed: add logging first
util.ts:30	Large commented-out block	Author's own commenting, no incident	Yes, back up the branch first

Note the second row's "unknown" — mark it honestly. Not knowing is fine; "unconfirmed" is infinitely safer than an invented reason. This register becomes your most important protection for the next three months: check it before every change.

6. Step five: distill it into a project context file

Everything from the first four steps — the map, the sequence diagram, the verified understandings, the risk register — dies with your session if it only lives in your head. The next conversation with AI will start making the same mistakes from zero. Step five distills it all into a project context file: a long-term asset for you and AI alike.

Where to write it, what to write

The filename depends on your tooling: CLAUDE.md for Claude Code, .muserules for Cursor, or the generic AGENTS.md. The name doesn't matter — what matters is that it sits at the repo root where AI reads it at the start of every session.

Suggested structure:

# Project context (excavated 2026-10-24)

## What this project is
One sentence: xxx. Entry point: xxx.

## Tech stack (verified only)
- Backend: xxx (evidence: package.json)
- Database: xxx (evidence: DATABASE_URL in .env.example)

## Core flows
- Order flow: frontend createOrder() → POST /orders →
  OrderService.create() → InventoryService.lockStock() →
  write to orders table
- Sequence diagram: docs/arch/order-sequence.png

## Danger zones (read before changing)
- The legacy_ branch at order.ts:142 is a hotfix from the 2024
  migration incident — do NOT remove
- pay.ts:88 swallows errors silently for unknown reasons —
  add logging before touching

## Conventions
- All experimental changes go on throwaway branches, deleted after
- Never cite code under examples/ as evidence for production logic

Three iron rules for writing it

• Only verified claims go in. Guesses stay out. Anything marked "guess" never enters the file. AI trusts this file unconditionally — an error here gets amplified tenfold.
• "Don't do X" beats "do Y." "Don't remove the legacy_ branch" is worth far more than "the order module handles checkout." The danger-zone list is the highest-ROI section of the file.
• Keep updating it; never treat it as done. Every new verified understanding, every new pit you step in, gets appended. In three months this file will be closer to the project's truth than any official documentation — because it was written with real incidents.

This file has two readers: you, three months from now, and the next person to inherit this repo (probably also staring at AI, wondering where to start). Your first week's excavation becomes their first map. That's the full circle of archaeology.

The first-week delivery checklist

Compress the five steps into a timetable and pin it to your wall:

When	Task	Deliverable	Done when
Day 1	Survey: evidence-backed architecture map	Module responsibility table with evidence & confidence	3 random evidence spot-checks all hold; project runs
Day 2	Trace one main flow	Sequence diagram + answers to 3 questions	Every arrow maps to a real call; you can say what breaks what
Day 3	Verify understanding with changes	3–5 sabotage experiment logs + pinning tests	Every "I think" has an experiment or test behind it
Day 4	Investigate "why is it written this way"	Risk register	Every awkward spot has a history or an honest "unconfirmed"
Day 5	Distill the context file	CLAUDE.md / AGENTS.md	Only verified claims; danger zones complete

After five days, you'll understand this codebase better than many "veterans" who've sat on it for a year — because veterans run on fuzzy muscle memory, and you run on a method with an evidence chain. More importantly, from week two on, every change you ask AI to make is backed by a map, a flow, a risk register, and a context file. AI writes code fast — but knowing where to point it and what it must never touch is the real scarce skill of the vibe era.

Dig before you touch. May your first week unearth treasure, not landmines.