Claude Code on an Inherited Repo: Make the First Edit Safe

On my first day with an internal repo I’d just inherited, I blew it.

I told Claude Code, “Read the whole thing and clean up anything that looks off.” Thirty minutes later, 23 files had changed. The edits weren’t bad on their own. But it had also “tidied up” the production deploy config and the billing files nobody is allowed to touch. The diff was so big I couldn’t tell which changes actually mattered. I threw all of it away and started over.

A smart AI doesn’t crash because it’s incapable. It crashes because nobody decided how far it was allowed to reach before it went in. Today we rebuild that first day into something reversible, verifiable, and actually finished.

Key takeaways

• The day you first enter someone else’s code, write a one-pager first: where it may read, where it must never touch, and the check command to run when it’s done.
• Don’t hand Claude Code a big refactor on day one. Start with one small, reversible edit (renaming a test, adding a comment).
• Before you accept any “done” report, run one verification command and keep the result.
• Deletes, the production database, billing, and force-push all stay pinned to “ask a human” on day one. Automate only what you’ve proven is safe.
• When the diff starts ballooning, don’t rewrite the prompt first — shrink the set of files the AI can touch.

Why you set the boundaries on day one

A new repository is a city with no map. Which file is the heart, which one breaks if you touch it — nobody can see that at first.

If you tell Claude Code “look at everything and fix it,” the AI helpfully reaches wide. That’s not the AI’s fault. The blame sits with the human who never handed over a scope. If you tell a brand-new hire “just make the shop look nice” and they go reconfigure the cash register, that’s on whoever gave the instruction.

So the first move isn’t writing a clever prompt. It’s drawing one map: the shelves you may read, the drawers you must not open, the doors you check before leaving. Just writing those three things on paper makes most day-one accidents disappear.

The three boundaries you set first

Order matters. Lock them top to bottom.

What to decide	Examples	Why decide it first
Where it may read	src/, docs/, test files	Let it read everything and it’ll propose unrelated changes
Where it must not touch	.env, billing, auth, DB migrations, production deploy config	Break these and there’s no going back
What to run when done	npm run build, one test	So you leave “proof it works” behind every time

I keep the paper holding these three (plain text is fine) in an ONBOARDING.md in the work folder. It’s also the first file I have Claude Code read. Share the map, then let it walk the city — in that order.

What you delegate to the AI vs. what you decide yourself

Blur this line and you get accidents. So draw it sharply.

Work it’s fine to hand Claude Code

• Skim the whole repo and summarize the structure
• Find “which file holds this feature”
• Draft reversible small improvements: renaming tests, adding comments, filling in types
• Run the check command, read the failure log, and form a hypothesis about the cause

Work a human must always decide

• Whether to allow a change that enters an off-limits area
• Deleting files, operating on the production DB, touching billing, force-pushing
• The final call on whether a large design change gets merged
• Whether to stop when the diff grows wider than you expected

My rule is simple. Anything I can undo with git, the AI does. Anything I can’t undo, a human presses the button. Hold that one line and day one won’t fall apart.

A copy-paste prompt template

Before the first edit, I throw this in. The trick is not letting it write code yet — make it return a plan first.

This is an existing repo I'm touching for the first time. Follow these rules.

