Claudeのtech-debtスキルで技術的負債を棚卸しし優先順位を付ける

tech-debtは、Anthropicがknowledge-work-pluginsで公開しているengineeringプラグインのスキルの1つです。技術的負債を6種類に分け、3つの数字で点数を付け、並べ替えて段階的な返済計画にするところまでを担当します。SKILL.mdはわずか32行で、コードを走査する仕組みは入っていません。

つまり「何を入力するか」で出力の質がほぼ決まります。この記事では導入から呼び出し方、点数式の癖、点数を付ける材料の集め方を順に扱います。

tech-debtスキルが決めていること

SKILL.mdのdescriptionは「Identify, categorize, and prioritize technical debt」で、"tech debt"、"technical debt audit"、"what should we refactor"、"code health"といった言い方に反応するよう書かれています。コード品質、リファクタリングの優先順位、保守バックログの質問でも発動します。

中身は次の3要素だけです。

分類表の6行を並べると、読み方が見えてきます。

コードの話だけではありません。runbookの欠落や手動デプロイも負債として数える設計なので、棚卸しの対象は開発チームの運用全体になります。

導入と呼び出し

engineeringプラグインは主にCowork向けに作られていますが、READMEによればClaude Codeでも動きます。Claude Codeではマーケットプレイスの追加とプラグインの導入を別々に行います。

claude plugin marketplace add anthropics/knowledge-work-plugins
claude plugin install engineering@knowledge-work-plugins

プラグインのスキルは/プラグイン名:スキル名の形で動きます。Claude Codeの公式ドキュメントでは、my-pluginのreviewスキルが/my-plugin:reviewとして動くと説明されています。したがってこのスキルは次の形で呼べます。

/engineering:tech-debt このリポジトリのDependency debtとTest debtを棚卸しして

直接呼ぶ以外に、「技術的負債を洗い出して」のようにdescriptionに合う依頼をすれば、Claudeが自動で読み込むことがあります。導入直後に反映されない場合は、/reload-pluginsコマンドでセッションを閉じずに読み直せます。

注意点が1つあります。knowledge-work-pluginsは公式のマーケットプレイス名ですが、公式ドキュメントでは自動更新がオフの例外として挙げられています。更新を取り込むときは自分で操作します。マーケットプレイスの仕組み全般はClaude Codeプラグイン完全ガイドが詳しい入口です。

READMEのスキル表には、tech-debtのほかにcode-review・incident-response・system-design・testing-strategy・documentationが並びます。コマンドは/standup・/review・/debug・/architecture・/incident・/deploy-checklistの6本です。plugin.jsonのバージョンは1.2.0です。

点数式の癖 — 工数の大きい項目は必ず沈む

式はPriority = (Impact + Risk) x (6 - Effort)です。Effortは反転されていて、工数が小さいほど掛け算の係数が大きくなります。取りうる範囲を計算すると、最小は(1+1) x (6-5) = 2、最大は(5+5) x (6-1) = 50です。

試しに、5件の負債を採点してみます。以下は説明用の仮の数字で、スキルの出力そのものではありません。

上から順に着手すると、モノリス分割は最後です。影響は最大の5でも、Effortが5だと係数が1に潰れるためです。

さらに、この式には癖があります。影響とリスクがともに5で工数も5の「全面的な作り直し」は10 x 1 = 10、影響もリスクも1で工数1の「ごく小さな整理」は2 x 5 = 10で、同点になります。式どおりに並べると、巨大な構造改革と些細な掃除が同じ列に並ぶわけです。

この癖は式の欠陥というより、「小さな勝ちを先に積む」ための設計と読むのが自然です。ただし大きな負債を後回しにし続けると、結局は最大のリスクが残ります。対策は、点数順の一覧とは別に、Effortが4以上でImpact+Riskが8以上の項目を拾い出し、四半期計画に分けて載せることです。出力の「段階的な返済計画」にこの条件を指示として書き加えれば、Claudeがそのとおりに並べ直します。

点数を付ける材料を集める

