Claude Code and Someone Else's Repo: Map It Before You Fix It

On my first day on a handover, I opened the internal-tool repo my predecessor had left behind. The README was three lines long and the last commit was eight months old. I figured I’d just point Claude Code at it: “Get up to speed on this project and fix the wording on the login screen.” Five minutes later it had also “tidied up while it was in there” — the auth config files and a production deploy script nobody had touched in months.

Luckily git status caught it and I reverted everything. But to this day my stomach drops when I imagine having run git commit without noticing. The problem wasn’t how smart the model was. The problem was that I handed off the work without knowing which parts were safe to touch.

The first hour inside someone else’s code is not for fixing. It’s for drawing a map. This article walks through how to draw that map as a step-by-step routine that keeps you out of trouble even on a repo you’ve never seen.

Key takeaways

• The first hour is for “drawing a map,” not “fixing.” Separate the safe-to-touch zones from the do-not-touch zones up front.
• Hand Claude Code the job of “read and list it out” — and nothing more. A human decides what becomes protected.
• Before any fix, pick exactly one proof command (build or test). That command is your evidence that something is actually “fixed.”
• Limit the first fix to something small enough to revert with a single git command.
• Save what you learned in a one-page note, so the next person into this repo (your future self included) doesn’t repeat the same investigation.

Why the first hour is where accidents happen

When you stumble on a new repo, it’s usually not because the code is hard. It’s because you can’t see the shape of the repository.

Which folder is the UI, which part is the backend logic, which file is the production config? Ask Claude Code to “make it nice” without knowing those things, and it will rewrite a wide area with the best of intentions. Unless you tell the AI “don’t touch this,” it assumes a file is fair game.

Handover projects are especially dangerous. The previous owner’s unwritten rules, naming quirks, commented-out code left in for no obvious reason — none of that context is written down anywhere in the code. Even a human can’t grasp it all on day one. That’s exactly why the first thing you do is not editing, but mapmaking.

The four steps to drawing a map

Order matters. Decide what to read, decide the protected zones, decide the proof command, and only then fix one small thing. Go in that order.

Step 1: Write today’s goal in a single sentence

“Understand this project” is too broad. Both Claude Code and people lose track of where to stop when the goal is wide.

Write this instead: “Fix the wording in exactly one place on the login screen, and confirm the build passes.” A goal you can state in one sentence is also a goal you can see is finished at a glance.

Step 2: Separate what to read from what must not be touched

This is the heart of the map. Before you hand Claude Code “read anything you want,” put the do-not-touch zones into words first.

The areas I mark as protected every single time: authentication, billing, environment-variable files (.env), and production deploy scripts. Get those wrong and the damage is large and hard to undo. So at the start I make it explicit: “Reading is fine, but do not write.”

Step 3: Decide the proof command first

When the agent says “it’s fixed,” what actually counts as fixed? Decide that ahead of time.

On most projects, a build command or a test command is your proof. npm run build passes; npm test goes green. Pin down that one command before you make the fix, and you can judge by a machine’s pass/fail instead of taking Claude Code’s “done!” at face value.

Step 4: Exactly one reversible, small fix

Once the map exists, don’t get greedy with the first fix. Pick one thing you can revert with a single git checkout — a wording change, a comment, an obvious typo.

Resist “while I’m at it, let me also…”. Big diffs are something nobody can review, and the cleanup when something goes wrong is brutal.

What to delegate to Claude Code, and what a human decides

In mapmaking, what you delegate and what you keep in your own hands is everything. Blur that line and you get the accident from the opening of this article.

Task	Owner	Why
Listing files and understanding folder structure	Claude Code	Mechanical reading is fast and accurate
”Where does this feature live?” investigation	Claude Code	Good at search and summarization
What becomes a protected zone	Human	The scale of damage is context-dependent; the AI doesn’t know it
The final call on the proof command	Human	Only a human knows the project-specific circumstances
Changes to production, billing, auth	Human	Hard-to-undo operations get human approval

The principle is simple. Delegate the reading and the listing. Keep the hard-to-undo judgment calls in human hands. Only once an operation is confirmed safe do you promote it to Claude Code later.

The fine-grained design of permissions is covered in a separate article. If you’re stuck on what to block first, see the permissions guide.

A copy-paste mapmaking prompt

This is the prompt I actually throw into the first hour. Paste it as-is and just swap in your own repo name.

This is my first time touching this repository. Do not edit anything yet.
Investigate the following in order and report the results as a bulleted list.

1. The top-level folder structure and the role of each one (guesses are fine, but mark them as guesses)
2. The commands used to build, test, and run (from package.json or the README)
3. The location of files related to authentication, billing, environment variables, and production deploy
4. Which file holds the "login screen wording"

After the report, the files from #3 are "read-only, editing forbidden" for this session.
The only file you may edit is the single one you found in #4.

The key is to nail it down in the first line: “do not edit yet.” Without that, some agents start fixing things as a side effect of investigating.

A copy-paste, runnable verification script

Once the map exists, it’s reassuring to be able to run the same check before and after a fix. The script below confirms the build passes and that the diff hasn’t grown too wide before and after the change. It runs on Node.js.

