classmethod 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: エラー情報の収集と分類
自動検出モード（引数なし）
docs/dev/context.mdからテスト実行コマンドを取得する- テストを実行してエラーを収集する
- ビルドコマンドがある場合はビルドも実行する
手動指定モード（引数あり、webtest 以外）
ユーザーが提供したエラー情報を分析する。
webtest モード（引数が webtest）
docs/dev/webtests/errors/を Glob で走査し、全error.mdを取得する- 各 error.md を Read し、frontmatter の
status: openのものだけ収集する - 0件の場合 →「未解決の webtest エラーはありません」と報告して終了
severity順にソートする（critical → major → minor）- 各エラーを Step 2 の webtest エラー診断 → Step 3 の修正・検証で順次処理する
- 全エラー処理後、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: カテゴリ別診断
コンパイル/型エラー
最小コンテキスト: エラー箇所のファイルのみ読み込む。
- エラーメッセージから該当ファイルと行番号を特定する
- 該当ファイルの関連部分を読み込む（Read tool の offset/limit を活用）
- 型定義・インターフェースが関係する場合はそれも読み込む
- 修正案を生成する
テスト失敗
最小コンテキスト: テストファイル + 対象実装ファイル。
- 失敗テストのファイルと名称を特定する
- テストファイルを読み込み、期待値を確認する
- 対象の実装ファイルを読み込む
- 期待値と実際の差分から原因を特定する
- 判断: テストが正しいか、実装が正しいかを判断する
- テストが正しい場合 → 実装を修正
- 実装が正しい場合 → テストを修正（ユーザーに確認を推奨）
ランタイムエラー
最小コンテキスト: スタックトレースに含まれるファイル。
- スタックトレースからコールチェーンを特定する
- 最も関連性の高いファイルから読み込む
- null/undefined チェックの漏れ、例外ハンドリングの不足を特定する
- ガード句やエラーハンドリングを追加する
環境・設定
最小コンテキスト: 設定ファイル群。
- Explore サブエージェント（haiku）で設定ファイルを探索する
- 環境変数、パス設定、ポート設定等を確認する
- 必要に応じてユーザーに手動操作を依頼する（AskUserQuestion）
- AI単独で解決できない場合は明確に伝達する
Lint/フォーマット
最小コンテキスト: Lint出力のみ。
- Lint/フォーマッターの自動修正コマンドがあれば実行する
- 自動修正できない場合は手動で修正する
- 修正後に再度Lintを実行して確認する
依存関係
最小コンテキスト: パッケージ定義ファイル + lock file。
- パッケージマネージャのエラー出力を分析する
- 依存ツリーの競合を確認する
- 互換性のあるバージョンを提案する
- 必要に応じてユーザーに確認する（破壊的変更がある場合）
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 |
機能実装 | 再現手順と期待される状態から機能バグを特定し、実装を修正 |
- error.md の「検出内容」「再現手順」「期待される状態」を読み取る
- Explore サブエージェント（haiku）で関連ソースファイルを特定する
- 上記テーブルに従い修正案を生成する
- 修正を適用する（Step 3 へ進む）
Step 3: 修正の適用と検証
- 修正案を適用する
- カテゴリに応じた検証コマンドを実行する:
- コンパイル/型エラー → ビルド実行
- テスト失敗 → 失敗していたテストを実行
- ランタイムエラー → 関連テストを実行
- 環境・設定 → 環境チェックコマンド
- Lint → Lint再実行
- 依存関係 → インストール + ビルド
- 修正が不十分な場合は Step 2 に戻る（最大3サイクル）
Step 4: 回帰テストと報告
- 修正対象のエラーが解消されたことを確認する
- 全テストを実行し、回帰がないことを確認する
- 結果をユーザーに報告する
報告フォーマット（通常モード）:
## 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サイクルで解決できない場合:
- これまでの診断結果と試行した修正をユーザーに報告する
- 考えられる追加の原因仮説を提示する
- ユーザーに次のアクションを相談する（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)でルートを取得）