Pi に「理解負債」を解消する workflow を追加した話

TL;DR

最近、AI coding agent の Pi を使っている。 Pi は prompt や extension を自分用に追加できるので、AI 開発で溜まりやすい 理解負債 を解消する workflow を作ることにした。

ここでいう理解負債とは、AI に説明してもらった直後は「わかった気がする」けれど、あとから自分では説明できない状態のこと。

今回作ったのは、理解負債を見つけて終わりにするのではなく、次の流れで解消まで進める仕組み。

会話から理解不足を検知する
  ↓
理解負債として記録する
  ↓
確認質問をする
  ↓
正答なら1段階だけ昇格する
  ↓
不正答なら、どこで詰まったかを残す
  ↓
次回、その失敗ポイントから復習する

背景

Pi は、AI coding agent を自分の開発スタイルに合わせて拡張できるツール。自分用の prompt を追加したり、作業ログや memory の運用ルールを決めたり、extension で独自の workflow を組み込んだりできる。

AI エージェントを使っていると、コードリーディングや実装方針の相談がかなり速く進む。一方で、説明を受ける量が増えるほど、次のような状態も起きやすくなる。

説明を聞いた直後は理解した気がする
でも、あとから同じ内容を自分で説明できない
コードの入力から出力までの流れを追えない
なぜその設計にしたのか言語化できない

この「理解したつもりだけど、まだ自分のものになっていない状態」を、この記事では 理解負債 と呼ぶ。

問題

AI エージェントを使うと、開発スピードはかなり上がる。実装方針を相談し、コードを読んでもらい、修正案を出してもらうことで、成果物は以前より速く完成する。

ただ、その速さの裏で、自分の理解が追いつかないことがある。成果物は動いている。でも、その中身を自分が説明できない。この状態を放置すると、あとから保守・修正するときに ブラックボックス化した負債 になる。

成果物は完成するが、中身がブラックボックスになる

AI が生成・提案したコードは、その場では正しく動いているように見える。しかし、あとから同じ処理を自分で説明しようとすると、入力と出力の流れや、途中のデータ変換を説明できないことがある。

つまり、成果物が完成していることと、自分がその中身を理解していることは別だった。

理解が曖昧なまま次の作業へ進んでしまう

開発中は、実装・レビュー・修正の流れが優先される。そのため、「ここは少し曖昧だった」という箇所があっても、作業が進むうちに埋もれやすい。

特に commit 前や作業完了時に思い出せないと、理解が曖昧なまま変更だけが残る。その結果、未来の自分がコードを直すときに「なぜこうなっているのか」がわからなくなる。

方針

そこで、理解負債を解消するための workflow を設計することにした。

Pi 側では、custom tool・自作 prompt・memory の運用ルールを組み合わせて、次の役割に分けて考えた。

役割	位置づけ	何をするか
会話での検知	AI との対話ルール	ユーザーが説明できなかった箇所、誤解した箇所を AI が拾う
`understanding_debt`	custom tool	理解負債の一覧・追加・更新を管理する
`/debt-check`	自作 prompt	1つの理解負債に対して確認質問を出す
memory tag	memory の運用ルール	失敗・理解済みの記録を次回の復習に使う
commit 前の通知	作業区切りの check	作業の区切りで、残っている理解負債に気づけるようにする

理解負債そのものは、次の3段階で扱う。

Lv	状態	目標
Lv1	まだ理解できていない	まず説明できるようにする
Lv2	説明できる	コードの流れを追えるようにする
Lv3	コードを読める	実装・レビューで使える状態

重要なのは、正答しても一気に完了にしないこと。 Lv1 から Lv3 に飛ばすのではなく、正答したら 1段階だけ昇格 する。

実装・運用イメージ

会話から理解不足を検知する

この仕組みのポイントは、コードだけではなく ユーザーとの会話 を見ること。

例えば、AI がある処理の流れを説明したあとに、確認質問をする。

AI: この値は、どこで別の形式に変換されて、最後にどの処理へ渡されますか？
ユーザー: たぶん、そのまま使われると思います
AI: 「値が途中で変換される箇所」と「最終的な受け渡し先」がまだ曖昧そう

この場合、AI は「この概念がわかっていない」と雑に記録するのではなく、どこで詰まったかを具体的に残す。

#understanding-fail [[値の変換と受け渡し]]
入力値が途中で別の形式に変換され、その変換後の値が次の処理へ渡される流れを説明できなかった。

