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. 結果をユーザーに報告する

報告フォーマット（通常モード）:

## dev-debug 結果

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

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

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

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

報告フォーマット（webtest モード）:

## 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 コメントに反映する

// 🟡 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) でルートを取得）