技術的負債はコードの中に溜まる。認知的負債は頭の中に溜まる。では、「なぜこの実装にしたか」という理由そのものが記録されていない状態——これをAddy Osmaniは"意図の負債"と呼ぶ。エージェントに仕事を任せるほど、この負債だけは効いてくる。
"意図の負債"という概念の中身と、なぜエージェント時代に唯一肩代わりできない負債になるのかの理由。そして今日から実行できる、意図を書き残す最小限の習慣。
技術的負債という言葉はもう馴染み深い。粗いコードや後回しにした設計判断が、コードそのものの中に残る。認知的負債はそれとは別の話で、自分の頭の中にある——コードが何をしているかの理解が、実際のコードから少しずつずれていく状態のことだ。
Addy Osmaniが指摘するのは、この2つとは別にもう1種類あるという点だ。意図の負債——目標・制約・「なぜこの形にしたか」という理由。これは書かれたことのない成果物の中に溜まる。運が良ければチームのドキュメントや議論に断片的に残っているが、たいていは不完全なままだ。
粗いコードの整理、テストの追加、リファクタリング——これらはエージェントが得意とする作業そのもの。人間がやるより速く片付けられる場面も多い。
「なぜこの実装を選んだか」が記録されていなければ、エージェントはコードから逆算で推測するしかない。推測は当たることもあるが、外れれば見当違いの変更を積み重ねる。
これが今回の核心。エージェントに任せる作業が増えるほど、コードそのものの負債は減っていく。だが「なぜそうしたか」を書き残す責任だけは、人間の側に残り続ける。むしろ、任せる範囲が広がるほどこの負債のコストは上がる。
大掛かりな設計文書である必要はない。むしろ小さく、その場で残すのが続くコツだ。
大掛かりな仕組みを整備しようとすると、たいてい続かない。理想の設計文書を書こうとする前に、今この瞬間の判断を1行だけ書き残す方を優先した方がいい。意図の負債は完璧な記録を目指すと挫折するが、断片の積み重ねなら誰でも続けられる。
意図の負債は、このポートフォリオの運用自体でも実際に起きた。ある時、進行中の作業ディレクトリに、別セッションが作った成果物が置かれていたことがある。それが「なぜそこにあるか」「誰が何のために置いたか」を記録した場所がどこにもなかった。
気づけたのは、ファイルのタイムスタンプにたまたま目が留まったからであり、検知できるように設計されていたわけではない。詳しい引き継ぎ設計は「ClaudeとCodexを二人体制で運用する｜引き継ぎ窓口はMarkdown1枚でいい」に書いた。これはコードの負債でも認知の負債でもなく、「なぜこの変更をしたか」を書き残す場所を、その時点で誰も決めていなかった、という意図の負債そのものだった。
ここが核心。この一件のあと、進行管理の窓口となるファイルへ「done / in-flight / waiting-user / next」の4行だけを毎回追記するルールに変えた。意図の負債は、完璧な設計書ではなく「今何をしていて、なぜか」を4行で書く習慣で防げる。
限界を明記する: 「発見がどれだけ遅れたか」を分単位で計測した記録は残っていない。確かな事実は発見の手段が設計された仕組みではなく偶然だったという1点であり、この記事では存在しない時間の数字を作らない。
大掛かりな設計書は続かない。判断のたびにこの5項目だけを、コミットメッセージやCLAUDE.mdの1行、journal.mdの備考欄に書き残す。
# 判断記録テンプレート（1エントリ=5行）
日付: 2026-07-XX
決めたこと: <具体的な選択>
検討した代替案: <採用しなかった案>
却下理由: <なぜ代替案を選ばなかったか>
見直し条件: <何が変わったら再検討するか>この記事を書いている当日の実例をそのまま記録すると、こうなる。
日付: 2026-07-25
決めたこと: 次に書くFLOW記事として「自然言語E2Eテスト」の事例を選んだ
検討した代替案: 「AIコードレビューの実証研究」を組み合わせた記事案
却下理由: 出典の一部（arXiv論文）のIDが不完全で、検証可能なURLとして提示できなかったため
見直し条件: 正しいarXiv IDが確認できたら再候補に戻す5項目のうち特に効くのは「却下理由」だ。採用した案の説明は後からコードを読めば大半が推測できるが、選ばなかった理由だけはどこにも残らず、書かなければ二度と分からなくなる。