Read the Change, Not the Whole File

Most of the time you are not reading a whole file. You are looking at a change: the agent proposes an edit, shows you red lines and green lines, and asks you to accept. That view is where you actually decide whether code is any good, and it has its own way of being read. This chapter gets you reading it.

4.2.1The diff is where you actually look at codeAdd note

A diff is the view of what a change adds and removes, not the whole file. When the agent finishes an edit, this is what it shows you: the few lines that moved, not the hundreds that stayed.

It is also the exact moment you approve or reject the work. That makes the diff the highest-value thing to be able to read, more than any full file, because it is where your decision actually happens.

4.2.2Red is removed, green is addedAdd note

The diff uses two marks and nothing more. A line with a minus in front, shown red, was removed. A line with a plus in front, shown green, was added. The plain lines around them did not change, and they are only there to give you context.

Here is a small one, changing how a total is calculated:

Read it as one thought: the old line charged a flat ten per item, the new line adds up each item's real price. You judge the change by comparing the red to the green, not by rereading the whole function.

4.2.3A small, focused diff is easier to trustAdd note

A change that touches thirty files at once is not something you can honestly read, so you end up accepting it on faith. A change that touches one thing is something you can actually check. Smaller is safer here for a plain reason:

• You can hold it in your head. A few lines fit; thirty files do not.
• You can spot the odd line. In a small diff, the one wrong change stands out.
• You can undo it cleanly. A focused change is easy to reverse if it turns out bad.

So ask the agent to work in small, focused changes, the same one-thing-at-a-time habit the chapter on building in small steps pushes. You are not being difficult, you are keeping the diff readable.

4.2.4Judge the change when you accept itAdd note

The accept button is a decision, not a formality. Before you click it, scan the red and green once: does the change match what you asked for, and is anything there that should not be? If a line makes no sense to you, that is not a reason to wave it through, it is a reason to ask.

The agent that wrote the diff will also explain any line in it, in plain words, at your level.

Do this now: the next time your agent proposes an edit, read the red and green before you accept, and paste the prompt to have it walk you through any line you are unsure about.