The Engineering of Intent 第39章:印象主義的スキャニング──コードを形で読むためのビジュアル・ヒューリスティック

本記事は、私の著書The Engineering of Intent(英語版)を1章ずつ読み解くシリーズの第39回です。前回の記事では、マルチエージェントのフリートを統治する方法を取り上げました。第39章では、ひとつのスキルに立ち返ります──第2章「認知負荷と物質的離脱」で紹介したスキルです──そして、それを実践で使える形にします。コードの視覚的な形のチートシートです。


中身より先に、形が大事

第2章「認知負荷と物質的離脱」では、印象主義的スキャニングを紹介しました。経験を積んだエンジニアは無意識にそれを行っていますが、ジュニアはそれがスキルだということすら知らないことがよくあります。第39章では、その暗黙知を明示します。形は、覆すのが難しい決定と相関しているのです。

縦に長く幅の狭い関数は、たいていネストの深い関数です──設計されたのではなく、時間とともに積み重なった条件ロジックです。横に広く平らな関数は、たいてい共通のロジックをくくり出すのではなく、ケースを追加することで膨らんできた関数です。こうした相関は法則ではなく、事前確率です──それでも、最初の1行を読む前に問題を捕まえられるほどには強く当てはまります。そしてそれは、人間が書いたコードよりもAIが生成したコードにいっそう強く当てはまります。エージェントは局所的な正しさに最適化し、全体の形が見えていないことが多いからです。


6つの形と、その意味

  1. 横に広く平ら(Wide and Flat)。 同じインデントに兄弟の分岐がずらりと並ぶ形です。抽象化ではなく、列挙によって膨らんできました。対策:ステートマシン、ルックアップテーブル、またはポリモーフィックなディスパッチ。
  2. 深いネスト(Deep Nesting)。 5〜7段のインデント。書き手が立ち止まって、早期リターンやヘルパーを抽出しなかった形です。エージェントの失敗モード第1位。対策:まずガード節。それでも3段を超えて残るものはヘルパーに。
  3. 雑多なインポート(High Import Churn)。 ファイル冒頭のインポートが、無関係なドメインにまたがっている形です。アーキテクチャのドリフトであり、このファイルはゴミ捨て場になっています。対策:責務ごとのモジュールへの分解を提案する。
  4. 細長いパイプライン(Long Thin Pipeline)。 step1、step2、intermediateといった変数がたくさんある、長い直線的な関数です。セクション見出しのようなコメントは、生まれたがっている関数です。対策:各ステップにヘルパーとして名前を付ける。トップレベルは短いオーケストレーションになります。
  5. ギザギザの縁(Jagged Edges)。 行の長さがばらばらな形です。フォーマッターが無視されたか、設定が間違っています。対策:フォーマッターを実行し、そのうえで、その下から現れる本当の不整合を探す。
  6. 不自然な均一さ(Suspicious Uniformity)。 骨格がまったく同じで、細部だけが違う兄弟ファイルが15個。パターンの変更に弱い、機械的な足場づくりです。対策:何が違うのかを表にし、テンプレートに抽出するか、重複を受け入れるかを決める。
💡 チートシート: 横に広く平ら → 列挙 → ディスパッチ。深いネスト → ヘルパーの欠如 → 平らにして抽出。雑多なインポート → ドリフト → 分解。細長い → 抽出されていないステップ → ヘルパーに名前を付ける。ギザギザ → フォーマッター → 実行する。不自然な均一さ → 足場づくり → パラメータ化するか、受け入れる。6つのカテゴリー。1ファイルあたり5秒。1週間、レビューするすべてのプルリクエストで。

それぞれの形の内側にある危険信号

本章では、それぞれのシルエットの内側で注意すべき兆候をカタログにしています。

  • 横に広く平ら: 名前がひとつ違うだけで同じ構造を持つ分岐。増殖していくブールフラグ(3個で8通り、5個で32通り、8個になるとその空間の1%未満しかテストしていない)。
  • 深いネスト: try/catchの中のifの中のループの中のtry/catch。失敗する処理から6段も離れた場所にあるエラー処理。
  • 雑多なインポート: レイヤーをまたぐインポート。遅延バインディングで断ち切られた循環インポート。ちょうど1回しか使われないシンボルのインポート。
  • 細長いパイプライン: step1、transformed、finalといった名前の変数。関数の境界がないまま80行を超える長さ。
  • ギザギザの縁: 異なるスタイルの時代のインポートの混在(commonjs + esm)。文字列フォーマットの混在(f-strings + 連結 + テンプレートリテラル)。
  • 不自然な均一さ: ファイルをまたいで一字一句同じコメント。テスト名と期待値だけが違うテストファイル(書かれるのを待っているパラメータ化テストです)。

「これを印刷して、モニターに貼ってください。1週間、すべてのプルリクエストのファイル一覧を、この6つのカテゴリーだけを使ってスキャンしてください。金曜日には、1ファイルあたり5秒で形のレベルの問題を捕まえられるようになっています。2か月目には、考えなくてもできるようになっているでしょう。」

⚠ 本章が教えようとしているスキル: あなたのエージェントは、局所的には問題なく、全体としては間違っている形を出荷してきます。最初にそれに気づくのはあなたです──ただし、目を鍛えていればの話です。このチートシートを使った3か月間の意識的なスキャンは、どれだけツールをアップグレードするよりも価値があります。

次回 ── 第40章「De-Vibingプロトコル──本番に向けた安定化スプリント」 本書の最終章は、オートコンプリートの罠(autocomplete trap)に対する処方箋です──Vibeだけで速く作ったビルドが飛ばした仕様、テスト、型、アーキテクチャのドキュメントを、さかのぼって作り出す2週間の安定化スプリントです。


📖 さらに詳しく知りたい方へ

本章では、6つの形それぞれについて、視覚的な特徴、危険信号、そしてその形に名前を付けたあとでエージェントに機械的にリファクタリングさせるための具体的なプロンプトを解説しています。さらに、印刷して貼っておける1ページのチートシートも収録しています。

The Engineering of Intent をAmazonで購入する →(英語版)

2026-05-25

下田 昌平

開発に関するインプットをアウトプットしています。