Communityコーディング&開発github.com

技術的負債発見

コードベースの技術的負債(デッドコード、重複、アーキテクチャの問題、先送り作業、フレームワークアンチパターン、低品質テスト)を分析し、重要度でランク付けし、ユーザーが確認した後にGitHub Issueとして起票します。

技術的負債発見 とは?

このスキルは、コードベースの技術的負債を体系的に発見し、GitHub Issueに変換するための強力なツールです。デッドコード、重複、アーキテクチャ上の問題、先送り作業、フレームワークアンチパターン、テスト品質の6カテゴリを分析し、各発見にP0~P4の重要度を割り当てます。スコープ指定、全スキャン、カテゴリ選択、ドライランなど、柔軟な実行オプションをサポートし、分析前にリポジトリのスタック(言語・フレームワーク・テストランナー)を自動検出します。重複検出や既存Issueとの照合により重複を排除し、ユーザーの確認後にGitHub CLI(gh)を使ってIssueを作成します。並列サブエージェントにも対応し、大規模コードベースでも効率的に動作するよう設計されています。

対応✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/JAdshead/toolkit/tree/HEAD/skills/tech-debt

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Tech Debt Discovery(技術的負債発見)

コードベースの技術的負債を分析し、発見事項を実行可能なGitHub Issueに変換します。この分析は読み取り専用です。スキル実行中にコードを変更することはありません。

オプション

ユーザーのリクエストまたはコマンド引数からこれらを解析します。

  • Scope paths(スコープパス): 分析するディレクトリまたはファイル(例:src/services lib/)。
  • --full: リポジトリ全体をスキャンします(node_modules、vendor、.git、dist、build、target、tmp、log、仮想環境、生成コードは除外)。
  • --dry-run: Issueを作成せずに結果のみを報告します。
  • --all: 20件の上限を解除します。
  • --force: 類似のオープンIssueが存在してもIssueを作成します。
  • --yes: 確認プロンプトをスキップします(ユーザーが明示的に指定した場合のみ)。
  • --categories=X,Y: 特定のカテゴリのみ実行します:dead-code、duplication、architecture、deferred-work、patterns、tests。

実行モデル

各カテゴリは独立して分析されます。エージェントが並列サブエージェントを起動できる場合は、各カテゴリにスコープ、検出されたスタック、および references/categories.md の該当カテゴリのチェックリストを渡し、それぞれが以下のJSON形式を返すようにします。そうでない場合は、カテゴリを順次実行し、コンテキスト制限内に収めます。

6カテゴリの順次実行は、中規模のコードベースで約15~30分かかります。より高速な結果を得るには、--categories またはより狭いスコープを推奨します。

Step 1: スコープの決定

  1. パスが指定されている場合はそれを使用します。
  2. --full が指定されている場合は、上記の除外ルールでリポジトリをスキャンします。
  3. それ以外の場合は、存在する主要なソースディレクトリとテストディレクトリを自動検出します(一般的なもの:src/、app/、lib/、pkg/、internal/、cmd/、test/、tests/、spec/)。次のように表示します: Auto-detected scope: [ディレクトリ]. About X files. Continue? (use --full for a complete scan)

リポジトリが実際に使用している拡張子でスコープ内のソースファイルをカウントします(例:git ls-files -- <scope> | grep -E '\.(rb|py|ts|tsx|js|go|java|kt|rs|php|cs)$' | wc -l)。

  • 1,000ファイルを超える場合:実行に時間がかかることを警告し、--categories を提案します。
  • 5,000ファイルを超える場合:一度に1カテゴリずつ実行することを強く推奨し、カテゴリごとのおおよその所要時間を示します。

Step 2: 事前分析チェック

--dry-run でない限り、GitHub CLIを確認します。

gh auth status

失敗した場合は gh_available=false を設定し、次のように表示します:「gh CLIが見つからないか、認証されていません。Issueを作成せずに結果を報告します。gh auth login を実行してIssue作成を有効にしてください。」

利用可能な場合は、後で必要になるデータを取得します。

gh issue list --state open --limit 200 --json number,title,body,labels
gh label list --limit 200 --json name,description

Issueリストを重複検出に、ラベルリストをラベル付けに使用します。

Step 3: スタックの検出

リポジトリの言語、フレームワーク、テストランナーを自動検出します(仮定はしません)。代表的な指標は以下の通りです。

指標スタック
Gemfile に rails あり、または config/application.rbRuby on Rails
manage.py または requirements / pyproject.toml に djangoDjango
pyproject.toml / requirements.txt に fastapi または flaskPython Web
package.json に next、react、vue、svelte、express、nestjsJS/TS フレームワーク
go.modGo
Cargo.tomlRust
pom.xml / build.gradle*JVM(SpringがあればSpring)
composer.json に laravel/frameworkLaravel
*.csproj.NET

テストフレームワーク(RSpec、Minitest、pytest、unittest、Jest、Vitest、Mocha、Go testing、JUnit、PHPUnitなど)とテストディレクトリも検出します。

