tech-debt-analyzer

技術的負債アナライザー

概要

JavaScript／TypeScript のコードベースにおける技術的負債を体系的に特定、分析、記録、追跡します。このスキルでは、技術的負債レジスターを維持するための自動分析ツール、包括的な負債分類フレームワーク、ドキュメントテンプレートを提供します。

コアワークフロー

1. 自動分析

自動スクリプトを実行して、コードベース全体から技術的負債の兆候を検出します。

コードスメルの検出

自動検出ツールを使って、コード品質の問題を特定します。

python3 scripts/detect_code_smells.py src --output markdown

スクリプトでは、次の項目を分析します。

• 大きなファイル： 500 行を超えるファイル
• 複雑な関数： サイクロマティック複雑度が高い（>10）、または長い関数（>50 行）
• 負債を示すマーカー： TODO、FIXME、HACK、XXX、BUG コメント
• Console 文： コードに残されたデバッグ用の文
• 弱い型付け： TypeScript での any 型の使用
• 長いパラメーターリスト： パラメーターが 5 個を超える関数
• 深いネスト： 4 階層を超えるネスト
• マジックナンバー： ハードコードされた数値

出力例：

# Technical Debt Analysis Report

**Files Analyzed:** 127
**Total Lines:** 15,432
**Total Issues:** 89

### Issues by Severity
- HIGH: 23
- MEDIUM: 41
- LOW: 25

## Large Files (12 issues)
### High Priority
- src/components/Dashboard.tsx (847 lines): File too large
- src/services/DataProcessor.ts (623 lines): File too large
...

依存関係の分析

依存関係に負債の兆候がないか調べます。

python3 scripts/analyze_dependencies.py package.json

スクリプトでは、次の項目を特定します。

• 非推奨パッケージ： 非推奨とされているライブラリ（request、tslint など）
• 機能の重複： 同じ目的で使用される複数のパッケージ
• バージョンの問題： 緩すぎる、または厳しすぎるバージョン制約
• セキュリティ上の懸念： 既知の脆弱性があるパッケージ（監査データが必要）

出力例：

# Dependency Analysis Report

**Package:** expense-tracker
**Dependencies:** 24
**Dev Dependencies:** 18
**Total Issues:** 7

## Deprecated/Outdated Packages (3)
### request [HIGH]
Using deprecated package - use axios, node-fetch, or got instead
- Current version: ^2.88.0

## Duplicate Functionality (2)
### HTTP client [MEDIUM]
Multiple packages for HTTP client: axios, node-fetch

2. 手動コードレビュー

自動分析を人の判断が必要な問題に対する手動レビューで補完します。

レビューの重点分野

アーキテクチャ上の負債：

• コンポーネント間の密結合
• 抽象化の不足
• 関心事の分離が不十分
• 循環依存

テストの負債：

• 重要な処理経路のテストカバレッジ不足
• 実装に依存する脆弱なテスト
• 統合テストや E2E テストがない
• テストの実行が遅い

ドキュメントの負債：

• README またはセットアップ手順がない
• アーキテクチャのドキュメントがない
• API ドキュメントが古い
• 重要な決定に対する ADR がない

パフォーマンスの負債：

• N+1 クエリの問題
• 非効率なアルゴリズム
• メモリーリーク
• バンドルサイズが大きい

セキュリティの負債：

• 入力検証が不足している
• 認証／認可がない
• SQL インジェクションの脆弱性
• XSS の脆弱性
• シークレットの露出

3. 分類と評価

標準化された負債カテゴリを使って、調査結果を整理します。

負債カテゴリ

各カテゴリの詳細については、references/debt_categories.md を参照してください。

1. コード品質の負債： コードスメル、複雑さ、重複
2. アーキテクチャ上の負債： 構造、結合、抽象化
3. テストの負債： カバレッジの不足、脆弱なテスト
4. ドキュメントの負債： ドキュメントの不足または古さ
5. 依存関係の負債： 古い、または問題のある依存関係
6. パフォーマンスの負債： 非効率性とボトルネック
7. セキュリティの負債： 脆弱性と弱点
8. インフラストラクチャの負債： DevOps とデプロイに関する問題
9. 設計の負債： UI／UX の不整合

深刻度の評価

