tech-debt-audit

技術的負債の監査

コードベース全体を意図的かつ独自の視点で監査し、根拠を示した指摘をまとめた TECH_DEBT_AUDIT.md を作成する Claude Code スキルです。

/tech-debt-audit で呼び出されたら、以下のプロトコルに従ってください。ここから --- 区切りまでが Claude の実行するプロトコルです。区切りの後は、このスキルをインストールまたは保守する人向けのドキュメントです。

---

運用原則

実際に問題となっている点を見つけてください。遠慮は不要です。表面的な指摘にとどめないでください。このリポジトリ固有の根拠なしに、一般的なベストプラクティスに当てはめないでください。お世辞は不要です。「コードベース全体の構成はよくできています」といった中身のない記述は避けてください。

具体的な指摘にはすべて file:line を記載してください。「コード全般が……」のような曖昧な主張は認められません。判断する前にコードを読んでください。単独で見ると誤りに見えるパターンでも、重要な役割を担っている可能性があります。

フェーズ 1：全体像を把握する

ここは省略しないでください。システムを理解する前に意見を形成すると、監査の質が下がります。

1. README、パッケージマニフェスト（package.json ／ pyproject.toml ／ Cargo.toml ／ go.mod）、および /docs または /adr にあるアーキテクチャ関連ドキュメントを読みます。
2. ディレクトリ構成を把握し、主要なモジュールやレイヤーを特定します。
3. git log --oneline -200 と git log --stat --since="6 months ago" を実行して、実際にどこが変更されているか、変更がどこに集中しているかを確認します。
4. エントリーポイント、ホットパス、あまり変更されない領域を特定します。
5. 行数の多いファイル上位 20 件と、過去 6 か月に最も頻繁に変更されたファイル上位 20 件を一覧にします。負債が潜んでいるのは、通常、この両方に含まれるファイルです。
6. TodoWrite を使って計画を公開し、ユーザーが各フェーズの進捗を確認できるようにします。

続行する前に、アーキテクチャのメンタルモデルを 1～2 段落でまとめます。モデルが README の記述と食い違う場合は、その点を指摘してください。それ自体が監査結果になります。

フェーズ 2：以下の観点で監査する

rg、ast-grep、言語固有のツールを使って、具体例を見つけてください。指摘にはすべて path/to/file.ext:LINE を記載してください。

1. アーキテクチャの劣化 — 循環依存、レイヤー違反、巨大なファイル（500 LOC 超）や巨大な関数、抽象化すべきロジックが 3 か所以上で重複している箇所、存在するのに使われていない抽象化、デッドコード（未使用のエクスポート、到達不能な分岐、古いコメントアウト部分）。

2. 一貫性の劣化 — 同じ処理を実現する複数の方法（HTTP クライアント、エラー処理、ロギング、設定読み込み、バリデーション、日付処理）。命名の揺れ。実際のコードの役割を反映しなくなったフォルダー構成。

3. 型と契約の負債 — any ／ unknown ／ as any ／ # type: ignore ／ 型の緩い辞書。型付けされていない API 境界。信頼境界でのスキーマ検証の欠如。

4. テストの負債 — 利用可能であればカバレッジを実行し、重要なパスの不足を特定します。動作ではなく実装を検証するテスト。スキップされたテストや不安定なテスト。変更頻度の高いファイルのうち、テストがないもの。

5. 依存関係と設定の負債 — npm audit ／ pip-audit ／ cargo audit で CVE を確認します。未使用の依存関係。同じ役割を担う重複した依存関係。環境変数の乱立（参照されているのに文書化されていないもの、環境ごとにデフォルト値が一貫していないもの）。

6. パフォーマンスとリソース管理 — N+1 クエリ、非同期パス内の同期処理、ホットパスでのブロッキング I/O、解放されないリスナーやハンドル、不要なシリアライズ。

7. エラー処理と可観測性 — 握りつぶされる例外、広範すぎる catch、ログに記録されても処理されないエラー、モジュール間で一貫しないエラー形式、重要なパスでの構造化ログの不足。

8. セキュリティ衛生 — ハードコードされたシークレット、文字列連結による SQL、信頼境界での入力検証の欠如、過度に許可的な認証や CORS、脆弱な暗号化。

9. ドキュメントの乖離 — 実態と一致しない README の記述、隣接するコードと矛盾するコメント、docstring のない公開 API。

フェーズ 3：成果物

リポジトリのルートにある TECH_DEBT_AUDIT.md に、次の構成で記述します。

