Notion のエンジニアはこうやってコードを読む

なぜ diff を読むやり方から先に壊れるのか

diff はコードのどこがどう変わったかを行単位で並べた一覧だ。人が少しずつ直していた時代は、これを読むことがそのままレビューだった。変更は小さく、その変更を作ったのは自分だったから、一覧を見るだけで頭の中に絵が描けた。

エージェントがコードを書き始めると、この二つの前提が同時に崩れる。一度に数十のファイルが変わり、しかもそれを書いたのは自分ではない。一覧を最後までめくっても何も残らないのはそのためだ。情報が足りないのではなく、理解に必要な順序になっていない。

ここでよくある誤解がある。人がコードを理解すべき理由は「検証」だ、という考えだ。エージェントは間抜けなことをするから人が見張る、という話である。しかし検証こそエージェントが着実に上達している領域だ。テストと検証ループを与えれば、正しいかどうかの判定は機械のほうが安定する。

本当の理由は別にある。理解は「参加」するためのものだ。今回の変更を理解すれば、その理解が次の判断の材料になる。頭の中に概念の構造が積み上がっているからこそ次のアイデアが出てくるし、それが人の担当分だ。理解を飛ばすと、判定は続けられても提案ができなくなる。

この代償を指す言葉が認知的負債（cognitive debt）だ。ビクトリア大学の Margaret-Anne Storey 教授が提唱し、Simon Willison が広めた概念で、技術的負債と対になる。技術的負債はコードに溜まり、認知的負債は人に溜まる。前者は静的解析で見えるが、後者は見えないまま進み、ある日「自分のプロジェクトなのに自分が一番わかっていない」という形で請求書が来る。

良い解説はどんな順序で書かれるか

では diff の代わりに何を読むのか。Litt の問いはこうだ——このコード変更ひとつを自分に説明するためだけに、チームを1年かけてカリキュラムを作らせたら、その成果物はどんな形になるだろうか。

その答えが explain-diff の作るドキュメントだ。構造は四つの塊で、順序そのものが教育学になっている。良い数学教師がやることと同じで、細部を投げる前にまず感覚をつかませる。

発表では実例が出てくる。禅の庭を描くゲームで、視点を真上から見下ろす方式から斜め見下ろし方式に変えた変更だ。ドキュメントは何が変わったかから始めない。使っているゲームエンジンと座標系がどうなっているかから敷いていく。すでに知っている人は飛ばしてよい、という但し書き付きで。

次が直感だ。「このコミットの目的は、2D の描画テクニックだけで庭を立体的に感じさせることだ」。よく書けたコミットメッセージをもう一段掘り下げた文章に近い。コードを突きつける前に本質を渡す。

コードは三番目。しかもファイル一覧の順ではなく、理解できる順に並べ替え、ファイルごとに何が起きるかを散文で先に述べてから出す。Litt はこれを literate code diff と呼び、印刷してカフェで読むと言う。IDE に張り付いていなければならなかった作業が、教科書を読む行為になったわけだ。

スキルとは何で、どこに置くのか

explain-diff はプログラムではなく、スキル（skill）ファイル1枚だ。通常の意味でインストールするものが無いので、初めて聞く人はかえって戸惑う。

Claude Code におけるスキルとは、「こういう状況ではこうしてほしい」を書いた markdown 文書だ。決められた場所に置けば、必要なときに自動で呼ばれる。場所は二つ——マシン全体で使うならホームの ~/.claude/skills/、特定のプロジェクトだけなら、そのリポジトリの .claude/skills/ の中だ。

ファイル名は必ず SKILL.md で、フォルダ名がそのままスキル名になる。つまり ~/.claude/skills/explain-diff-html/SKILL.md というパス自体が登録手続きだ。設定ファイルも再ビルドも要らない。

文書の先頭には短いフロントマターが付く。name はスキル名、description は「いつ使うか」だ。この description が肝心で、名前で呼ばなくても、今の状況がその説明に合えばエージェントが自分でこの文書を読む。explain-diff-html の説明は「コード変更・diff・ブランチ・PR について豊かな解説を求められたときに使う」となっている。

フロントマターの下はすべて人間の言葉だ。どの節を入れるか、どんな文体で書くか、図はどう描くか、ファイルはどこに保存するか。コードは一行も無い。だから後で触れる「自分のチーム向けの改造」が、ただの文書編集で済む。