影響度と緊急度に基づいて深刻度を割り当てます。

重大：

• セキュリティの脆弱性
• 本番環境に影響する問題
• データ損失のリスク
• 対応： 直ちに修正が必要です

高：

• パフォーマンスに関する重大な問題
• 機能開発を妨げるアーキテクチャ上の問題
• テストされていないリスクの高いコード
• 対応： 現在または次のスプリント内に修正します

中：

• 頻繁に変更されるファイルのコード品質の問題
• ドキュメントの不足
• 古い依存関係（セキュリティ関連ではないもの）
• 対応： 四半期内に対処します

低：

• 軽微なコードスメル
• 最適化の機会
• あると望ましい改善
• 対応： 都合のよいときに対処します

優先度マトリクス

影響度／作業量	作業量：小	作業量：中	作業量：大
影響度：大	最初に実施	2 番目に実施	計画して実施
影響度：中	2 番目に実施	計画して実施	検討する
影響度：小	すぐに取り組める成果	検討する	避ける

4. 調査結果を文書化する

技術的負債を包括的に文書化します。

技術的負債の登録簿

提供されたテンプレートを使って負債の登録簿を管理します。

テンプレートの場所： assets/DEBT_REGISTER_TEMPLATE.md

構成：

## DEBT-001: Complex UserService with 847 lines

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

**Description:**
UserService has grown to 847 lines with multiple responsibilities
including authentication, profile management, and notification handling.

**Impact:**
- Business: Slows down feature development by 30%
- Technical: Difficult to test, high bug rate
- Risk: Changes frequently break unrelated functionality

**Proposed Solution:**
Split into separate services:
- AuthenticationService
- UserProfileService
- NotificationService

**Effort Estimate:** 3 days
**Priority Justification:** High churn area blocking new features
**Target Resolution:** Sprint 24

登録簿のセクション：

1. 対応中の負債項目： 対応が必要な現在の技術的負債
2. 解決済みの項目： 解消した負債の履歴記録
3. 修正しない項目： 許容可能なトレードオフとして受け入れた負債
4. 傾向： カテゴリ、重大度、経過期間ごとの分析
5. レビュー予定： 定期的なメンテナンス計画

アーキテクチャ決定記録（ADR）

将来の負債を防ぐため、重要な技術的決定を ADR で文書化します。

テンプレートの場所： assets/ADR_TEMPLATE.md

ADR を作成するタイミング：

• フレームワークやライブラリを選定するとき
• アーキテクチャを変更するとき
• 大規模なリファクタリングを決定するとき
• 技術を移行するとき
• パフォーマンス最適化の戦略を決めるとき

例：

# ADR-003: Migrate from Moment.js to date-fns

**Status:** Accepted
**Date:** 2024-01-15

## Context
Moment.js is deprecated and increases bundle size by 67KB.
Team needs a modern date library with tree-shaking support.

## Decision
Migrate to date-fns for date manipulation.

## Consequences
- Positive: Reduce bundle by 60KB, modern API, active maintenance
- Negative: Migration effort, learning curve for team
- Technical Debt: None - this resolves existing dependency debt

5. 優先順位を付けて計画する

技術的負債に対処するため、実行可能な計画を作成します。

優先順位付けの方法

1. クリティカルな項目： 直ちに現在のスプリントに追加します
2. 優先度の高い項目： スプリント計画に含めます
3. 優先度が中程度の項目： 四半期ロードマップに追加します
4. 優先度の低い項目： 関連作業の際に機会を見て修正します

時間の割り当て

推奨される割り当て：

• スプリントのキャパシティの 20% を技術的負債に充てる
• スプリントを交互に実施する：機能開発スプリント／負債解消スプリント
• 四半期ごとに専用の「技術健全性」スプリントを設ける

進捗の追跡

負債の削減状況を継続的に監視します。

追跡するメトリクス：

• 負債項目の合計数（減少傾向）
• 重大度ごとの負債（クリティカルな項目は 0 件であるべきです）
• 負債の経過期間（古い負債は懸念事項です）
• 解決率（スプリントごとに修正した項目数）
• 新規負債の発生率（スプリントごとに追加された項目数）

6. 予防策

新たな技術的負債を最小限に抑えるためのプラクティスを導入します。

