Claude Codeで技術的負債を徹底監査する拡張スキル

最近、AIエディタやLLMに「このコードベースの問題点を教えて」と投げた結果を見て、そっとタブを閉じた経験はないだろうか。

返ってくるのは決まって「SOLID原則に違反している箇所があります」「マジックナンバーを定数化しましょう」といった、どこかで読んだようなベストプラクティスの羅列だ。確かにその通りかもしれないが、我々が知りたいのは「この数万行の歴史的遺産の中で、今すぐメスを入れるべき腐敗箇所は具体的にどこか」である。コンテキストを欠いた一般論のアドバイスは、どれだけ網羅的に見えても現場では全く役に立たない。

AIの「雰囲気レビュー」をどう防ぐか

LLMによるコードレビューが失敗するパターンは予測可能だ。彼らは一般的なヒューリスティックにパターンマッチさせ、コードの深層に基づかない自明な問題だけを表面化させる。結果として「もっともらしいが誰も実行に移せない」レポートが生成される。

この徒労感に対する極めて実践的なアンサーが、Claude Codeの拡張スキルとして公開された「tech-debt-audit」だ。ターミナルで /tech-debt-audit と打ち込むだけで、リポジトリ全体を舐め回し、ファイル引用付きの具体的な指摘と修正の優先順位をまとめた TECH_DEBT_AUDIT.md を吐き出してくれる。

注目すべきは、LLM特有の「浅い分析」をプロトコルレベルで徹底的に封じ込めている点だ。このスキルは、3つの強烈な設計思想によって成り立っている。

「とりあえず指摘」を許さない3つの制約

第一に「判断前の強制的なオリエンテーション」だ。このスキルは、LLMがいきなりコードの良し悪しを語ることを許さない。マニフェストを読み、ディレクトリ構造をマッピングし、Gitの変更履歴（Churn）を分析し、アーキテクチャのメンタルモデルを言語化するフェーズを必須としている。コンテキストのない指摘はただの「雰囲気（Vibes）」として切り捨てられる。

第二に「すべての指摘に対するファイルと行番号の明記」だ。「全体的にコードが〜」といった曖昧な主張はエラー弾きされる。path/to/file.ext:LINE が明記されていない指摘は反証不可能であり、反証不可能なものは決して修正されないという現場のリアルをよく分かっている。

そして極め付きが「一見悪そうだが、実は問題ない（Looks bad but is actually fine）」セクションの必須化である。個人的に、これが真の監査と単なるチェックリストの暗唱を分ける決定的な要素だと感じた。LLMに「指摘しようとしたが、踏みとどまった箇所」を明示させることで、深い思考のプロセスを強制する。もしこのセクションが空で返ってきたら、その監査は十分にコードを読み込んでいない証拠となるのだ。

既存のツールチェーンとの決定的な違い

Claude Codeには標準でもいくつかのコード支援スキルが組み込まれているが、それらは技術的負債の「監査」という目的には力不足だった。

tech-debt-auditは、アーキテクチャの崩壊や型付けの負債、テストの不足など、9つの次元でリポジトリ全体を評価する。しかもLLMの推論だけに頼るのではなく、言語ごとの静的解析ツール（TypeScriptならknipやmadge、Pythonならruff、Rustならcargo auditなど）を自動検知して裏側で実行し、その結果をレポートに統合するという泥臭さも兼ね備えている。5万行を超えるような巨大なリポジトリでは、コンテキストウィンドウが溢れないようにサブエージェントをディスパッチしてモジュールごとに並列処理を行うというから恐れ入る。

負債を「生きたドキュメント」として飼い慣らす

このスキルが最終的に出力する TECH_DEBT_AUDIT.md は、一度きりのレポートではない。Gitにコミットしてチームで共有し、継続的に追跡するためのアーティファクトだ。繰り返し実行することで、修正された指摘には RESOLVED タグがつき、新たな問題には NEW タグが付与される。

技術的負債は、見えないからこそ恐ろしい。しかし、行番号付きでリスト化され、工数見積もりと優先順位がつけば、それは単なる「日々のタスク」へと変わる。AIを単なる壁打ち相手から冷徹な監査役へと昇華させるこのアプローチは、LLM時代のコードベース管理におけるひとつの到達点と言えるだろう。

参考リポジトリ: ksimback/tech-debt-skill

Photo by Gabriel Heinzer on Unsplash