こうしておくと、次回は同じ説明を最初から繰り返すのではなく、「どこで値が変換されるのか」「変換後にどこへ渡されるのか」だけを重点的に復習できる。

逆に、ユーザーが内部ロジックやデータの流れを説明できた場合は、理解済みとして記録する。

#understanding-learned [[設計判断の理由]]
すぐに実装せず、先に仕様や影響範囲を整理する理由を説明できた。

つまり、AI が勝手に「理解した」と決めるのではなく、確認質問と回答を材料にして判定する。

`/debt-check` では1件だけ確認する

ここでは、自作 prompt として /debt-check を用意した。理解負債の確認では、対象を1つだけ選ぶ。複数を同時に確認しない。

/debt-check
  ↓
Lv1 または Lv2 の項目を1つ選ぶ
  ↓
確認質問を1つ出す
  ↓
ユーザーの回答を待つ

一度に複数聞くと、どれを理解できていて、どれを理解できていないのかが曖昧になる。そのため、確認は1回に1テーマだけにした。

commit 前に理解負債を思い出せるようにする

もう1つ大事なのが、作業の区切りで通知すること。

理解負債は、実装中は後回しになりやすい。特に commit 前は「この変更を残す前に、理解が曖昧なままの箇所がないか」を確認するよいタイミングになる。

そこで、理解負債が残っている場合は、commit 前や作業完了前に気づけるようにする。例えば、agent の応答や作業完了前の check で「未解消の理解負債があります」と表示し、必要なら /debt-check に進める。

実装する
  ↓
レビューする
  ↓
commit 前に理解負債を確認する
  ↓
残っていれば通知する
  ↓
必要なら /debt-check で1つだけ確認する

ポイントは、commit を必ず止めることではなく、理解が曖昧なまま作業を閉じようとしていることに気づける ようにすること。

これにより、理解負債が「あとで見るリスト」ではなく、日々の開発 workflow の中で自然に戻ってくる。

正答時は1段階だけ昇格する

Lv1: 未理解
  ↓ 正答
Lv2: 説明できる
  ↓ コードの流れも説明できる
Lv3: コードを読める

このように段階を分けると、「説明はできるが、まだコードは追えない」という中間状態を扱える。

不正答時は失敗ポイントを残す

不正答の場合は、単に「間違い」とは扱わない。何を誤解したのか、どのデータ変換を追えなかったのかを残す。

これにより、次回の復習対象が明確になる。

理解済みは慎重に記録する

正答した場合も、何でも understanding-learned にするわけではない。

記録するのは、次のような場合だけ。

内部ロジックを説明できた
入力から出力までのデータ変換を説明できた
なぜその設計にしたか説明できた
edge case や失敗条件を説明できた

「なんとなくわかった」だけでは理解済みにしない。

Before / After

Before

AI に説明してもらう
  ↓
なんとなくわかった気がする
  ↓
中身を説明できないまま作業が進む
  ↓
あとから見たときにブラックボックスになる

After

AI に説明してもらう
  ↓
AI が確認質問をする
  ↓
回答から曖昧な点を検知する
  ↓
必要なものだけ理解負債にする
  ↓
commit 前や作業完了前に残っている負債を通知する
  ↓
/debt-check で1つ確認する
  ↓
正答なら1段階昇格
  ↓
不正答なら失敗ポイントを記録
  ↓
次回、その失敗ポイントから再確認

学び

Pi のように自分で workflow を足せる AI coding agent では、コード生成やレビューだけでなく、自分の学習 loop も拡張できる。

理解負債は、単なるメモではなく小さな issue に近い。 Issue に title だけあっても、close 条件がなければ進まない。

同じように、理解負債にも次の情報が必要になる。

何がわかっていないか
どの状態になれば解消とみなすか
どう確認するか
間違えた場合、何を次回復習するか

つまり、理解負債管理で大事なのは「見つけること」だけではなく、「解消までの導線」だった。

まとめ

AI エージェントとの開発では、説明を受ける機会が増えるほど「わかった気がする」状態も増えやすい。

だからこそ、理解負債を解消する workflow が必要になる。

会話から検知する
理解負債として扱う
作業の区切りで通知する
確認する
昇格する
失敗を残す
次回復習する

この一連の流れを Pi に組み込むことで、理解負債を日々の開発 workflow の中で継続的に解消できるようになる。