コードレビューのチェックリスト

PR を承認する前に、以下を確認します。

• コードスメル（複雑さ、サイズ、ネスト）が新たに持ち込まれていない
• 十分なカバレッジを確保するテストが追加または更新されている
• ドキュメント（README、コメント、ADR）が更新されている
• セキュリティの脆弱性がない
• パフォーマンスへの影響が考慮されている
• 正当な理由のない新しい依存関係が追加されていない
• チームの規約やパターンに従っている

自動化による予防

リンティングとフォーマット：

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

必須チェック：

• TypeScript の strict モードが有効になっている
• テストカバレッジの最低基準（80%）
• 重大度の高いセキュリティ脆弱性がない
• バンドルサイズの上限が適用されている

定期的なメンテナンス

毎週：

• TODO／FIXME コメントを確認してトリアージする
• 新たな調査結果を負債の登録簿に追加する

毎月：

• 依存関係を更新する（セキュリティパッチ）
• 負債の登録簿をレビューする
• 優先度の高い項目の修正を計画する

四半期ごと：

• コードベース全体の負債を分析する
• アーキテクチャをレビューする
• 主要な依存関係を更新する
• 傾向を分析し、戦略を調整する

判断フロー

状況に応じて、以下のワークフローに従います。

新しい分析を始めますか？ → 自動スクリプト（detect_code_smells.py、analyze_dependencies.py）を実行します → 出力を確認し、重大度の高い問題を特定します → スクリプトでは検出できない領域を手動でレビューします → 文書化の手順に進みます

調査結果を文書化しますか？ → DEBT_REGISTER_TEMPLATE.md をプロジェクトのルートにコピーします → 各負債項目に詳細を記入します → 種類ごとに分類し、重大度を割り当てます → 工数を見積もり、優先順位を付けます → 計画の手順に進みます

負債の削減を計画しますか？ → 優先順位マトリックス（影響度／工数）で並べ替えます → スプリントのキャパシティを割り当てます（20% を推奨） → 優先度の高い項目からチケットを作成します → 定期的なレビューを予定します

アーキテクチャ上の決定を行いますか？ → ADR_TEMPLATE.md をコピーします → 背景、選択肢、決定を文書化します → 発生する技術的負債がないか確認します → 該当する場合は負債の登録簿に追加します

新たな負債を防ぎますか？ → コードレビューのチェックリストを導入します → リンティングとテストを自動化するよう設定します → 定期的なメンテナンスのスケジュールを設定します → メトリクスを継続的に監視します

ツールとスクリプト

detect_code_smells.py

目的： コード品質の自動分析

使用方法：

python3 scripts/detect_code_smells.py [src-dir] [--output json|markdown]

検出項目：

• 大きなファイル（500 行超）
• 複雑な関数（複雑度が 10 超）
• 技術的負債を示すマーカー（TODO、FIXME、HACK）
• コンソール出力
• 型指定が不十分な TypeScript
• パラメーター数が多い関数（5 個超）
• 深いネスト（4 レベル超）
• マジックナンバー

出力： Markdown レポート、またはプログラム処理用の JSON

analyze_dependencies.py

目的： 依存関係の健全性分析

使用方法：

python3 scripts/analyze_dependencies.py [package.json-path]

検出項目：

• 非推奨パッケージ（request、tslint、node-sass など）
• 機能の重複（複数の日付ライブラリ、HTTP クライアントなど）
• 安全性に欠けるバージョン指定（*、latest）
• 厳密すぎるバージョン指定（^ や ~ を付けない完全一致のバージョン）

出力： 推奨事項を含む Markdown レポート

リファレンスドキュメント

debt_categories.md

技術的負債の種類に関する包括的なガイド。内容：

• 9 つの主要な負債カテゴリ
• 各カテゴリの兆候と例
• 影響の評価基準
• 重大度レベルの定義
• 測定指標
• 予防策

次の場合にこのリファレンスを読み込んでください：

• 特定の負債の種類について詳しい例が必要な場合
• 重大度と影響を評価する場合
• 根本原因を理解する場合
• 予防策を計画する場合

ドキュメントテンプレート

DEBT_REGISTER_TEMPLATE.md

以下を含む、技術的負債の完全な台帳テンプレート：

