# Dev Debug

> This skill should be used when the user asks to "dev-debug", "テストが失敗する", "ビルドエラーを直して", "デバッグ", "debug failing tests", "fix build error", "エラーを修正", "コンパイルエラー", "環境の問題を解決". テスト失敗、ビルドエラー、環境問題など様々なエラーパターンをカテゴリ別に診断し、最小コンテキストで修正する。

- Skill: `classmethod/dev-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add classmethod/dev-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/classmethod/dev-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: classmethod (https://skillmd.com/u/classmethod)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/classmethod/dev-debug

---


# Dev Debug

テスト失敗、コンパイルエラー、環境問題など、様々なエラーパターンに対応する集中デバッグスキル。エラーをカテゴリ分類し、それぞれに最適な診断・修正戦略を適用する。最小コンテキストでの高速解決を目指す。

## 前提知識

### dev-*スキルフロー内の位置

```
dev-context → dev-plan → dev-impl → dev-verify
                              ↘ [dev-debug] ↗
                                     ↑
                              dev-webtest → [dev-debug webtest] → 「/dev-webtest retest で再テストしてください」
                                     ↑                                            │
                                     └──────── retest ────────────────────────────┘
```

dev-impl で解消できないエラーが発生した場合、dev-verify で問題が検出された場合、または dev-webtest で検出された画面系エラーの修正に使用する。

### 引数フォーマット

```
/dev-debug                           # 自動検出モード
/dev-debug "エラーメッセージや状況の説明"  # 手動指定モード
/dev-debug webtest                   # webtest エラー修正モード
```

## エラーカテゴリと対応戦略

### カテゴリ一覧

| カテゴリ | 例 | 診断アプローチ | 典型的な修正 |
|---------|---|-------------|-----------|
| **コンパイル/型エラー** | 型不一致、missing import、構文エラー | エラーメッセージの直接分析 | 型定義修正、import追加 |
| **テスト失敗** | assertion失敗、タイムアウト | 期待値と実際の差分分析 | ロジック修正 or テスト修正 |
| **ランタイムエラー** | null参照、パニック、未処理例外 | スタックトレース分析 | エラーハンドリング追加 |
| **環境・設定** | 依存関係エラー、設定ミス、パス問題 | 設定ファイル・環境変数チェック | 設定修正、依存追加 |
| **Lint/フォーマット** | スタイル違反、未使用変数 | Lint出力分析 | 自動修正 or コード調整 |
| **依存関係** | バージョン競合、パッケージ不足 | lock file/パッケージ分析 | バージョン調整、パッケージ追加 |
| **webtest エラー** | 視覚崩れ、a11y違反、レスポンシブ不備、フォームバリデーション不備、シナリオ失敗 | error.md の検出内容・再現手順を分析 | CSS/HTML修正、バリデーション追加、機能バグ修正 |

## ワークフロー

### Step 1: エラー情報の収集と分類

#### 自動検出モード（引数なし）

1. `docs/dev/context.md` からテスト実行コマンドを取得する
2. テストを実行してエラーを収集する
3. ビルドコマンドがある場合はビルドも実行する

#### 手動指定モード（引数あり、webtest 以外）

ユーザーが提供したエラー情報を分析する。

#### webtest モード（引数が `webtest`）

1. `docs/dev/webtests/errors/` を Glob で走査し、全 `error.md` を取得する
2. 各 error.md を Read し、frontmatter の `status: open` のものだけ収集する
3. 0件の場合 →「未解決の webtest エラーはありません」と報告して終了
4. `severity` 順にソートする（critical → major → minor）
5. 各エラーを Step 2 の webtest エラー診断 → Step 3 の修正・検証で順次処理する
6. 全エラー処理後、Step 4 で報告する（`/dev-webtest retest` での再テストを案内）

#### 分類判定

エラーメッセージのパターンマッチでカテゴリを判定する:

- `TypeError`, `SyntaxError`, `Cannot find module`, `missing import` → コンパイル/型エラー
- `AssertionError`, `expect(`, `assert`, `test failed` → テスト失敗
- `null`, `undefined`, `panic`, `NullPointerException`, `segfault` → ランタイムエラー
- `ENOENT`, `Permission denied`, `port already in use`, `env` → 環境・設定
- `eslint`, `prettier`, `clippy`, `unused variable` → Lint/フォーマット
- `ERESOLVE`, `version conflict`, `peer dependency` → 依存関係

### Step 2: カテゴリ別診断

#### コンパイル/型エラー

**最小コンテキスト**: エラー箇所のファイルのみ読み込む。

1. エラーメッセージから該当ファイルと行番号を特定する
2. 該当ファイルの関連部分を読み込む（Read tool の offset/limit を活用）
3. 型定義・インターフェースが関係する場合はそれも読み込む
4. 修正案を生成する

#### テスト失敗

**最小コンテキスト**: テストファイル + 対象実装ファイル。

1. 失敗テストのファイルと名称を特定する
2. テストファイルを読み込み、期待値を確認する
3. 対象の実装ファイルを読み込む
4. 期待値と実際の差分から原因を特定する
5. **判断**: テストが正しいか、実装が正しいかを判断する
   - テストが正しい場合 → 実装を修正
   - 実装が正しい場合 → テストを修正（ユーザーに確認を推奨）

#### ランタイムエラー

**最小コンテキスト**: スタックトレースに含まれるファイル。

1. スタックトレースからコールチェーンを特定する
2. 最も関連性の高いファイルから読み込む
3. null/undefined チェックの漏れ、例外ハンドリングの不足を特定する
4. ガード句やエラーハンドリングを追加する

#### 環境・設定

**最小コンテキスト**: 設定ファイル群。

1. Explore サブエージェント（haiku）で設定ファイルを探索する
2. 環境変数、パス設定、ポート設定等を確認する
3. 必要に応じてユーザーに手動操作を依頼する（AskUserQuestion）
4. AI単独で解決できない場合は明確に伝達する

#### Lint/フォーマット

**最小コンテキスト**: Lint出力のみ。

1. Lint/フォーマッターの自動修正コマンドがあれば実行する
2. 自動修正できない場合は手動で修正する
3. 修正後に再度Lintを実行して確認する

#### 依存関係

**最小コンテキスト**: パッケージ定義ファイル + lock file。

1. パッケージマネージャのエラー出力を分析する
2. 依存ツリーの競合を確認する
3. 互換性のあるバージョンを提案する
4. 必要に応じてユーザーに確認する（破壊的変更がある場合）

#### webtest エラー

**最小コンテキスト**: error.md + 関連するソースファイル。

error.md の `step` フィールドに応じて診断アプローチを切り替える:

| step | 主な修正対象 | 診断アプローチ |
|------|------------|-------------|
| `3-visual` | CSS、テンプレート | error.md の検出内容からレイアウト崩れの原因を特定し、CSS/テンプレートを修正 |
| `4-a11y` | HTML属性 | 不足している alt、label、aria 属性、heading 階層を特定して追加 |
| `5-responsive` | メディアクエリ、CSS | 問題のビューポートサイズに対応するメディアクエリやレイアウト CSS を修正 |
| `6-form` | バリデーションロジック | サーバー/クライアントのバリデーション処理を特定して修正。XSS/SQLi はサニタイズ処理を追加 |
| `2a-scenario` / `2b-monkey` | 機能実装 | 再現手順と期待される状態から機能バグを特定し、実装を修正 |

1. error.md の「検出内容」「再現手順」「期待される状態」を読み取る
2. Explore サブエージェント（haiku）で関連ソースファイルを特定する
3. 上記テーブルに従い修正案を生成する
4. 修正を適用する（Step 3 へ進む）

### Step 3: 修正の適用と検証

1. 修正案を適用する
2. カテゴリに応じた検証コマンドを実行する:
   - コンパイル/型エラー → ビルド実行
   - テスト失敗 → 失敗していたテストを実行
   - ランタイムエラー → 関連テストを実行
   - 環境・設定 → 環境チェックコマンド
   - Lint → Lint再実行
   - 依存関係 → インストール + ビルド
3. 修正が不十分な場合は Step 2 に戻る（**最大3サイクル**）

### Step 4: 回帰テストと報告

1. 修正対象のエラーが解消されたことを確認する
2. 全テストを実行し、回帰がないことを確認する
3. 結果をユーザーに報告する

**報告フォーマット**（通常モード）:
```markdown
## dev-debug 結果

### 検出されたエラー
- カテゴリ: [エラーカテゴリ]
- 原因: [根本原因の説明]

### 適用した修正
- [ファイル](パス): [修正内容]

### 検証結果
- 対象エラー: 解消
- 回帰テスト: passed / failed

### 確信度
- 🔵/🟡/🔴: [修正の確信度と理由]
```

**報告フォーマット**（webtest モード）:
```markdown
## dev-debug webtest 結果

### 修正したエラー
| # | error.md | severity | step | 修正内容 |
|---|----------|----------|------|---------|
| 1 | docs/dev/webtests/errors/.../ | critical | 2a-scenario | [修正内容] |

### 修正できなかったエラー
| # | error.md | severity | step | 理由 |
|---|----------|----------|------|------|
（なければ「なし」）

### 次のステップ
`/dev-webtest retest` で再テストし、修正が反映されているか確認してください。
```

## サイクル制限と escalation

3サイクルで解決できない場合:

1. これまでの診断結果と試行した修正をユーザーに報告する
2. 考えられる追加の原因仮説を提示する
3. ユーザーに次のアクションを相談する（AskUserQuestion）:
   - 追加情報の提供
   - 手動での確認依頼
   - アプローチの変更

## Intent コメントルール

コード修正時に、既存の Intent コメント（🔵🟡🔴）を維持し、修正箇所には適切に追加・更新する。

### 修正時の対応

- **既存の Intent コメントがある関数を修正する場合**: コメント内容が修正後も正確であれば維持する。修正により意図が変わった場合はコメントを更新する
- **新しい関数・メソッドを追加する場合**: dev-impl と同じルールで Intent コメントを付与する（public 関数は必須）
- **デバッグ修正特有の判断がある場合**: 修正理由を Intent コメントに反映する

```go
// 🟡 Intent: nil チェックを追加。元のコードではリポジトリが nil を返すケースが
//    未考慮だったため、エラーとして返却するガード句を追加。
func (s *TodoService) GetByID(ctx context.Context, id string) (*model.Todo, error) {
```

### 信号機の判定基準

- 🔵 **前工程指示**: タスクファイル・plan.md で指示された修正
- 🟡 **妥当な推測**: エラーパターンから推論した妥当な修正（ガード句追加、型修正等）
- 🔴 **AI推論補完**: 根本原因が不明確なまま適用した暫定修正

## ルール・制約

- **最小コンテキスト原則**: エラーに関連するファイルだけ読み込む。プロジェクト全体を読まない
- **サイクル制限**: 修正→検証のサイクルは最大3回
- **回帰防止**: 修正後は必ず全テストを実行する
- **環境問題の限界認識**: AI単独で解決できない環境問題（OS設定、ネットワーク等）はユーザーに明示的に伝達する
- **テスト修正の慎重さ**: テストを修正する場合はユーザーに確認を推奨する（テストが仕様を反映しているため）
- 探索作業は Explore サブエージェント（haiku）に委託し、メインコンテキストを保護する
- 500行ルール: 修正によりファイルが500行を超える場合は分割する
- Bash コマンドはプロジェクトルートの **絶対パス** を使用する（`$(git rev-parse --show-toplevel)` でルートを取得）