Reading a diff

Last lesson, Claude proposed a change and showed you a small block of code with green and red lines. That block is the most important thing on your screen.

A diff is the line-by-line list of what’s about to change. Lines marked + are being added. Lines marked − are being removed. Unmarked lines are there for context — they show you where in the file the change lands.

That’s the whole format. It’s used everywhere — Claude, git, GitHub, every code review tool ever made. Learn to read one once and you can read all of them.

A worked example

 function greet(name) {
-  return "hi " + name;
+  return `Hello, ${name}!`;
 }

Three lines matter here. The function greet(name) line is context — unmarked, just showing where you are. The line starting with − is being removed. The line starting with + is being added.

So the change is: replace the old return statement with a new one. The function name and signature aren’t changing — those are context.

The trap: scanning vs reading

Most people glance at a diff. They see a few green lines, a few red lines, the names look about right, and they hit accept.

That’s not reading. That’s nodding.

Claude can be confidently wrong. It can rename a variable correctly in five places and forget the sixth. It can add the line you asked for and also delete one you didn’t. The diff shows you that. The diff is the truth. The diff is what’s actually about to happen.

When the diff is more than ten or fifteen lines, slow down. Read each + and each −. Ask yourself: did I ask for this line? If the answer is no, that’s the catch.

Don’t read the summary, read the diff

Claude will often summarize a change in plain English above the diff. Something like:

I’ve renamed usr to user throughout the file.

That sentence is interpretation. The diff is reality. Sometimes they match. Sometimes the diff also moved a function, or removed an early return, or fixed a typo Claude noticed in passing. The summary won’t always say so.

Read the diff. Always. The summary is a hint, not a contract.

Try one

Here’s a small diff. Read it before you scroll to the quiz.

 const total = items.reduce((sum, item) => {
-  return sum + item.price;
+  return sum + item.price * item.quantity;
 }, 0);

What’s next

You can now read what Claude proposes. The next lesson is what to do when what Claude proposes is almost right but not quite. The skill is keeping the conversation going instead of starting over.