• 負債項目の構成
• ステータスの追跡
• 影響評価の形式
• 傾向分析のセクション
• レビューのスケジュール

このテンプレートの用途：

• 新しい負債台帳を作成する
• 負債のドキュメント化を標準化する
• チーム／プロジェクト全体で負債を追跡する

ADR_TEMPLATE.md

以下を含む、アーキテクチャ決定記録のテンプレート：

• 背景と問題の説明
• 検討した選択肢
• 決定の根拠
• 影響（正と負）
• 実装計画

このテンプレートの用途：

• 重要な技術的決定を記録する
• 将来の「なぜこれを行ったのか？」という疑問を防ぐ
• 決定によって生じた技術的負債を追跡する

ベストプラクティス

分析のベストプラクティス

1. 定期的に分析を実行する（毎週または隔週）
2. 包括的に把握するため、自動レビューと手動レビューを組み合わせる
3. 最大の効果を得るため、変更頻度の高い領域から着手する
4. 負債の特定にチームを巻き込む
5. 客観的に捉える — どのコードベースにも負債はあります

ドキュメント作成のベストプラクティス

1. 具体的に記載する — ファイル名、行番号、例を含める
2. 影響を説明する — なぜ重要なのか？
3. 解決策を提案する — 不満を述べるだけでなく、修正案を提示する
4. 工数を見積もる — 優先順位付けに役立ちます
5. 傾向を追跡する — 負債は増加しているか、減少しているか？

改善のベストプラクティス

1. 重大な項目はすぐに修正する — 特にセキュリティ関連
2. 継続的に時間を確保する — スプリントのキャパシティの 20%
3. 成果を称える — 負債の削減を追跡し、評価する
4. 完璧を求めて良いものを妨げない — 段階的に改善する
5. 新たな負債を防ぐ — 古い負債を修正するより簡単です

コミュニケーションのベストプラクティス

1. 負債を可視化する — 指標をステークホルダーと共有する
2. 影響を理解してもらう — 負債をビジネス上の成果と結び付ける
3. 賛同を得る — 負債削減の投資対効果を説明する
4. 定期的に報告する — スプリントレビューに含める
5. 責任を追及しない — 非難ではなく改善に焦点を当てる

ワークフローの例

分析から解決までのワークフロー全体：

第 1 週：分析

# Run automated analysis
python3 scripts/detect_code_smells.py src --output markdown > debt_analysis.md
python3 scripts/analyze_dependencies.py package.json >> debt_analysis.md

# Manual review of critical areas
# - Authentication logic
# - Payment processing
# - Data models

第 1～2 週：ドキュメント化

# Create debt register from template
cp assets/DEBT_REGISTER_TEMPLATE.md TECHNICAL_DEBT.md

# Add findings to register with:
# - Category and severity
# - Impact assessment
# - Effort estimation
# - Priority assignment

第 2 週：優先順位付け

# Team review session
# - Review all high/critical items
# - Discuss quick wins (high impact, low effort)
# - Allocate sprint capacity
# - Create tickets for top 5 items

第 3～6 週：改善

# Sprint work
# - Fix 2-3 debt items per sprint
# - Update debt register as items resolved
# - Create ADRs for major refactoring decisions
# - Monitor metrics

毎月：レビュー

# Trend analysis
# - Total debt (should decrease)
# - New debt rate (should be low)
# - Age of oldest items (should decrease)
# - Categories most affected

# Adjust strategy based on trends

---

成功指標

技術的負債の削減効果を測定するために、次の指標を追跡します。

数量指標：

• 技術的負債の項目数合計（減少傾向）
• 重大度別の技術的負債（重大な項目はゼロ）
• LOC 1000 行あたりの技術的負債の項目数

品質指標：

• テストカバレッジ（増加傾向）
• 循環的複雑度（減少傾向）
• ファイル／関数の平均サイズ（横ばい、または減少）

ベロシティ指標：

• スプリントごとに解消した技術的負債の項目数
• スプリントごとに新たに発生した技術的負債の項目数（少ないことが望ましい）
• 解消までの時間（短縮することが望ましい）

ビジネス指標：

• バグ発生率（減少することが望ましい）
• 機能の提供速度（向上することが望ましい）
• 開発者の満足度（向上することが望ましい）