[May read]   only src/, docs/, and test files
[Don't touch] .env / auth / billing / DB migrations / production deploy config
[Goal this time] exactly one small, reversible improvement (e.g. renaming a test)
[Verify] after the change, always run `npm run build` and paste the result

Do not change any code yet.
First return your plan for which files you'll edit and how,
and restate the rules above in your own words.

If the plan it returns restates your constraints faithfully, it passes. If it’s trying to widen the scope, stop it right there. If the plan is good, move on: “Good — do exactly that, and run the build.”

Keep the boundaries as code

Paper rules get forgotten. So I also keep the onboarding plan in a machine-readable form. The script below runs as-is. Swap in your own repo’s details before using it.

#!/usr/bin/env bash
# Collect the existing-repo onboarding plan into a single JSON file
set -euo pipefail

cat > onboarding-plan.json <<'JSON'
{
  "goal": "Finish the first edit on an existing repo safely",
  "readOnlyCommands": [
    "git status --short",
    "git ls-files | head -50",
    "grep -rn \"TODO\\|FIXME\" src | head -20"
  ],
  "protectedAreas": [".env", "billing", "auth", "db/migrations", "deploy/prod"],
  "firstTask": "One reversible small improvement to docs or a test",
  "proofCommand": "npm run build",
  "rollback": "git diff -- path/to/changed-file && git checkout -- path/to/changed-file"
}
JSON

echo "=== Onboarding plan ==="
cat onboarding-plan.json

echo ""
echo "=== Current diff (empty means nothing edited yet) ==="
git status --short

This script isn’t flashy. Its value is that it pins the off-limits areas and the proof command to a file before you start working. Rewrite protectedAreas to point at the dangerous spots in your own repo and you’ve got a day-one map.

It helps to have one verification command ready too. For a Node.js project, this minimal check confirms mechanically that nothing’s broken.

// check.mjs : the smallest script that just confirms the build passes
import { execSync } from "node:child_process";

try {
  // Replace with your own project's verification command
  execSync("npm run build", { stdio: "inherit" });
  console.log("Check OK: the build passed. Review the diff.");
} catch (e) {
  console.error("Check FAILED: the build broke. Don't merge — find the cause.");
  process.exit(1);
}

If node check.mjs is green, send the diff to review; if it’s red, stop. This one file alone kills the “it should work” accident where you merge on a hunch.

Three real situations

If one of these is close to yours, don’t rebuild the steps — just swap in your own names.

1. Inheriting a content site First have it learn where the article data lives, the image folder, the build command, and the product pages. The first edit is just “fix one broken link.” Once the build passes, send it to review. Save the big body rewrites for after you’ve proven it’s safe.

2. A SaaS codebase Spell out auth, billing, and DB migrations as off-limits. Narrow the first task to something like “make the test descriptions easier to read,” and have a human approve before going further. Go soft here and a “helpful improvement” lands in your payment logic — heart-stopping.

3. An old legacy repo “Modernize the whole thing” is a banned phrase. It produces a diff too big to read. Instead, start with a small step you can verify by build: fixing a typo in a function name, renaming a test. Succeed once, then take the next step in the same shape.

Every one of these has a stopping point. Because there’s a stopping point, the work doesn’t expand forever.

Failures, and how to fix them

Honestly, I botched all of these the first few times.

Asked without writing the off-limits list → the diff grew too big to review and I scrapped it all. The fix is dead simple: before you rework the request, cut down which files it may read. The narrower the scope, the narrower the AI’s blast radius.

Built only after all the changes were done → I couldn’t tell which edit broke things. Now I run the check after each file I touch. The moment it breaks gets recorded, so the cause is obvious right away.

Relied only on my own eyes for review → on a busy day, I always miss something. Whatever a machine can know, hand to the machine: build pass/fail, test results, broken links. Save human eyes for the design judgments the machine can’t catch. That alone cut my late-night reviews way down.

I leave the pitfalls in the article because success stories alone won’t let a reader notice their own dangerous state. Jotting down which request spread too far and which check was missing keeps the next version of you from stepping in the same hole.

FAQ

Q. What should the first edit be? A. Pick something you can undo with git checkout even if you’re wrong. Renaming a test, adding a comment, fixing a typo — all safe. New features and config changes aren’t day-one material.

Q. How granular should the off-limits list be? A. Just “places where breaking them is irreversible” is enough. .env, auth, billing, production deploy config, DB migrations. Nail those five first and you’ll prevent almost every fatal accident.

Q. Can I skip the step of making Claude Code return a plan? A. I’d recommend you don’t. That one extra step of restating the plan catches scope drift before any editing. It’s far cheaper than realizing it after code is already written.

Q. Is the build enough for a verification command? A. On day one, the build alone is enough. Once you’re comfortable, add one related test. Trying to run the whole suite from the start is too heavy to sustain. Start small and grow it after the green logs pile up.

Q. Anything to watch when rolling this out to a team? A. Write the boundaries in a shared file like ONBOARDING.md so everyone uses the same map. If each person’s off-limits list differs, the review bar wobbles too.

Related reading

For the underlying mindset, How non-engineers can use Claude Code and Claude Code first-steps guide are good starting points. The craft of teaching it your project rules is in CLAUDE.md best practices, and a deeper take on giving instructions is in Advanced prompt engineering. For the fine print on permissions, check the official Anthropic docs too.

What I found when I actually tried this

After the “23-file accident” up top, I changed the order of my onboarding. I stopped hunting for a clever prompt and instead pinned the off-limits areas and the check command in onboarding-plan.json first. That alone took accidents involving billing or production config to zero.

The day I narrowed the first edit to “rename a test,” the diff fit in 8 lines and the build passed on the first try. Review took less than two minutes. The day I asked without setting a scope, the diff ballooned again and I scrapped everything. The difference wasn’t how smart the model was — it was whether I drew the map before going in.

If you want to harden this pattern for touching other people’s code using your own team’s real examples, I work through onboarding tailored to your workflow over in training and consulting. For today, start by writing out the five off-limits areas of your own repo.