comprehension debt（理解の負債）の予防は、判断の自動化ではなく可視化から生まれる

キッカケクリエイションが2026年2月に実施した調査によると、コードレビューを担当するエンジニア322名のうち86.3%が「AIコード生成によってレビューの負担が増えた」と回答している。さらに踏み込んだ数字がある。コードを提出した本人が、その内容を説明できなかったケースが49.5%あった(出典)。

書いた人間が説明できないコードが、半数近く存在する。これは技術的負債とは別種の問題で、comprehension debtと呼ばれている。

comprehension debtとは何か

comprehension debtという語を明確に定義したのは、nihonbuson氏がブログで書いた「AIコーディングツール時代のQA活動」という記事だ(出典)。この記事では、AI生成コードが抱える負債を二つに分けている。**comprehension debt（理解の負債）は、コードが「どう動くか」についての知見が欠けている状態を指す。もう一つのintent debt（意図の負債）**は、「なぜ作られたか」「どのトレードオフを許容したか」という判断そのものが失われる状態を指す。

技術的負債とcomprehension debtの違いは、負債の在り処にある。技術的負債は書いたコードの中に存在する。急ぎで書いた分岐、コピペで増えた重複、後回しにしたエラー処理。これらはコードを読めば見つかり、リファクタリングという形で有限のコストで返済できる。

comprehension debtはコードの中にはない。理解している人間がいない、という状態そのものが負債になる。だからコードの品質とは独立に発生する。整った設計で書かれたきれいなコードでも、書いた本人が異動し、レビュアーが差分だけを見て通し、誰もその判断を再構成できなくなれば、comprehension debtは静かに積み上がっている。冒頭の49.5%という数字は、この負債がマージされる前、コードが生成された瞬間にすでに発生していることを示している。

「記録する」運用がなぜ続かないか

comprehension debtへの対策として、まず思いつくのは「PRの説明欄に、なぜそう実装したかを書く」という運用だ。実際、Design Docの書き方として「守るもの・許容するもの・理由・別案を採らなかった理由」の4項目を挙げているブログもある(出典)。フォーマットとしては過不足がない。

それでも、こうした運用は長続きしないことが多い。理由は、書く人が気を抜いているからではなく、コストと便益を負う人が別々だからだ。判断を書き残すコストを払うのは、今まさに手を動かしている本人で、締め切りに追われている瞬間である。その記録から便益を得るのは、半年後にその変更に触れる別の誰か、あるいは異動後の自分自身になる。今日の自分が、まだ会ったことのない未来の誰かのために時間を使う構造は、締め切りの圧力の前ではまず削られる。

フォーマットがどれだけ整っていても、それが「書いても書かなくても、レビューは同じように通る」ものである限り、この構造は変わらない。記録するかどうかを本人の裁量に委ねている限り、記録は真っ先に省略される項目になる。

自動化と可視化は何が違うのか

この構造を放置したまま開発を高速化すると、comprehension debtはむしろ深まる。ある社内テックブログでは、全PRの83%をAIレビューだけでマージしていると報告している(出典)。スループットを最大化する設計として筋が通っており、批判すべき事例ではない。ただし、これは自動化がどの変数を最適化しているかを示す好例でもある。人間がレビューに費やしていた時間そのものを削っているので、コードが動くようになる速度は上がるが、誰かがその変更を理解する機会は代わりに減る。

自動化は「判断を代わりに下す」ことを目的にしたツール群だ。判断そのものはAIやルールが下し、人間はその結果を追認するか無視する。判断が下される瞬間から、それを下した根拠は誰の頭にも残らない。コードに変換された結果だけが残る。

可視化は逆の方向を向く。判断を代わりに下すのではなく、判断が下された事実とその理由を、コードから切り離せない形で記録に残す。ツールは決めない。決めた内容を、後から読める形にする。この違いが効くのは、半年後に同じコードへ触れる人が、diffだけから判断を再構成する必要があるか、それとも記録された判断を引き継げるかの差になるからだ。diffからの再構成は、書いた本人の頭の中にあった前提を推測する作業であり、推測が外れれば静かに間違った理解が積み上がる。

摩擦をどう設計するか

「記録する運用」が続かない理由は、記録することとレビューが通ることが無関係だからだった。ここから導かれる対策は一つしかない。記録がなければレビューが通らない、という制約を先に作ることだ。

この必要性を、Parry自身の開発中に痛感した実例がある。7月5日、リポジトリの内部識別子をユーザー単位で作り直す移行を行った。このとき、既存データそのものを新しい識別子側へ移すかどうかという判断があったが、その判断の理由はどこにも記録されなかった。1週間後の7月12日、別の機能として「未登録のリポジトリをドラッグ&ドロップで開くと自動的に作成する」処理を実装した。この処理は、新しい識別子の側だけを見て重複を判定していた。7月5日の移行が既存データを完全には移していなかったという事実を、7月12日に手を動かした側は知らなかったからだ。結果、既に存在するはずのリポジトリが「未登録」と誤判定され、空のリポジトリが新規作成されてしまった。重複判定の実装自体は書かれた通りに動いており、単体で見れば筋の通ったコードだった。欠けていたのは、7月5日の判断を7月12日の自分が引き継ぐ手段であり、それさえあれば重複判定の対象に旧識別子も含めるという一行の違いで済んだはずだった。復旧はGitの履歴を手動で統合することで済んだが、この移行漏れが他のリポジトリにも残っている可能性は、今も検証できていない。

このバグは、コードの品質の問題ではなく、判断が記録されなかったことの結果だった。摩擦設計が狙うのは、「もっと書くように促す」ことではなく、判断がどこかに残っていない限り、その先の操作を完了させない、という制約そのものを作ることだ。

Parryが解く問題

Parryは、レビューを通すために判断を書かせる摩擦を作るツールである。判断を自動化するツールではない。

この摩擦が、comprehension debtの蓄積を長期的にどこまで抑えられるかは、まだ検証できていない。今のところの根拠は、Parry自身の開発中に実際に起きた、この記事で書いたような実例の積み重ねであって、複数チームを対象にした比較検証ではない。判断を可視化する制約が、書く側の負担としてどこまで許容されるのかも、運用しながら確かめている途中にある。