Technical Debt Analyzer

Overview

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

Core Workflow

1. Automated Analysis

コードベース全体の技術的負債インジケータを検出するために自動スクリプトを実行します。

Code Smell Detection

自動検出器を使用してコード品質の問題を特定します：

python3 scripts/detect_code_smells.py src --output markdown

スクリプトは以下を分析します：

• Large Files: 500行を超えるファイル
• Complex Functions: 高い循環的複雑度（>10）または長い関数（>50行）
• Debt Markers: TODO、FIXME、HACK、XXX、BUG コメント
• Console Statements: コードに残されたデバッグステートメント
• Weak Typing: TypeScript での any 型の使用
• Long Parameters: 5個以上のパラメータを持つ関数
• Deep Nesting: 4レベル以上のネストされたコード
• Magic Numbers: ハードコードされた数値

Output Example:

# 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
...

Dependency Analysis

負債インジケータについての依存関係を確認します：

python3 scripts/analyze_dependencies.py package.json

スクリプトは以下を特定します：

• Deprecated Packages: 既知の非推奨ライブラリ（request、tslint など）
• Duplicate Functionality: 同じ目的を提供する複数のパッケージ
• Version Issues: 不適切に緩い、または厳しいバージョン制約
• Security Concerns: 既知の脆弱なパッケージ（監査データが必要）

Output Example:

# 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. Manual Code Review

人間の判断が必要な問題のため、自動分析を手動レビューで補完します。

Review Focus Areas

Architectural Debt:

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

Test Debt:

• クリティカルパスのテストカバレッジ不足
• 実装と密結合した脆弱なテスト
• 統合テストまたは E2E テストがない
• テスト実行速度が遅い

Documentation Debt:

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

Performance Debt:

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

Security Debt:

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

3. Categorize and Assess

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

Debt Categories

包括的な詳細については references/debt_categories.md を参照してください：

1. Code Quality Debt: コードスメル、複雑性、重複
2. Architectural Debt: 構造、結合、抽象化
3. Test Debt: カバレッジ不足、脆弱なテスト
4. Documentation Debt: ドキュメント欠落または古い
5. Dependency Debt: 古い、または問題のある依存関係
6. Performance Debt: 非効率性とボトルネック
7. Security Debt: 脆弱性と弱点
8. Infrastructure Debt: DevOps とデプロイメントの問題
9. Design Debt: UI/UX 不一致

Severity Assessment

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

Critical:

• セキュリティ脆弱性
• 本番環境を壊す問題
• データ損失リスク
• Action: 即座の修正が必要

High:

• 大きなパフォーマンス問題
• 機能をブロックするアーキテクチャの問題
• 高リスクのテストされないコード
• Action: 現在のスプリントまたは次のスプリント内に修正

Medium:

• 頻繁に変更されるファイルのコード品質の問題
• ドキュメント欠落
• 古い依存関係（セキュリティ以外）
• Action: 四半期内に対処

Low:

• マイナーなコードスメル
• 最適化機会
• あると良い改善
• Action: 都合がつくときに対処

Priority Matrix

Impact / Effort	Low Effort	Medium Effort	High Effort
High Impact	Do First	Do Second	Plan & Do
Medium Impact	Do Second	Plan & Do	Consider
Low Impact	Quick Win	Consider	Avoid

4. Document Findings

技術的負債の包括的な文書を作成します。

Technical Debt Register

提供されたテンプレートを使用して負債レジスタを保守します：

Template Location: assets/DEBT_REGISTER_TEMPLATE.md

Structure:

## 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

Register Sections:

1. Active Debt Items: 注意が必要な現在の技術的負債
2. Resolved Items: 修正された負債の履歴記録
3. Won't Fix Items: 許容可能なトレードオフとして受け入れられた負債
4. Trends: カテゴリ、深刻度、年齢による分析
5. Review Schedule: 定期的なメンテナンス計画

Architecture Decision Records (ADRs)

