ai-debt-detector

AI 負債検出器

概要

AI エージェントはハッピーパスを通るコードを生成しますが、負債を隠します。エラーハンドリングの欠如、孤立したリソース、無視された失敗モード、幻覚パッケージ、静かなアーキテクチャのドリフトなどです。このスキルは、AI エージェントが間違える正確なパターンに対して的を絞った監査を強制します。

使用するタイミング

• AI によるコード生成セッションの後（20 行以上生成された場合）
• AI が生成した PR をマージする前
• コードは動くが、何かおかしいと感じるとき
• 負債が最も速く蓄積するバイブコーディングスプリントの後
• エージェントが検証を示さずに完了したと主張するとき

プロセス

コード生成後、これらの AI 特有の負債パターンをスキャンします：

1. 失敗モード - これが失敗したとき何が起きるか？

   • ネットワークタイムアウト？ディスクフル？権限拒否？null 入力？
   • try/catch はあるか？特定のエラーを捕捉しているか、それともすべてを飲み込んでいるか？
   • 失敗時にリソースはクリーンアップされるか？（ストリームのクローズ、接続の返却、一時ファイルの削除）

2. 孤立 - 作成されるが決してクリーンアップされないものは何か？

   • 一時ファイル、イベントリスナー、インターバル、サブスクリプション、接続
   • すべての open/create に対応する cleanup/dispose/close 呼び出しがあるか？
   • React では：すべての addEventListener にクリーンアップ内の removeEventListener があるか？

3. エッジケース - どの入力がこれを壊すか？

   • 空の配列/文字列？null/undefined？数 MB の入力？Unicode？同時呼び出し？
   • コードはハッピーパスを前提としているか？（AI はほぼ常にそうしている）

4. 幻覚の依存関係 - すべてのインポートは実際に存在するか？

   • すべてのパッケージは package.json/requirements.txt にあるか？
   • API メソッドは実在するか？（AI は存在しないもっともらしいメソッドを発明する）
   • このライブラリの最新バージョンはまだこの関数をエクスポートしているか？

5. アーキテクチャのドリフト - これはプロジェクトのパターンに一致しているか？

   • 既存のコードと同じエラーハンドリングスタイルか？
   • プロジェクトの確立されたユーティリティを使用しているか（再発明していないか）？
   • ファイル構造の慣習に従っているか？

危険信号（停止して即座に修正）

• catch (e) {} または catch (e) { console.log(e) } - 飲み込まれたエラー
• リソースが開かれたのに finally ブロックがない
• // TODO: handle error - AI の先送り方法
• プロジェクトに存在しないパスからのインポート
• タイムアウトは設定されているが、タイムアウト時の abort/cleanup がない
• データベース接続が開かれたがプールに返却されない

よくある間違い

• コンパイルが通ることは正しさを意味すると信頼する（コンパイルは構文をチェックし、ロジックはチェックしない）
• AI が生成しなかったものを確認せずに差分のみをレビューする（欠落したエラーパス）
• AI が正しいライブラリバージョンを使用したと仮定する（しばしば非推奨の API を使用する）
• ガベージコレクションが処理するので孤立チェックをスキップする（接続、リスナー、タイマーには処理しない）

これが存在する理由

AI エージェントは「正しく見える」と「ハッピーパスを通る」ために体系的に最適化します。彼らは失敗モード、孤立リソースを見逃し、手書きのコードよりも著しく高い割合で依存関係を幻覚します。このスキルは、それらの特定の盲点に対する監査を強制します。