AIで技術的負債を棚卸しするプロンプト｜根拠・優先度・改善案まで整理
このプロンプトは、コードや設計資料から技術的負債の候補を洗い出し、根拠・影響・優先度・次の一手まで整理するためのテンプレートです。既存システムを引き継いだ開発者、改修計画を立てるリーダー、レビューの観点をそろえたいチームに向いています。
重要なのは、AIに「悪いコードを探して」と頼まないことです。対象範囲と判定基準を渡し、推測と確認済みの事実を分けさせます。
この記事では、次の内容を扱います。
- コピペして使える棚卸し用プロンプト
- 入力時に変更する項目
- 曖昧な指示を改善する方法
- 結果をMarkdownやJSONで受け取る指定
- AIの指摘を改修チケットへ変える手順
このプロンプトで作るのは「修正案」ではなく「負債台帳」
最初の目的は、自動修正ではなく、レビュー可能な負債台帳を作ることです。
技術的負債には、重複コードだけでなく、テスト不足、古い依存関係、例外処理の不統一、責務の集中、ドキュメントとの食い違いなども含まれます。GitHubの公式ガイドでも、重複、テスト不足、古い依存関係、一貫しない実装パターン、レガシーコードが代表例として挙げられています。
ただし、コードを読んだだけでは判断できない事情もあります。複雑な分岐が業務要件として必要かもしれませんし、古いライブラリを互換性維持のために残している可能性もあります。
そこで、AIの出力を次の3種類に分けます。
- 確認済みの問題：入力されたコードや資料から根拠を示せる
- 負債の疑い：問題の可能性はあるが、追加確認が必要
- 対象外：材料不足で判断できない
ここがポイント: AIに結論だけを出させず、「どのファイルの何が根拠か」と「判断に足りない情報」を必ず書かせます。
コピペ用：技術的負債の棚卸しプロンプト
以下は、特定のサービスに依存しない汎用LLM向けテンプレートです。コードを直接渡せるチャット、リポジトリを参照できる開発支援ツール、ファイル添付に対応したAIで使えます。
あなたは、既存システムの保守性を評価するシニアソフトウェアエンジニアです。
以下の情報を基に、技術的負債の候補を棚卸ししてください。
## 目的
{例：次四半期の改修計画に入れる技術的負債を整理する}
## 対象範囲
- 対象ディレクトリ／ファイル：{例：src/orders/ と tests/orders/}
- 対象言語・フレームワーク：{例：Python 3.12、FastAPI、SQLAlchemy}
- 対象外：{例：自動生成コード、vendor、マイグレーション履歴}
## システムの前提
- 主な用途：{システムの用途}
- 重要な品質：{例：決済処理の正確性、障害時の復旧性}
- 現在困っていること：{例：注文機能の変更時に関連箇所を特定しにくい}
- チームの制約：{例：破壊的なAPI変更は不可、改修は1件2日以内を優先}
## 入力資料
{コード、ディレクトリ構成、設計資料、テスト結果、静的解析結果などを貼る}
## 確認する観点
1. 重複したロジック
2. 責務が集中した関数・クラス・モジュール
3. モジュール間の強い依存や循環依存
4. テスト不足、およびテストしにくい構造
5. 例外処理、ログ、入力検証の不統一
6. 古い依存関係や非推奨API
7. 設定値・認証情報・環境依存値の埋め込み
8. コメント、README、設計資料と実装の不一致
9. 性能、セキュリティ、運用上のリスク
## 判定ルール
- 入力資料で確認できた事実と推測を分ける
- 根拠として、可能な限りファイル名、関数名、該当箇所を示す
- 行番号が不明な場合は作らない
- 情報不足の項目は断定せず「要確認」とする
- コードの複雑さだけで負債と決めつけず、業務上必要な可能性も示す
- 同じ原因から生じる指摘は1件にまとめる
- 修正コードはまだ作らない
## 優先度
各候補を次の軸で1〜5点評価してください。
- 影響度：障害、変更コスト、開発速度への影響
- 発生可能性：問題が顕在化する可能性
- 修正容易性：小さい変更で改善できるほど高得点
- 根拠確度：入力資料による裏付けの強さ
優先度スコアは次で計算してください。
(影響度 × 発生可能性) + 修正容易性
## 出力形式
最初に全体所見を3点以内で示し、その後に候補を優先度順で並べてください。
各候補には次を含めます。
- ID
- タイトル
- 分類
- 状態（確認済み／要確認）
- 根拠
- 想定される影響
- 優先度スコアと各評価値
- 推奨する改善方針
- 改善時の注意点
- 追加で確認する質問
- チケット化するときの完了条件
最後に、次の3区分で着手案をまとめてください。
- 今すぐ確認する項目
- 小さく改善できる項目
- 設計判断が必要な項目
入力時に変える項目
精度を左右するのは、コード量よりも対象範囲と業務上の制約です。 一度にリポジトリ全体を渡すより、変更頻度の高い機能や障害の多い領域から始める方が、指摘を検証しやすくなります。
必ず変更する項目
{目的}：棚卸し後に何を決めるのか{対象ディレクトリ／ファイル}：AIが確認する境界{対象外}：生成物や外部ライブラリなど、評価しない範囲{システムの用途}：コードが担う業務{重要な品質}：正確性、速度、可用性、監査性など{現在困っていること}：変更が遅い、障害調査が難しい、といった症状{チームの制約}：互換性、工数、リリース時期など
固定しておきたい条件
次の条件は、指摘の暴走を抑えるために残しておきます。
- 事実と推測を分ける
- 存在しない行番号や計測値を作らない
- 同じ原因の指摘をまとめる
- 修正コードをすぐに生成しない
- 情報不足なら確認質問を出す
コード以外の資料も有効です。ディレクトリ構成、テスト結果、静的解析レポート、障害記録、設計上の制約を加えると、「見た目が古い」という表面的な評価から、改修判断に使える分析へ近づきます。
NG例と改善例
NG例：範囲も基準もない
このコードの技術的負債を全部見つけて、直し方を教えてください。
この指示では、「全部」の範囲が決まっていません。AIは一般的なベストプラクティスを並べやすく、重要な問題と好みの違いが混ざります。根拠のない工数や優先順位を出す可能性もあります。
改善例：対象、症状、出力を絞る
添付した注文確定処理と関連テストを確認してください。
目的は、注文ルールを追加するたびに修正箇所が増える原因を特定することです。
重複ロジック、責務の集中、モジュール間依存、テスト困難性に限定して分析してください。
各指摘には、根拠となるファイル名と関数名を付けてください。
入力だけで断定できない内容は「要確認」とし、確認質問を1件付けてください。
出力は、影響度、発生可能性、修正容易性を各1〜5点で評価した優先順位付きリストにしてください。
修正コードは生成しないでください。
改善点は明確です。
- 「注文確定処理と関連テスト」に対象を限定した
- 現場で起きている症状を示した
- 評価観点を4つに絞った
- 根拠の場所を必須にした
- 不明点を「要確認」へ分離した
- 修正より先に棚卸しを求めた
出力を安定させる3つの指定
形式、制約、確認手順を分けて書くと、AIの回答をレビューしやすくなります。
1. 1件ごとの項目を固定する
「詳しく説明して」では、指摘ごとに情報量がばらつきます。ID、根拠、影響、優先度、改善方針、完了条件を固定すれば、そのまま会議資料やバックログの下書きに転用できます。
特に「根拠」と「完了条件」は省かないでください。根拠は誤検出を見抜く材料になり、完了条件は「リファクタリングする」のような曖昧なチケットを防ぎます。
2. 優先度を単一の印象で決めさせない
深刻そうに見えるコードが、必ずしも最優先とは限りません。ほとんど変更されない内部ツールより、毎週変更する注文処理の小さな重複の方が、累積コストは大きい場合があります。
最低でも次を分けて評価します。
- 問題が起きたときの影響
- 問題が顕在化する可能性
- 改善に着手しやすいか
- 指摘を裏付ける情報が十分か
なお、プロンプト内の計算式はチームの判断をそろえるための例です。監査済みのリスク評価モデルではありません。重大なセキュリティ問題や法令対応は、合計点にかかわらず別枠で扱います。
3. AIの回答を検証する工程を入れる
AIの分析だけで負債を確定しないでください。GitHubのコード品質に関する説明でも、既知のアンチパターンを扱うルールベース分析と、ルール外の問題を探すAI分析は異なる役割として扱われています。
実務では、次の順で確認します。
- AIが示したファイルや関数が実在するか確認する
- 静的解析、テスト、依存関係スキャンの結果と照合する
- コード所有者や機能担当者に、意図的な設計かを確認する
- 小さな項目を1件選び、修正範囲と副作用を調べる
- 根拠が取れたものだけをバックログへ登録する
AIは探索範囲を広げる役です。最終判断は、コード、実行結果、運用事情を確認できる担当者が行います。
JSONで受け取りたい場合の追加指定
集計やチケット連携に使うなら、自由文ではなくJSONにします。基本テンプレートの「出力形式」を、次の指定に置き換えてください。
出力は次の構造を持つJSONのみにしてください。
説明文やMarkdownのコードフェンスは付けないでください。
{
"summary": ["全体所見"],
"items": [
{
"id": "TD-001",
"title": "短いタイトル",
"category": "duplication|dependency|testing|architecture|operations|security|documentation|other",
"status": "confirmed|needs_review",
"evidence": [
{
"file": "ファイルパス",
"symbol": "関数名またはクラス名",
"reason": "根拠"
}
],
"impact": "想定される影響",
"scores": {
"impact": 1,
"likelihood": 1,
"ease": 1,
"confidence": 1,
"priority": 2
},
"recommendation": "改善方針",
"cautions": ["注意点"],
"questions": ["追加確認事項"],
"done_when": ["完了条件"]
}
]
}
数値は1〜5の整数にしてください。
根拠がない項目を補完せず、該当情報がなければ空配列にしてください。
JSONは機械処理に向きますが、構文が正しくても分析内容が正しいとは限りません。取り込み前にスキーマ検証を行い、ファイルパスや評価値も確認します。
活用例：棚卸しから改修チケットへつなぐ
最初の分析結果をそのまま修正指示にせず、対象を1件だけ選んで二段階目のプロンプトへ渡します。
以下の技術的負債候補「{TD-ID}」を、改修チケットの下書きに変換してください。
## 負債候補
{棚卸し結果から対象1件を貼る}
## 追加確認の回答
{担当者の回答、テスト結果、計測値などを貼る}
## 作成条件
- 現状、問題、対応範囲、対象外、受け入れ条件、確認方法を分ける
- 根拠が確認できない記述は残課題に移す
- 大規模な全面改修を前提にしない
- 既存APIとデータ形式の互換性を維持する
- 1回のプルリクエストでレビュー可能な大きさを優先する
- 実装手順ではなく、達成すべき状態を書く
## 出力
1. チケットタイトル
2. 背景と問題
3. 対応範囲
4. 対象外
5. 受け入れ条件
6. テスト・確認方法
7. リスクと未決事項
この分離には意味があります。棚卸しでは広く候補を探し、チケット化では根拠の取れた1件だけを狭く具体化できます。GitHubの技術的負債削減ガイドも、まず小さく始め、対象となる問題やリポジトリを絞る進め方を案内しています。
利用前のチェックリスト
入力前に、次を確認してください。
- [ ] 対象ファイルやディレクトリを限定した
- [ ] 生成コードや外部ライブラリなどの対象外を示した
- [ ] システムの用途と重要な品質を説明した
- [ ] 現場で起きている症状を1つ以上書いた
- [ ] 事実と推測を分けるよう指定した
- [ ] 根拠のファイル名や関数名を求めた
- [ ] 修正コードではなく棚卸しを依頼した
- [ ] 優先度の評価軸を明示した
- [ ] 機密情報、認証情報、個人情報を除外した
- [ ] AIの指摘を人とツールで検証する手順を決めた
最初に試すなら、リポジトリ全体ではなく、最近の変更で繰り返し触っている1機能を対象にしてください。そこで根拠の精度と優先順位の妥当性を確認できたら、隣接モジュールへ範囲を広げます。次の分岐点は、AIが多くの候補を出せるかではなく、担当者が根拠を短時間で検証し、1件を安全な改修単位へ落とせるかです。