判断する前に、プロジェクト独自の規約(README、CONTRIBUTING、エージェント指示ファイル(AGENTS.md、CLAUDE.md、GEMINI.md)、リンター設定、アーキテクチャドキュメント)を読みます。プロジェクトが意図的に選択したパターンは負債ではありません。

次のように報告します:Stack detected: [言語/フレームワーク/テストランナー]. Analysis rules adjusted accordingly.

Step 4: カテゴリ分析の実行

有効な各カテゴリ(デフォルトは全6カテゴリ)について:

  1. Analyzing [カテゴリ]... (X of N) とアナウンスします。
  2. references/categories.md の該当カテゴリのチェックリストを、検出されたスタックに適応させて適用します。
  3. 発見事項を以下のJSON形式で収集します。
  4. [カテゴリ] complete: X findings と報告します。

あるカテゴリが他のカテゴリより大幅に長くかかる場合(アクティブ分析で約5分)、そのカテゴリを停止し、レポートで「Incomplete (truncated)」とマークして、実行が止まらないようにします。

発見事項の形式

各カテゴリは以下を返します。

{
  "category": "Dead Code",
  "findings": [
    {
      "type": "Unused Import",
      "severity": "P3",
      "location": "src/utils/format.ts:5",
      "line_number": 5,
      "description": "Import 'date-fns' is never used in this file",
      "evidence": "import { format } from 'date-fns'",
      "remediation": "Remove the unused import",
      "complexity": "simple"
    }
  ]
}

重複の場合は、すべての場所を location にカンマ区切りで入れます。アーキテクチャ上の発見の場合は、メトリクスを description に含めます(例:「567 lines, 23 public methods」)。

重要度リファレンス

パターン重要度カテゴリ
セキュリティ問題を隠すテストP0Test Quality
リソースアクセス時の認可チェック欠落P1Pattern Violations
Godクラス(>500行または>20のpublicメソッド)P1Architecture
循環依存P1Architecture
到達不能コードP1Dead Code
モックのみのテスト(テスト対象をモックしているテスト)P1Test Quality
テスト対象をスタブ化してアサートP1Test Quality
トートロジー的なテストP1Test Quality
空のテスト本体P1Test Quality
過剰なモック(テストの50%以上がセットアップ)P1Test Quality
クラスの全インスタンスをスタブ化P1Test Quality
テスト間で共有される可変状態P1Test Quality
長い関数(>50行)P2Architecture
高い結合度(>10のプロジェクト内インポート)P2Architecture
完全またはほぼ完全な重複P2Duplication
非推奨通知P2Deferred Work
一時的または回避策のマーカーP2Deferred Work
フレームワークアンチパターンP2Pattern Violations
実装結合テストP2Test Quality
「エラーが発生しない」ことのみをアサートするテストP2Test Quality
参照されていない関数、デッドブランチ、孤立ファイルP2Dead Code
深いネスト(>4レベル)P3Architecture
未使用のインポートP3Dead Code
TODO / FIXME コメントP3Deferred Work
コメントアウトされたコードP3Deferred Work
規約違反P3Pattern Violations
脆いテストアサーションP3Test Quality
チケットを参照するTODOP4Deferred Work

複雑さガイド

  • simple: 10行未満、1ファイル、修正が明白(未使用インポートの削除)。
  • moderate: 10~50行、2~3ファイル、簡単なリファクタリング(関数の抽出)。
  • complex: 50行以上、アーキテクチャ上の判断が必要、またはコードベース全体に影響(Godクラスの分割)。修正案に、実装前に設計や提案が必要であることを明記します。

Step 5: 収集と重複排除

  1. 発見事項をカテゴリ + ファイル + 行(±10行以内)でグループ化します。各グループでは、最も詳細な証拠を持つ発見事項を、そのグループ内で最も高い重要度で保持します。
  2. カテゴリ間:Dead CodeとArchitectureが同じクラスをフラグした場合はArchitectureの発見を保持します。複数のカテゴリが同じ行をフラグした場合はマージし、最も高い重要度を保持します。
  3. P0を最初に、次にP1~P4の順にソートします。

Step 6: 既存Issueの確認

このステップは --force が設定されている場合のみスキップします。各発見事項について、以下の条件を満たすオープンIssueを探します。

  • タイトルまたは本文に同じファイルパスが含まれている、AND
  • 同じ種類の問題、またはこの発見事項の±20行以内の行をカバーしている。

[TechDebt] というタイトルのIssue、またはtech-debtラベルが付いたIssueを優先しますが、同じ問題を明確に追跡しているオープンIssueがあればマッチとします。マッチした場合、発見事項を「already tracked as #N」とマークし、Issueを作成しません。同じファイル内の異なる種類の問題は別の発見事項とします。

Step 7: 確認、その後Issueを作成

--dry-run または gh_available=false の場合は作成をスキップし、レポートに直接進みます。