スキルは採点の枠組みであって、リポジトリを自分で調べる手順は持っていません。入力が「このプロジェクトの負債を教えて」だけだと、Claudeは見える範囲のコードから推測して点数を付けます。根拠の薄い数字が並ぶことになります。

Coworkで使う場合は、READMEの「Standalone」の欄にあるとおり、コードや説明を貼る、ファイルをアップロードする形が基本です。Claude Codeならリポジトリを直接読めるので、材料はセッション内で集められます。たとえば次のコマンドを実行させ、結果をスキルに渡す流れです。

# 直近6か月でよく変更されたファイル(変更の集中箇所)
git log --since="6 months ago" --name-only --pretty=format: \
  | sort | uniq -c | sort -rn | head -20
 
# 古くなった依存(Node.jsの場合)
npm outdated

変更が集中するファイルはImpactの根拠に、npm outdatedの結果はDependency debtの根拠に使えます。テストの不安定さは、CIの失敗履歴を貼って渡すのが確実です。

そのうえで、依頼文に「採点の根拠を1行ずつ付ける」「不明な項目は推測せず『要確認』と書く」の2点を入れます。点数が根拠つきになり、後で見直したときにどこを疑えばよいか分かります。

/engineering:tech-debt 添付のgit logの集計とnpm outdatedの結果をもとに、
負債を洗い出して。各項目にImpact/Risk/Effortの根拠を1行付け、
根拠がない項目は「要確認」にして。出力はdocs/tech-debt.mdに保存して

出力をdocs/tech-debt.mdのようなファイルに残すと、次回の棚卸しで前回との差分を取れます。点数は人が決めたものではなく、Claudeの見積りです。チームでImpactとRiskだけでも合わせてから、Effortの確からしさをレビューする使い方が現実的です。

小さく試す手順と、足りない部分

最初は範囲を絞ります。リポジトリ全体ではなく、ディレクトリ1つとDependency debtだけで試すと、点数のぶれや根拠の質が確かめやすくなります。

足りない部分も書いておきます。SKILL.mdには、Effortの目盛り(1が何時間で5が何か月か)の定義がありません。そのため同じリポジトリでも、実行のたびに数字がぶれる可能性があります。チームで「Effort 3は1スプリント」のように目盛りを決め、依頼文かCLAUDE.mdに書いておくと安定します。

READMEはengineering/.claude/settings.local.jsonにtechStackやdefaultBranchなどを書けるとしていますが、SKILL.mdにはこのファイルへの言及がありません。tech-debtがこの設定を読むかは、SKILL.mdからは分かりません。依頼文にスタックを直接書くほうが確実です。

プラグインのCONNECTORS.mdには、GitHub・Linear・Jira・Datadogなどの接続先が載り、.mcp.jsonにもslack・linear・asana・atlassian・notion・github・pagerduty・datadogが定義されています。接続すれば、PRの履歴や監視の指標も材料にできます。ただし、tech-debtのSKILL.mdには接続先への言及がありません。つなぐ場合は、依頼文で「GitHubのPR履歴から変更が多い領域を拾って」のように、参照させたい情報を自分で指示します。

次の一歩 — 棚卸しの先をつなぐ

棚卸しで上位に出た項目が実際のリファクタリング作業になる場合は、テストが無いコードのリファクタリング手順が続きになります。返済の途中で生じる変更のレビューは、code-reviewプラグインの手順で多角的に確認できます。部門別の公式プラグイン全体の見取り図は、Claude部門別プラグインの使い方にあります。

まとめ

tech-debtは、負債の分類表と点数式を持つ軽量なスキルです。強みは「運用文書や手動デプロイまで負債に数える6分類」と「計算で並べ替えられる点数式」にあります。弱みは、材料集めを自分でやる必要があることと、工数が大きい項目が必ず沈む式の性質です。まず1ディレクトリの依存だけで試し、根拠つきの点数を人が上位3件だけ見直すところから始めると、式の癖とClaudeの見積りの精度を同時に確かめられます。