• エグゼクティブサマリー — 影響度順に最大 10 項目。
• アーキテクチャのメンタルモデル — システムの実際の状態についての理解。
• 調査結果の表 — 列：ID | Category | File:Line | Severity (Critical/High/Medium/Low) | Effort (S/M/L) | Description | Recommendation。調査結果は 30～80 件を目安とし、それ以上に水増ししてもノイズになります。
• 「ほかを何も直さないなら、これだけは直す」上位 5 項目 — 曖昧な助言ではなく、具体的な差分案またはリファクタリングの概要を記載します。
• すぐにできる改善 — 低工数 × 中以上の重要度の項目をチェックリストにします。
• 問題に見えるが、実際には問題ないもの — 指摘を検討したものの、見送った項目とその理由を記載します。このセクションは必須です。 空の場合は、十分に調査できていません。
• メンテナーへの未解決の質問 — 技術的負債なのか、意図的なものなのか判断できなかった事項。

ルール

• 具体的な指摘にはすべて file:line を記載します。
• 技術的負債なのか意図的なものなのか判断できない場合は、断定せず、未解決の質問のセクションで尋ねてください。
• 書き換えは勧めないでください。範囲を絞った具体的な変更を提案してください。
• 水増ししないでください。該当カテゴリに重要な項目がなければ、「重要な指摘なし」と記載して次に進みます。
• お世辞は不要です。何が壊れているのかを伝えてください。

スタック固有のツール

マニフェストからスタックを特定し、該当するツールを実行します。可能な場合は並行して実行してください。

• TypeScript / JavaScript — npm audit、npx knip（未使用のエクスポート）、npx madge --circular（循環依存）、npx depcheck（未使用の依存関係）、型の不整合を調べる tsc --noEmit。
• Python — pip-audit、ruff check、vulture（デッドコード）、pydeps --show-cycles、型の不整合を調べる mypy --strict。
• Rust — cargo audit、cargo udeps、cargo machete、cargo clippy -- -W clippy::pedantic。
• Go — govulncheck、go vet、staticcheck、golangci-lint run。

ツールがインストールされていない場合は、その旨を監査レポートに記載して先に進みます。開発ツールを許可なくグローバルにインストールしないでください。

大規模なリポジトリ：サブエージェントを起動する

リポジトリが 50k LOC を超える場合、またはトップレベルのモジュールが 5 つを超える場合は、サブエージェント（Task ツール）を並行して起動し、モジュールごとに担当させてください。その後、各レポートを統合します。大規模なリポジトリを逐次的に読み進めると、調査結果をまとめる前にコンテキストウィンドウを使い切ってしまいます。

各サブエージェントには、担当範囲（モジュール 1 つ）、上記の調査項目、引用の要件、調査結果の上限 200 件を伝えます。メインエージェントが結果を統合し、重複を取り除き、優先順位を付けます。

再実行モード

リポジトリに TECH_DEBT_AUDIT.md がすでに存在する場合は、まずその内容を読みます。解消済みの指摘には RESOLVED を付け、古くなった指摘を更新し、新しい指摘には NEW を付けます。これにより、監査を継続的に追跡できるドキュメントにできます。

---

プロジェクトのドキュメント

以下は、このスキルをインストール、使用、または開発に参加する人向けの情報です。監査プロトコルには含まれません。

インストール

個人用インストール（すべてのプロジェクトで利用可能）：

mkdir -p ~/.claude/skills/tech-debt-audit

curl -o ~/.claude/skills/tech-debt-audit/SKILL.md https://raw.githubusercontent.com/ksimback/tech-debt-skill/main/SKILL.md

または、プロジェクト専用にインストールする場合（このリポジトリのみ）：

mkdir -p .claude/skills/tech-debt-audit && cp /path/to/SKILL.md .claude/skills/tech-debt-audit/SKILL.md

読み込まれたことを確認します：

echo "/skills" | claude

使用方法

Claude Code で、監査するリポジトリを開き、次を実行します：

/tech-debt-audit

これで完了です。出力はリポジトリのルートにある TECH_DEBT_AUDIT.md に保存されます。初回の実行には、リポジトリのサイズに応じて 5～20 分かかります。再実行モードでの 2 回目以降の実行は、より短時間で完了します。

設計理念

ほとんどの「コードレビュー」プロンプトは、一般的なベストプラクティス違反を指摘事項らしく見せた箇条書きを出力します。このスキルは、そうした失敗を避けるために作られています。効果を発揮する設計上の工夫は、主に3つあります。

判断の前に、必ず状況を把握する。 フェーズ1は任意の飾りではありません。アーキテクチャの実像を理解していなければ、フェーズ2の指摘はどれも、一般的なヒューリスティックに当てはめただけのものになります。変更頻度を把握するためにgit logを読むことで、実際に負債を抱えているファイルと、単に雑然として見えるだけのファイルを見分けられます。

すべての指摘にファイルと行番号を記載する。 これは品質を左右する最大の要素です。引用のない指摘は、ただの印象にすぎません。印象だけでは修正されません。

「問題に見えるが、実際には問題ない」セクションを必須にする。 プロンプトを自分向けに変更するとき、多くの人が最初に削除するのがこのセクションです。削除しないでください。検討したものの、採用しなかった指摘をモデルに明示させることで、本当の監査とチェックリストの焼き直しを区別できます。このセクションが空なら、監査は浅いということです。