上限: --all がない限り最大20件。P0とP1をすべて埋め、次にP2(1ファイルに多数のIssueを作成するよりも、ファイル間で分散することを優先)、次にP3、次にP4の順にスロットを埋めます。--all で50件を超える場合は、時間がかかることを警告します。

ラベル: gh label list に存在するラベルのみを使用します。技術的負債に最も近いラベル(例:tech-debt、technical-debt、debt、refactor、chore)を選択し、リポジトリにそれらがあれば、重要度にマッチする優先度ラベルと種別ラベル(例:testing)も選択します。ユーザーに確認せずにラベルを作成しないでください。適切なラベルがない場合はその旨を伝え、ラベルなしでIssueを作成するか、ユーザーに tech-debt を作成するか尋ねます。

確認(必須): 作成前に、完全なリストを表示し、ユーザーの応答を待ちます。--yes が渡されていない限り、確認なしでIssueを作成してはいけません。

Will create X issues (labels: tech-debt, P2):

1. [P1] [TechDebt] Architecture: Split OrderService (612 lines, 27 public methods)
2. [P1] [TechDebt] Test Quality: Fix mock-only test in payment_test.py:45
3. [P2] [TechDebt] Duplication: Extract address validation (user.ts:40, account.ts:88)
...

Already tracked (skipped): 3. Over the cap (not filed): 12.
Proceed? You can also drop items by number or change labels.

ユーザーが行った編集を適用し、各Issueを作成します。各本文は単独で読み取れるようにし、このレポートを見ていない人でも理解できるようにします。

gh issue create \
  --title "[TechDebt] <カテゴリ>: <簡潔な説明>" \
  --label "<既存ラベル>" \
  --body "$(cat <<'EOF'
**Category:** <カテゴリ>
**Severity:** P<N>
**Location:** <ファイル:行>

## Problem
<説明>

## Evidence
```
<証拠>
```

## Suggested fix
<修正案>

**Complexity:** <simple|moderate|complex>

## Acceptance criteria
- <負債が解消されたことを確認する観測可能なチェック>
- The project's full test suite passes
EOF
)"

タイトルの例:

  • [TechDebt] Dead Code: Remove unused imports in format.ts:5-12
  • [TechDebt] Architecture: Split OrdersController (567 lines, 23 actions)
  • [TechDebt] Test Quality: Fix mock-only test in payment_service_test.go:45

gh issue create 呼び出しが失敗した場合は、エラーとコマンドをログに記録し、残りの処理を続行して、最後に「Created X issues, Y failed」と報告します。

リポジトリがGitHub Project Boardで作業を追跡している場合(エージェント指示の Issue tracking セクションに Mode: project とあるか、そのようなセクションがなく gh repo view --json projectsV2 でリンクされたボードが表示される場合)、新しいIssueに対して place-issues スキルを実行するオファーを出します。

Step 8: サマリーレポート

=== Tech Debt Discovery Report ===

Scope: [分析したパス]
Files analyzed: [件数]
Stack: [言語/フレームワーク/テストランナー]
Duration: [かかった時間]

## Summary
- Total findings: X | Issues created: Y | Already tracked: Z | Over cap: W
- By severity: P0: A, P1: B, P2: C, P3: D, P4: E

## Findings by Category

### Dead Code (X)
- [ ] #N: Remove unused imports in format.ts:5-12 (P3)

### Duplication (X)
- [ ] #N: Extract address validation (user.ts:40, account.ts:88) (P2)

### Architecture (X)
- [ ] #N: Split OrderService (612 lines, 27 public methods) (P1)

### Deferred Work (X)
- [ ] #N: Resolve TODO in billing.py:123 (P3)

### Pattern Violations (X)
- [ ] #N: Fix N+1 query risk in OrdersController#index (P2)

### Test Quality (X)
- [ ] #N: Fix mock-only test in payment_test.py:45 (P1)

## Already Tracked
- billing.py:100 TODO → #N

## Additional Findings (over the cap, not filed)
[リスト]
Run with --all to file the remaining X findings.

## Skipped (false positive or intentional)
- tests/fixtures/** : fixtures excluded
- TODO(#42) in conftest.py : has a linked ticket (P4)

## Analysis Status
- Dead Code: Complete
- ...
- Test Quality: Incomplete (truncated)

## Errors
[失敗したghコマンド]

--dry-run の場合は、Issue番号を [would create] に置き換えます。

原則

  1. 読み取り専用。 分析中にコードを変更しません。
  2. 保守的。 確信が持てない場合は、誤検知を報告するよりもスキップします。ノイズの多いレポートは無視されます。
  3. プロジェクトを尊重します。 フレームワークの規約(コールバック、デコレーター、依存性注入、規約ベースのルーティング)およびリポジトリで文書化された選択は負債ではありません。
  4. 証拠を最優先。 すべての発見事項は、ファイル、行、およびそれを証明するコードを引用します。
  5. 構造化された出力。 カテゴリ分析はJSONを返すため、マージと重複排除が確実に行われます。
  6. ユーザーが起票前に確認。 リストは常に最初に表示されます。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

関連スキル