将来の負債を防ぐために ADRs を使用して主要な技術的決定を文書化します。

Template Location: assets/ADR_TEMPLATE.md

When to Create ADRs:

• フレームワークまたはライブラリの選択
• アーキテクチャの変更
• 主要なリファクタリング決定
• テクノロジーマイグレーション
• パフォーマンス最適化戦略

Example:

# 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. Prioritize and Plan

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

Prioritization Approach

1. Critical Items: 現在のスプリントに即座に追加
2. High Items: スプリント計画に含める
3. Medium Items: 四半期ロードマップに追加
4. Low Items: 関連するワーク中の機会修正

Time Allocation

Recommended Allocation:

• スプリント容量の 20% を技術的負債に
• 交互スプリント：機能スプリント / 負債スプリント
• 専用四半期「テックヘルス」スプリント

Tracking Progress

時間をかけて負債削減を監視します：

Metrics to Track:

• 総負債項目（トレンドは下向き）
• 深刻度別の負債（クリティカルは 0 であるべき）
• 負債年齢（古い負債は懸念事項）
• 解決率（スプリント当たり修正された項目）
• 新しい負債率（スプリント当たり追加された項目）

6. Prevention Strategies

新しい技術的負債を最小化するプラクティスを実装します。

Code Review Checklist

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

• コードスメルが導入されていない（複雑性、サイズ、ネスト）
• テストが追加/更新され、適切なカバレッジがある
• ドキュメント更新（README、コメント、ADRs）
• セキュリティ脆弱性がない
• パフォーマンス影響を考慮
• 正当化なしの新しい依存関係がない
• チーム規約とパターンに従う

Automated Prevention

Linting and Formatting:

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

Required Checks:

• TypeScript strict モード有効
• 最小テストカバレッジしきい値（80%）
• 高深刻度のセキュリティ脆弱性がない
• バンドルサイズ制限を施行

Regular Maintenance

Weekly:

• TODO/FIXME コメント確認とトリアージ
• 新しい知見で負債レジスタを更新

Monthly:

• 依存関係更新（セキュリティパッチ）
• 負債レジスタレビュー
• 優先度の高い項目の修正計画

Quarterly:

• コードベース全体の負債分析
• アーキテクチャレビュー
• 主要な依存関係更新
• トレンド分析と戦略調整

Decision Tree

状況に基づいてこのワークフローに従います：

新しい分析を開始していますか？ → 自動スクリプト実行（detect_code_smells.py、analyze_dependencies.py） → 高深刻度の問題について出力をレビュー → スクリプトが検出できない領域の手動レビュー → ドキュメンテーションステップに進む

結果を文書化していますか？ → DEBT_REGISTER_TEMPLATE.md をプロジェクトルートにコピー → 各負債項目を全詳細で追加 → タイプ別にカテゴリ化し深刻度を割り当て → 工数を見積もりと優先順位付け → 計画ステップに進む

負債削減を計画していますか？ → 優先度マトリックス（影響/工数）でソート → スプリント容量を配分（推奨 20%） → 優先度の高い項目のチケットを作成 → 定期的なレビューをスケジュール

アーキテクチャの決定を下していますか？ → ADR_TEMPLATE.md をコピー → コンテキスト、オプション、決定を文書化 → 発生する負債を特定 → 該当する場合は負債レジスタに追加

新しい負債を防いでいますか？ → コードレビューチェックリストを実装 → 自動リント/テストを構成 → 定期的なメンテナンススケジュールを設定 → 時間をかけてメトリックスを監視

Tools and Scripts

detect_code_smells.py

Purpose: 自動コード品質分析

Usage:

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

Detects:

• 大きなファイル（>500行）
• 複雑な関数（複雑度 >10）
• 技術的負債マーカー（TODO、FIXME、HACK）
• console ステートメント
• 弱い TypeScript タイピング
• 長いパラメータリスト（>5 params）
• 深いネスト（>4レベル）
• マジックナンバー