// verify-edit.mjs
// Confirms the build passes before/after the fix and that the diff isn't bigger than expected
import { execSync } from "node:child_process";

// Cap the number of changed files to keep it inside one-command-revertable range
const MAX_CHANGED_FILES = 3;

function run(cmd) {
  return execSync(cmd, { encoding: "utf8" }).trim();
}

try {
  // Count the changed files
  const changed = run("git diff --name-only")
    .split("\n")
    .filter(Boolean);

  console.log(`Changed files: ${changed.length}`);
  changed.forEach((f) => console.log(`  - ${f}`));

  if (changed.length > MAX_CHANGED_FILES) {
    console.error(
      `Diff is too wide (${changed.length} > ${MAX_CHANGED_FILES}).`,
    );
    console.error("Revert with git checkout once and split the fix into smaller pieces.");
    process.exit(1);
  }

  // Confirm no protected zones were touched
  const protectedHits = changed.filter((f) =>
    /(^|\/)\.env|auth|billing|deploy/i.test(f),
  );
  if (protectedHits.length > 0) {
    console.error("A change landed in a protected zone:");
    protectedHits.forEach((f) => console.error(`  - ${f}`));
    process.exit(1);
  }

  // Confirm the build passes (swap this out for your project's command)
  console.log("Checking the build...");
  run("npm run build");
  console.log("Build OK. The fix stayed inside the safe range.");
} catch (err) {
  console.error("Verification failed:", err.message);
  process.exit(1);
}

Run it with node verify-edit.mjs. If too many files changed, or a protected zone was touched, it stops right there. The “it tidied up my auth files” accident from the opening would have been stopped before it happened if I’d run it through this script.

Three situations where it pays off

To be concrete, here are three patterns I’ve tried it on.

1. An inherited internal tool When you’re going into a codebase with no docs. First have it list the folder structure and run commands, then pin auth and config files as protected zones. Make the first fix something whose result is visible to the eye, like a label change in an admin screen.

2. A first contribution to a public repo When you’re sending your first pull request to someone else’s open source. Have it identify the test command first, then ship one small fix while keeping npm test green. A single reversible one-file fix gets merged more easily than a broad list of improvement suggestions.

3. Restarting an old project When you’re picking up code you abandoned six months ago. Have Claude Code investigate “how much still works” and map the broken entry points. Fix the most easily revertable spot first.

Pitfalls and how to fix them

Pitfall 1: Trying to fix everything at once “While I’m at it, let me refactor too” balloons the diff to 50 files, and nobody can review it. The fix: cap the number of changed files with the verification script above. Over the cap, revert once and split.

Pitfall 2: Calling it done on a passing build alone A build passing locally doesn’t mean the screen looks the way you expect. For a wording fix, opening that actual screen and confirming the text with your own eyes is part of the set.

Pitfall 3: Communicating protected zones verbally only Saying “don’t touch auth” in the prompt can get forgotten partway through a long session. The fix: have the verification script mechanically reject changes to protected zones. Guard it with a command, not human memory.

Pitfall 4: Not keeping the map you investigated Spend an hour getting up to speed and skip the note, and next time you do the same investigation again. Write the folder structure, the proof command, and the protected zones into a single note, and your future self will thank you.

That map note works even better written into CLAUDE.md as the project’s rules. I covered how to write it in CLAUDE.md best practices.

FAQ

Q. In the first hour, do I really not fix anything? A. You can fix something, but limit it to “one small, revertable spot.” Spending the rest of the time on mapmaking ends up reducing accidents and is faster overall.

Q. Is handing Claude Code “read anything” dangerous? A. Reading alone isn’t dangerous. The danger is “write” permission. Read wide, write narrow. That’s the basic split.

Q. What about a project where I can’t tell what the proof command is? A. First have Claude Code suggest candidates from package.json or the README. If it’s still unclear, fall back to the minimum: just confirm git status shows no unexpected diff.

Q. Can I do the same thing in PowerShell? A. Yes. The logic of counting the output of git diff --name-only and comparing it to a cap writes cleanly in PowerShell too. Rewrite the verification script to fit the environment you’re using.

Q. Can a beginner run this workflow? A. Yes — and it helps beginners most of all. Even without fully understanding the code, deciding “the safe-to-touch spots” up front prevents major accidents. If you want to lock down the basics first, reading the getting-started guide first makes this go smoother.

What I found when I actually tried it

I built this routine for myself after the accident at the top. The thing that helped most when I tried it was adding the “cap on changed files” and the “automatic protected-zone check” into the verification script.

In practice, I ran it about three times on an inherited repo, and once it stopped because the number of changed files went over the cap. Looking inside, Claude Code had rewritten a shared component as a side effect of a wording fix — and if I’d let it through, the blast radius would have been an unreadable diff. Because it stopped, I was able to split the fix into two and ship them separately.

It’s not “hand it to a smart AI and you’ll be fine.” It’s “hand off only what you can revert when you trip.” Just drawing the map first completely changed the feel of that first hour. If you want to share this split with non-engineers on your team, the entry point for non-engineers is useful too.

You can also confirm the official way to use Claude Code in the Anthropic docs. If you want to lock down your own operating rules and turn them into something the team can reproduce, in training and consultation we map an actual repo of yours together.