The change landed late one night. You had asked Claude Code for an export button, the kind that turns a screen of records into a CSV download (a file any spreadsheet can open), and it produced one, listed the files it touched, and printed a tidy summary. The demo worked on the first click. You accepted the change without opening a single file and went to bed feeling like a person who ships.
Two weeks later you are walking your first real user through the product. They click Export, the download arrives, and it holds the same three sample rows it held that night, no matter what is on the screen. The button was wired to placeholder data, the code said so in a comment, and the comment sat in a file you never opened. Nothing broke quietly behind your back: the warning was right there in the change, and the change went unread.
Read for structure and intent, not the code itself
The fix is not learning to program.
You can read what an AI built without being an engineer, because you read for structure and intent, not the code itself: where things landed in the project, and whether the change matches what you asked for.
Both are readable by anyone who can follow a map and a before-and-after. People who ship with AI and people who ship bugs with AI use the same tools, and the difference is that the first group reads the work before accepting it. The moves below are that reading, and they cost a few minutes per change.
Skim the file tree: where everything lives
Start above the code, with the tree of folders every project is organized into. Any tool prints it on request, and the same handful of folder names repeats across nearly every web project.
apporpagesholds the screens, roughly one file per page a user can visit.componentsholds reusable interface pieces, the buttons, cards, and navigation bars that pages assemble.lib,utils, orapiholds the working logic, the code that fetches, computes, and saves.publicholds files served exactly as they are: images, fonts, icons.- The root holds configuration, including the manifest (
package.jsonon web projects), which lists the project's name and every library it depends on.
The skim asks one question: did the change land where the task suggests it should? A wording fix that touches one file in components reads as expected. One that also edits the manifest and adds a folder you have never seen raises a question, and the time to ask is before you accept.
Read the diff: what was, what is now
The diff is the before-and-after of a change, file by file, line by line, the same view of your project's history you met in Git: the undo that makes AI edits safe. Your coding tool presents finished work as one, because the diff states exactly what happens to your project if you say yes. Read it in a fixed order.
Filename first. The path tells you what kind of thing changed before you read any code. A change in components/Nav.tsx is interface; a change in lib/billing.ts deserves a slower read.
Minus is what was, plus is what is now. Removed lines carry a minus, added lines carry a plus, and you read shape rather than syntax. A "small fix" that removes forty lines is larger than its description.
Check the file count against the task. More files than the task needed is a question. Sometimes the answer is sound, a rename has to reach every file using the name, and sometimes the change did more than you asked.
Ask for the explanation, then ask what it glossed over
Some file in the diff will still read as noise, and that is fine, because the tool that wrote it will also explain it. Make that file your next prompt and ask twice, in order.
The plain-language ask. "Explain lib/export.ts in plain language, to someone who does not write code. What does it do, what does it depend on, and what breaks if it is wrong?" The answer turns a screen of syntax into a paragraph you can judge against your own intent.
The follow-up that does the real work. "What did your explanation gloss over?" A first explanation is generated to read smoothly, and smoothness compresses the awkward parts: the edge case nobody handles, the shortcut that holds only while the data stays small, the step that quietly depends on a service you have not set up. The follow-up makes those omissions the subject of the answer.
Run the pair on the one file you understand least, since that is where the risk concentrates. Claude Code answers these questions as readily as it produces code.
Check whether the feature is real or just staged
A mock is a stand-in, code that looks like the feature without doing its work. Mocks are legitimate scaffolding mid-build, and they are exactly how an export button ships wired to three sample rows. The signs of a staged feature repeat reliably enough to scan for.
the work is postponed, not done
the demo is wearing a costume
nothing is computed
normally is doing all the work
See one? Ask the tool what is real before you build on it.
The mechanical scan. Search the changed files for TODO, FIXME, placeholder, sample, and mock. The scan takes under a minute.
The behavioral test. Use the feature twice with different inputs. If the answer never changes, nothing is being computed.
The confession comment. A line that begins "this would normally call the API" is the code admitting it is staged, and the word "normally" means it does not call the API yet.
Finding one is a decision point, not a catastrophe. Ask: "List everything in this change that is placeholder or staged, and what is missing before each piece can be real." The answer is usually a missing credential, a missing decision, or context only you can supply.
Make this reading part of how you accept a change
Every tool has an accept moment, the keystroke that lets a change into your project, and that moment is where the habit lives: skim the tree, read the diff, ask for an explanation where you need one, scan for mocks, then say yes. Working with AI as a builder gave you the iteration loop, and reading is the checkpoint inside it. The Playbook carries the rest of the discipline: the verify-first rule makes the tool prove a foundation before features stack on top of it, and the failure modes catalog names the patterns you are scanning for. Every page of this site passed through this gate, and it has caught problems no recap mentioned.
Try it now
No setup: Open GitHub in a browser, pick any open-source project you have heard of, and open its Pull requests tab (a pull request is a proposed change waiting for review). Choose one, click Files changed, and read one diff with the moves from this chapter: filename first, minus is what was, plus is what is now, file count against the task in the title, and a scan for mock tells. You will understand more of it than you expect.
With your tools: The next time Claude Code finishes a change, stop at the accept moment. Read the diff, pick the one file you understand least, ask for the plain-language explanation, then ask what the explanation glossed over. Accept only when both answers would survive being repeated to a user. In Codex or Cursor the move is the same: the sidebar shows each file's diff before you apply it, and the same two questions go into the chat. If your tools are not set up yet, the Setup Clinic gets you there in one sitting.
Chapter Summary
- You can read what an AI built without being an engineer, because you are reading for structure and intent, not the code itself.
- Skim the file tree first to check that the change landed where the task suggests it should.
- Read the diff before you accept: the path tells you what kind of thing changed, minus lines are what was there, plus lines are what is there now.
- Check the number of changed files against the task. More files than the task needed is worth a question before you say yes.
- Treat the recap your tool prints as generated text that can be wrong. Accept on the diff, never on the recap.
- For any file you still cannot follow, ask the tool to explain it in plain language, then ask what the explanation glossed over.
- Scan for staged work: search for words like TODO and placeholder, run the feature twice with different inputs, and watch for a comment that admits the code is not real yet.
- Do all of this at the accept moment, so reading becomes the checkpoint right before a change enters your project.
- That gate covers changes you can see, but some failures arrive through what a build exposes, so next is Guardrails: keep secrets, money, and data safe.