Output: プログラム的な処理のための Markdown レポートまたは JSON

analyze_dependencies.py

Purpose: 依存関係の健全性分析

Usage:

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

Detects:

• 非推奨パッケージ（request、tslint、node-sass など）
• 重複した機能（複数の日付ライブラリ、http クライアントなど）
• 安全でないバージョン制約（*、latest）
• 過度に厳しいバージョン（^ または ~ なしの完全指定）

Output: 推奨事項付き Markdown レポート

Reference Documentation

debt_categories.md

以下を含む技術的負債タイプの包括的なガイド：

• 9つの主要な負債カテゴリ
• 各カテゴリのインジケータと例
• 影響評価基準
• 深刻度レベルの定義
• 測定メトリックス
• 予防戦略

Load this reference when:

• 特定の負債タイプの詳細な例が必要
• 深刻度と影響を評価
• 根本原因を理解
• 予防戦略を計画

Documentation Templates

DEBT_REGISTER_TEMPLATE.md

以下を含む完全な技術的負債レジスタテンプレート：

• 負債項目構造
• ステータストラッキング
• 影響評価フォーマット
• トレンド分析セクション
• レビュースケジュール

Use this template to:

• 新しい負債レジスタを開始
• 負債文書を標準化
• チーム/プロジェクト全体の負債をトラッキング

ADR_TEMPLATE.md

以下を含む Architecture Decision Record テンプレート：

• コンテキストと問題ステートメント
• 検討されたオプション
• 決定の根拠
• 結果（肯定的と否定的）
• 実装計画

Use this template to:

• 主要な技術的決定を文書化
• 将来の「なぜこれをしたのか？」という質問を防ぐ
• 決定によって発生した技術的負債をトラッキング

Best Practices

Analysis Best Practices

1. 定期的に分析を実行（週 1 回または隔週）
2. 自動 + 手動レビューを組み合わせて包括的なカバレッジを実現
3. 最大限の影響のために高チャーン領域に焦点を当てる
4. チームを含める負債特定に
5. 客観的であるすべてのコードベースには負債がある

Documentation Best Practices

1. 具体的であるファイル名、行番号、例を含める
2. 影響を説明するなぜこれが重要なのか？
3. 解決策を提案する不平を言うだけではなく、修正を示唆
4. 工数を見積もる優先順位付けに役立つ
5. トレンドをトラッキング負債は増加または減少していますか？

Remediation Best Practices

1. クリティカル項目を即座に修正特にセキュリティ
2. 一貫した時間を割り当てるスプリント容量の 20%
3. 勝利を祝う負債削減をトラッキングおよび認識
4. 完璧を良いことの敵にしない増分改善
5. 新しい負債を防ぐ修正より簡単

Communication Best Practices

1. 負債を可視化するメトリックスをステークホルダーと共有
2. 影響を教育する負債をビジネス成果に接続
3. 買収を得る負債削減の ROI を説明
4. 定期的な更新スプリントレビューに含める
5. 非難を避ける改善に焦点を当て、落ち度ではなく

Example Workflow

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

Week 1: Analysis

# 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

Week 1-2: Documentation

# 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

Week 2: Prioritization

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

Weeks 3-6: Remediation

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

Monthly: Review

# 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

---

Success Metrics

負債削減の有効性を測定するためにこれらのメトリックスをトラッキングします：

Quantity Metrics:

• 総負債項目（トレンドは下向き）
• 深刻度別の負債（クリティカルはゼロ）
• 1000 行当たりの負債項目

Quality Metrics:

• テストカバレッジ（トレンドは上向き）
• 循環的複雑度（トレンドは下向き）
• 平均ファイル/関数サイズ（安定または減少）

Velocity Metrics:

• スプリント当たりの解決された負債項目
• スプリント当たりの新しい負債項目（低いべき）
• 解決時間（減少するべき）

Business Metrics:

• バグ率（減少するべき）
• 機能配信速度（増加するべき）
• 開発者満足度（増加するべき）