---
name: explain-diff-html
description: Use when the user asks for a rich explanation of a code change, diff, branch, or PR. Produces HTML output.
---

インストール——コマンド2行

元は Geoffrey Litt が公開した gist ひとつで、中にファイルが二つある。explain-diff-html.md は HTML 1枚を作り、explain-diff-notion.md は Notion ページを作る。片方だけでも両方でもよい。両方入れておけば、要求に合うほうが自動で呼ばれる。

インストールはフォルダを作り、その中に SKILL.md という名前でファイルを落とすだけだ。下のコマンドをそのままターミナルに貼ればいい。管理者権限もパッケージ管理も不要だ。

ここでよくある失敗がファイル名だ。explain-diff-html.md のまま保存すると認識されない。フォルダ名がスキル名で、ファイル名は常に SKILL.md である。-o の後ろのパスがそういう形になっているのはそのためだ。

ちゃんと入ったかはフロントマターを表示すればすぐ分かる。name の行が見えれば成功だ。すでに開いていた Claude Code のセッションには新しいスキルがまだ見えないことがあるので、セッションを開き直して使うほうが確実だ。

mkdir -p ~/.claude/skills/explain-diff-html
curl -sL https://gist.githubusercontent.com/geoffreylitt/a29df1b5f9865506e8952488eac3d524/raw/explain-diff-html.md -o ~/.claude/skills/explain-diff-html/SKILL.md

# 確認 — name の行が見えればインストール済み
head -4 ~/.claude/skills/explain-diff-html/SKILL.md

mkdir -p ~/.claude/skills/explain-diff-notion
curl -sL https://gist.githubusercontent.com/geoffreylitt/a29df1b5f9865506e8952488eac3d524/raw/explain-diff-notion.md -o ~/.claude/skills/explain-diff-notion/SKILL.md

動かしてみる——何と言えばいいか

入れてしまえば覚えるコマンドは無い。リポジトリの中で Claude Code を開き、普通の言葉で「このブランチが main と比べてどう変わったか説明して」と頼めばいい。スキルの description がこの状況に合うので、エージェントが自分でその文書に従う。

説明の対象は三通りで指定できる。ブランチ全体（main との差分）、特定のコミット範囲、まだコミットしていない作業ツリーの変更だ。スキルには diff だけでなく周辺のコードも広く読むよう書かれており、背景節の質はそこで決まる。

成果物は自己完結型の HTML ファイル1枚だ。CSS も JavaScript も中に入っているので、ブラウザで開くだけでクイズまで動く。タブに分けず1枚の長いページで、先頭に目次が付く。スマートフォンでも読めるよう基本的なレスポンシブ対応が入る。

保存場所はスキルに固定されている。リポジトリの外の共通の場所に置き、ファイル名は必ずその日の日付で始める。たとえば /tmp/2026-08-01-explanation-isometric-view.html のような形だ。理由は二つ——時系列に並び、バージョン管理に紛れ込まない。

作った文書を開くのはコマンド1行。macOS なら open、Linux なら xdg-open、Windows なら start だ。

このブランチが main と比べてどう変わったか説明して

# ほかの指定の仕方
直近3コミットを説明して
まだコミットしていない変更を説明して

# 今日作られた解説ドキュメントを探す
ls -t /tmp/$(date +%F)-explanation-*.html

# 開く（macOS）
open /tmp/2026-08-01-explanation-isometric-view.html

クイズを速度調整器として使う

文書の末尾に付く5問がこのスキルの中核だ。難易度の指示が具体的で、中程度、引っかけは禁止、ただし変更の実質を理解していなければ解けない水準、とある。選択式で、答えを選ぶとその場で正誤と解説が出る。

なぜクイズなのか。Litt は Andy Matuschak の「Books don't work」を根拠に挙げる。本を読み終えたのに理解していない、という事実を自分で気づくのは極めて難しい、という主張だ。Matuschak と Michael Nielsen はそこで、エッセイの本文中に間隔反復のクイズを埋め込み、理解せずには通り抜けられない文章を作った。

