手法1：変更を教える説明を作る

In the previous chapter, we saw the problem that if we leave understanding to an AI agent and put it off, humans may later lose the ability to participate in the work. Now we will look at concrete techniques for this problem. The first technique is to make the code change itself an opportunity to teach people.

Showing a diff is not enough

AI agents can create large code changes faster than humans can. But even if we can check whether a change is correct, we may not understand what the change means. A raw code diff, which only lists file names and red and green lines, shows where the code changed. It does not automatically show the background the reader needs or the relationships among the changes.

The code explainer proposed by the speaker is not a shortened, polished diff. It is a small learning curriculum made for a particular reader to understand a change. It first explains the necessary background, then shows the purpose and idea of the change, and only afterward moves to implementation details.

Supplement: This does not mean that people must always read every line in order. The goal is to grasp how the system works and what the change means through a route other than following the lines one by one.

Figure 1: An explanatory diagram using people and arrows is placed below a red-and-green code diff.

This slide is a presentation graphic contrasting a simple red-and-green comparison with an explanation that helps people understand it. The people and arrows around it can be read as an image connecting the act of reading a diff to an explanation that can be learned from. However, the exact layout of the actual explainer document and its code implementation cannot be confirmed from this video. Watch at 00:06:58

Turn the Zen-garden change into one story

The concrete example the speaker shows is a Zen-garden game. The game changed from a top-down view to an isometric view. An isometric view is a way to make a 2D screen look as if it has depth.

What matters here is that the explainer does not end as a list saying, "This line in this file changed." When the game engine and the idea of coordinates come first, readers can think about why the garden's appearance needs to change and which relationships are changing. The speaker describes making explainers like this as HTML, Markdown, or a collaboratively edited Notion document.

Figure 2: A Notion-like document titled "Code explainer doc" explains the change in the Zen garden's display.

The slide shows a document for changing the Zen garden from a top-down view to an isometric view. Therefore, we can confirm that the code explainer is presented as a document containing the background and purpose of a change. The detailed implementation text is too small, so we cannot say that a specific algorithm or file structure is shown. Watch at 00:07:46

Build the background first

This explainer document does not begin suddenly with the changed lines. In the speaker's example, it first introduces the game engine, the coordinate system, and several subsystems. Here, a coordinate system is the basic mechanism for representing where objects are on the screen. A subsystem is a part of the game that has a particular role.

With this background, readers can see a change not as an isolated group of lines but as an event within an existing system. For example, if they know how coordinates are handled first, they can more easily think that a change in how the screen looks touches the relationships among position and drawing. Background is not decoration. It is the foundation for interpreting the details that come later.

Figure 3: A background document explains Phaser 3, the coordinate system, and the flat canvas before the change.

The visible slide gives an overview of Phaser 3, a game engine, a flat canvas, and the parts that draw the scene. In other words, it explains the environment in which the change works before the reader examines the changed code. The detailed text is small and cannot all be read accurately, so we should not infer specific implementation details from it. Watch at 00:08:01

A shared document keeps understanding from ending with one person

When an explainer is a collaboratively edited document, understanding no longer belongs only to its creator. Teammates can comment at the relevant place in the document and ask about things they do not understand. Someone else can add an answer or their own idea in the same place.

This has two effects. First, readers of the change need less often to remember their questions and ask them somewhere else. Second, because the questions and answers remain with their context, later readers can use the same explanation. This creates a place where people can think together about the same change after asking an AI to write the code, instead of removing people from the conversation.

The process of this technique

The practice in this chapter can be summarized in the following order.

1. Show the background of the change. Explain the foundation the reader needs, such as the game engine, coordinate system, and subsystems.
2. Explain what the change means. Put into words what you want to change, such as changing the Zen garden's display from a top-down view to an isometric view.
3. Move to the details. Read the changed code using the background and purpose as guides.
4. Deepen understanding together. Share it in a form where readers can leave comments and questions, such as HTML, Markdown, or a Notion document.

This is not a way to throw away code diffs. It is a way to place a diff into an order and context that readers can understand. The more code an AI agent creates, the more important this order becomes. Even if readers see every changed line, they lose an opportunity to understand if they cannot use the change to make their next decision or idea.

Summary

In the speaker's first technique, an agent's code change becomes not only a "deliverable" but also a "lesson." Putting the background first builds a model for reading the implementation details. In the Zen-garden example, the change from a top-down view to an isometric view is explained together with that background. HTML, Markdown, and collaboratively edited Notion documents then allow individuals and teams to deepen their understanding.

The central idea of this chapter is that showing a diff and teaching someone to understand a change are not the same thing. The next principle narrows the order of this explanation further: it presents the intuition and purpose of the change before the implementation details.

Uncertainty: The explainer document described by the speaker and the actual code are not provided. Therefore, this chapter covers only the confirmed purpose, background, and display examples; it does not fill in the document's exact structure or implementation details.