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: スコープの決定
- パスが指定されている場合はそれを使用します。
--fullが指定されている場合は、上記の除外ルールでリポジトリをスキャンします。- それ以外の場合は、存在する主要なソースディレクトリとテストディレクトリを自動検出します(一般的なもの:
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.rb | Ruby on Rails |
manage.py または requirements / pyproject.toml に django | Django |
pyproject.toml / requirements.txt に fastapi または flask | Python Web |
package.json に next、react、vue、svelte、express、nestjs | JS/TS フレームワーク |
go.mod | Go |
Cargo.toml | Rust |
pom.xml / build.gradle* | JVM(SpringがあればSpring) |
composer.json に laravel/framework | Laravel |
*.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カテゴリ)について:
Analyzing [カテゴリ]... (X of N)とアナウンスします。references/categories.mdの該当カテゴリのチェックリストを、検出されたスタックに適応させて適用します。- 発見事項を以下のJSON形式で収集します。
[カテゴリ] 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」)。
重要度リファレンス
| パターン | 重要度 | カテゴリ |
|---|---|---|
| セキュリティ問題を隠すテスト | P0 | Test Quality |
| リソースアクセス時の認可チェック欠落 | P1 | Pattern Violations |
| Godクラス(>500行または>20のpublicメソッド) | P1 | Architecture |
| 循環依存 | P1 | Architecture |
| 到達不能コード | P1 | Dead Code |
| モックのみのテスト(テスト対象をモックしているテスト) | P1 | Test Quality |
| テスト対象をスタブ化してアサート | P1 | Test Quality |
| トートロジー的なテスト | P1 | Test Quality |
| 空のテスト本体 | P1 | Test Quality |
| 過剰なモック(テストの50%以上がセットアップ) | P1 | Test Quality |
| クラスの全インスタンスをスタブ化 | P1 | Test Quality |
| テスト間で共有される可変状態 | P1 | Test Quality |
| 長い関数(>50行) | P2 | Architecture |
| 高い結合度(>10のプロジェクト内インポート) | P2 | Architecture |
| 完全またはほぼ完全な重複 | P2 | Duplication |
| 非推奨通知 | P2 | Deferred Work |
| 一時的または回避策のマーカー | P2 | Deferred Work |
| フレームワークアンチパターン | P2 | Pattern Violations |
| 実装結合テスト | P2 | Test Quality |
| 「エラーが発生しない」ことのみをアサートするテスト | P2 | Test Quality |
| 参照されていない関数、デッドブランチ、孤立ファイル | P2 | Dead Code |
| 深いネスト(>4レベル) | P3 | Architecture |
| 未使用のインポート | P3 | Dead Code |
| TODO / FIXME コメント | P3 | Deferred Work |
| コメントアウトされたコード | P3 | Deferred Work |
| 規約違反 | P3 | Pattern Violations |
| 脆いテストアサーション | P3 | Test Quality |
| チケットを参照するTODO | P4 | Deferred Work |
複雑さガイド
- simple: 10行未満、1ファイル、修正が明白(未使用インポートの削除)。
- moderate: 10~50行、2~3ファイル、簡単なリファクタリング(関数の抽出)。
- complex: 50行以上、アーキテクチャ上の判断が必要、またはコードベース全体に影響(Godクラスの分割)。修正案に、実装前に設計や提案が必要であることを明記します。
Step 5: 収集と重複排除
- 発見事項をカテゴリ + ファイル + 行(±10行以内)でグループ化します。各グループでは、最も詳細な証拠を持つ発見事項を、そのグループ内で最も高い重要度で保持します。
- カテゴリ間:Dead CodeとArchitectureが同じクラスをフラグした場合はArchitectureの発見を保持します。複数のカテゴリが同じ行をフラグした場合はマージし、最も高い重要度を保持します。
- 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] に置き換えます。
原則
- 読み取り専用。 分析中にコードを変更しません。
- 保守的。 確信が持てない場合は、誤検知を報告するよりもスキップします。ノイズの多いレポートは無視されます。
- プロジェクトを尊重します。 フレームワークの規約(コールバック、デコレーター、依存性注入、規約ベースのルーティング)およびリポジトリで文書化された選択は負債ではありません。
- 証拠を最優先。 すべての発見事項は、ファイル、行、およびそれを証明するコードを引用します。
- 構造化された出力。 カテゴリ分析はJSONを返すため、マージと重複排除が確実に行われます。
- ユーザーが起票前に確認。 リストは常に最初に表示されます。