同じ装置をコードレビューに移したのがこれだ。Litt が自分に課したルールは一文である——クイズに通らなければ、エージェントが書いたコードをチームにレビュー依頼として出さない。子どもじみて見えるが、実際によく引っかかるという。読んだつもりの PR で同僚に最も基本的な質問をされ、答えられなかった経験が出発点だった。

彼はこれを速度調整器と呼ぶ。AI 関連の道具はどれも、もっと速くという方向に圧をかける。正確さの速度だけ上げて理解の速度を上げなければ、その差の分だけ認知的負債が溜まる。クイズは二つの速度を無理やり結び直す装置だ。

チームに持ち込むなら個人の掟として置くほうがよい。人がクイズに通ったかどうかを CI でゲートにはできない。代わりに「レビュー依頼に解説ドキュメントのリンクを添える」あたりから始めると、文書を作る過程で自然とクイズを解くことになる。

Notion 版は何が違うか

explain-diff-notion.md は成果物をファイルではなく Notion ページとして作る。内容の構造（背景・直感・コード・クイズ）は同じで、出力先だけが分かれる。

違いは協働だ。ファイルは自分のマシンにあるが、Notion ページはチームで一緒に見るものになる。段落にコメントを付けられるので、解説ドキュメント自体が議論の場になる。エージェントが立てた計画に、同僚が該当行でそのまま異論を残せる。Litt が Notion で働いているからでもあるが、この派生版の狙いは理解を個人ではなくチーム単位で積むことにある。

前提が一つ付く。Notion MCP がつながっていることだ。MCP はエージェントが外部サービスに直接話しかけられるようにする標準的な接続方式で、Notion のコネクタを入れておけばエージェントがページを作って URL を返す。接続が無ければこのスキルは何も作れない。

クイズの表現も違う。HTML 版は JavaScript でクリックを判定するが、Notion にはその手の操作が無いのでトグルブロックを使う。選択肢を一つずつ開くと、それがなぜ正しい／間違いなのかの説明が出る。選ぶまで答えが見えない点で役割は同じだ。

付け加えると、実演では Notion ページの中にインタラクティブなシミュレーションまで入っていた。座標をドラッグして、今回の変更が何を変えたのかを手で確かめる形だ。ただし Litt 自身が釘を刺している——インタラクションは松葉杖になりやすく、雑なコンテンツにもなりやすい。静止画では届かないところだけを、慎重に作る。

自分のチーム向けの改造と、残る二つの技法

スキルファイルはただの markdown なので、そのまま書き換えればいい。実際に触ることになるのは四か所だ。第一に節の構成——自分のチームが毎回聞くこと（ロールバック計画、性能への影響など）を節として足す。第二にクイズの問数と難易度。第三に保存パスとファイル名の規則で、社内の共有フォルダに溜めたいならここだけ変える。第四に文体の指示だ。原文には Martin Kleppmann の明晰さで書けとあるが、自分のチームが好む文書を代わりに指名してもよい。

逆に触らないほうがよい箇所もある。原文は図を ASCII で描くことを禁じて HTML で描けと明記し、コードブロックは pre タグを使うこと、どうしても自前でスタイルした div を使うなら white-space を pre-wrap にして保存前に各ブロックを確認せよ、とまで書いている。実際によく壊れる箇所なので、この手すりは残しておくほうがよい。

同じ発表には技法があと二つ出てくる。一つはマイクロワールドだ。理解を助けるためだけに存在し、出荷しないソフトウェアをエージェントに作らせる。Litt は自作の Prolog インタプリタの内部動作をタイムラインでスクラブして見るデバッガを作り、個人サイトを別フレームワークへ移すときは、移行をボタンで一歩ずつ進める小さなゲームを作って自分で押しながら移した。スクリプトに任せれば結果は同じだが、感覚が残らないからだ。

もう一つは共有スペースだ。人とエージェントが同じスレッドで会話し、議論がドキュメントのコメントとして残り、コーディングエージェントをチームの文書空間に招き入れる。各自が自分のエージェントと一対一で話していると、チームの理解が割れるという問題意識である。

三つの技法に共通する動きは一つだ。エージェントにコードを書かせるところで止めず、そのコードを理解するための道具を書かせる。コードが安くなったのだから、理解のための使い捨ての道具も安くなった。ならばその力は、理解を減らす方向ではなく増やす方向に使える——それがこの発表の結論だ。