tech-debt-analyzer

技術的負債アナライザー

技術的負債を体系的に特定、分析し、文書化します。

使用する場面

次のような場合に使用します：

• コード品質の問題を分析する
• 技術的負債の台帳を作成する
• コードの保守性を評価する
• 依存関係の問題を特定する
• セキュリティ脆弱性を文書化する
• リファクタリングの取り組みを計画する

次のような場合には使用しないでください：

• 新しいコードを書く場合 → generic-feature-developer を使用してください
• コードレビューを行う場合 → generic-code-reviewer を使用してください
• テストを書く場合 → test-specialist を使用してください

クイック分析コマンド

# Find large files (>500 lines)
find src -name "*.ts" -exec wc -l {} + | awk '$1 > 500' | sort -rn

# Find TODO/FIXME markers
grep -rn "TODO\|FIXME\|HACK\|XXX" src/

# Check for console.log in production code
grep -rn "console.log" src/ --include="*.ts" --include="*.tsx"

# Find TypeScript 'any' usage
grep -rn ": any" src/ --include="*.ts" --include="*.tsx"

# Check outdated dependencies
npm outdated

# Security vulnerabilities
npm audit

# Unused exports (requires ts-unused-exports)
npx ts-unused-exports tsconfig.json

負債のカテゴリ

カテゴリ	例
コード品質	大きなファイル、複雑な関数、TODO/FIXME マーカー
アーキテクチャ	密結合、抽象化の欠如、循環依存
テスト	カバレッジ不足、壊れやすいテスト、実行時間の遅さ
ドキュメント	README の欠如、古いドキュメント、ADR の欠如
依存関係	古いパッケージ、セキュリティ脆弱性
パフォーマンス	N+1 クエリ、メモリーリーク、大きなバンドル
セキュリティ	バリデーションの欠如、シークレットの露出、XSS／SQL インジェクション

分析ワークフロー

1. 自動検出

確認するコードの不吉な臭い：

• 大きなファイル（500 行超）
• 複雑な関数（循環的複雑度が 10 超）
• 負債マーカー（TODO、FIXME、HACK、XXX）
• 本番コード内のコンソール出力
• TypeScript の any 型
• 長いパラメーターリスト（5 個超）
• 深いネスト（4 階層超）

依存関係の問題：

• 非推奨のパッケージ
• 機能の重複
• 緩いバージョン制約
• 既知の脆弱性

2. 重大度の評価

重大度	基準	対応
重大	セキュリティ脆弱性、データ損失のリスク	直ちに修正
高	パフォーマンスの問題、作業を妨げる問題	現在のスプリントで対応
中	コード品質、ドキュメント不足	今四半期中に対応
低	軽微な不吉な臭い、最適化	都合のよいときに対応

3. 優先度マトリックス

影響度／工数	低	中	高
影響度：高	最初に対応	次に対応	計画して対応
影響度：中	次に対応	計画して対応	検討
影響度：低	すぐに成果が出る項目	検討	回避

負債台帳の形式

## DEBT-001: Description

**Category:** Code Quality | **Severity:** High
**Location:** src/services/UserService.ts

**Description:** Brief description of the issue

**Impact:**

- Business: How it affects delivery
- Technical: Why it's problematic
- Risk: What could go wrong

**Proposed Solution:** What to do about it
**Effort:** Days/hours estimate
**Target:** Sprint/quarter

予防策

自動ガード

{
  "rules": {
    "complexity": ["error", 10],
    "max-lines-per-function": ["error", 50],
    "max-params": ["error", 5],
    "max-depth": ["error", 4]
  }
}

メンテナンススケジュール

頻度	タスク
毎週	TODO/FIXME を確認し、台帳を更新
毎月	依存関係を更新し、負債をレビュー
四半期ごと	全体分析、アーキテクチャレビュー

自己批評チェックリスト

負債分析の完了後：

• 自動チェックをすべて実行した
• 重要なパスを手動でレビューした
• 重大度の評価に根拠がある
• 提案した解決策を実行できる
• 優先度マトリックスを一貫して適用した
• 台帳の項目がすべて揃っている

関連項目

• コードレビュースタンダード - 品質チェック
• プロジェクトの CLAUDE.md - ワークフロールール