このスキルでは、書き換えの提案と、カテゴリを水増しすることも明示的に禁止しています。どちらもLLMによく見られる失敗です。書き換えは原因の診断より簡単で、水増しは内容が伴わないのに、出力を網羅的に見せてしまいます。

得られるもの

TECH_DEBT_AUDIT.mdは、次のような形式になります。

# Tech Debt Audit — <repo name>
Generated: 2026-04-25

## Executive summary
- 3 Critical findings, 12 High, 31 Medium, 18 Low
- Largest debt concentration: src/payments/* (god module, 4 of 3 Critical findings)
- ...

## Architectural mental model
The system is a [...]

## Findings
| ID | Category | File:Line | Severity | Effort | Description | Recommendation |
|----|----------|-----------|----------|--------|-------------|----------------|
| F001 | Architectural decay | src/payments/processor.ts:1240 | Critical | L | 1,400-line god class handling routing, validation, retry, and reconciliation | Extract retry and reconciliation into separate services |
| ... |

## Top 5
1. **F001 — Decompose payments/processor.ts** ...

## Quick wins
- [ ] F042: Remove unused dep `lodash.merge` (replaced by native ...)
- [ ] ...

## Things that look bad but are actually fine
- The deeply nested callback pattern in `src/legacy/webhooks.ts` looks like a refactor target, but it preserves ordering guarantees that the queue-based replacement would break. Leave it.
- ...

## Open questions
- Is `src/experiments/` intentionally untested, or did it fall through?
- ...

適用に関するメモ

プロジェクト単位での上書き。 特定のリポジトリにある.claude/skills/tech-debt-audit/SKILL.mdは、グローバルの設定より優先されます。プロジェクト固有の観点が必要な場合に便利です。たとえば、エージェントのコードベースでは、「プロンプトインジェクションの攻撃対象領域」や「ターンあたりのツール呼び出しコスト」を監査カテゴリに追加できます。

監査途中での方向修正。 フェーズ1が完了した後、次のように割り込んで指示できます。「フェーズ2に進む前に、フェーズ1で意外だったことと、観点リストにはないもので調査したいことを教えてください。」 最も優れた指摘は、プロンプトが想定していなかったことから生まれる場合があります。新しいコードベースで初めて実行するときは、試す価値があります。

深刻度の調整。 モデルが問題を過剰に、または過少に指摘する場合は、フェーズ2の観点リストに明確な基準値を追加してください。たとえば、コードベースの規模が一般より大きい場合、「巨大なファイル（>500 LOC）」を「>800 LOC」に変更します。

カテゴリの追加。 フェーズ2の9つの観点は出発点です。利用している技術スタックに合わせて、ドメイン固有の観点を追加してください。たとえば、フロントエンドならアクセシビリティ、インフラならIaCのドリフト、MLならモデル評価、LLMアプリならプロンプトのバージョン管理を追加できます。

補助ファイルへの分割。 このSKILL.mdが大きくなってきたら、セクションを兄弟ファイル（severity-rubric.md、stack-tooling.md）に切り出し、プロトコルから参照できます。Claude Codeは必要なときだけ、それらを遅延読み込みします。

制限事項

これは静的監査であり、セキュリティ監査ではありません。明らかなセキュリティ衛生上の問題（ハードコードされたシークレット、SQLインジェクションのパターン）は検出できますが、実際のペネトレーションテストや脅威モデルの代わりにはなりません。

ビジネスロジックのバグは検出できません。それにはモデルが持っていないドメイン知識が必要です。

意図的なシンプルさと、意図せず単純になっている状態を区別することはできません。「未解決の質問」セクションは、まさにこのためにあります。判断に迷ったとき、スキルは決めつけずに質問します。

非常に大規模なリポジトリ（>200k LOC）では、サブエージェントに処理を割り当てても結果が浅くなることがあります。対象をモジュールに絞ることを検討してください。例：/tech-debt-audit src/payments

貢献

PRを歓迎します。提出する前に、次のことを行ってください。

1. 異なる技術スタックの実際のコードベースを、少なくとも2つ使ってテストしてください。
2. 観点を追加する場合は、既存の9つの観点ではカバーできない理由を説明してください。
3. ルールを厳格化する場合は、改善を示す監査抜粋を変更前と変更後で提示してください。

唯一の設計上の制約は、このスキルがエンジニアの行動につながる指摘を出すことです。「網羅的に感じられるが、何も変わらない」方向につながるものは、すべて後退です。

ライセンス

MIT。自由に使用、フォーク、公開してください。クレジット表記は歓迎しますが、必須ではありません。

謝辞

Claude Code Agent Skills標準に基づいて作られています。長い時間をかけて非常に雑然としたコードベースを、Claude Codeとともに扱った経験から着想を得ました。