Before Letting Codex Touch a Legacy Codebase, Make It Do These Three Things

Taking over a codebase that has been running for years, the scariest part isn't messy code — it's changing one place and breaking three others. I've been maintaining a legacy project with Codex lately, and after a few painful rollbacks I fixed my opening routine into three steps. Sharing it here for anyone doing similar work.

Step 1: Read-only first — make it map the project

Don't start with "change this feature for me." When Codex has no model of the project yet, what it produces tends to clash with existing conventions and abstractions.

My first message is now always:

Don't modify any files yet. Read the directory structure, the entry points, and the code related to user login. Tell me: where login state lives, which files this change would touch, and what you're unsure about.

That list is your chance to verify it actually understood the project. If the list is off, correct its mental model before any code changes. Ten minutes here saves two hours of rollback later.

Step 2: Plan first — and the plan must include how to verify

Once it knows the terrain, the second message asks for a plan, and the plan must include verification:

Give me a minimal-change plan: which files, what changes in each. Also write down how we'll verify — which test to run, which page to open, what we should see. Show me the plan first; don't start until I confirm.

The key words are "minimal change." Without that constraint, AI happily "improves" a ring of unrelated code and hands you an unreviewable diff. Writing the verification steps in advance has a second benefit: afterwards you don't have to invent checks — you just walk its own list.

Step 3: One change at a time, verified immediately

When real work starts, only approve one change point at a time. If this round is about login expiry logic, change only that, run the verification, confirm it's fine, then allow the next point.

I learned this the hard way: I once let it change three places at once, something broke, and there was no way to tell which change caused it. The whole batch got rolled back. Single-point progress feels slower, but total time ends up shorter.

Three easy-to-miss reminders

1. State the hidden conventions out loud. Things like "every API call in this project goes through the shared request wrapper, never call fetch directly" are invisible in code. Write them into your instructions — better, keep them in an AGENTS.md at the repo root so you don't repeat yourself.
2. Demand file and line numbers in reports. "Done" carries zero information. Require every report to say which file, which section, and what the verification result was.
3. Database changes get separate approval. For schema or migration work, have it generate the script only — a human reads it before anything runs. These are the most expensive changes to roll back.

The short version

Understand first, plan second, execute one point at a time. Each step leaves a human checkpoint: Codex does the work and the self-checking, you make the calls at the points that matter. The real risk in legacy code isn't moving slowly — it's not knowing what else your change just broke. This routine is built to remove exactly that uncertainty.

I write about practical ChatGPT and Codex workflows at Yunsi Guide.