Troubleshoot Skill
問題発生時の診断と解決をガイドするスキル。 VibeCoder が技術的な知識なしで問題を解決できるよう支援します。
トリガーフレーズ
このスキルは以下のフレーズで自動起動します:
- •「動かない」「エラーが出た」「壊れた」
- •「うまくいかない」「失敗した」
- •「なぜ?」「原因は?」
- •"it's broken", "doesn't work", "error", "why?"
概要
問題が発生したとき、VibeCoder は技術的な詳細を理解する必要はありません。 このスキルが自動的に診断し、解決策を提示します。
診断フロー
Step 1: 症状の確認
🔍 何が起きましたか?
簡単に教えてください:
- •「画面が真っ白」
- •「ボタンが動かない」
- •「データが保存されない」
Step 2: 自動診断
bash
# 環境チェック node -v npm -v git status -sb # エラーログ確認 npm run build 2>&1 | tail -20 npm test 2>&1 | tail -20 # 依存関係チェック npm ls --depth=0
Step 3: 問題カテゴリの特定
| カテゴリ | 症状 | 自動対応 |
|---|---|---|
| 依存関係 | Cannot find module | npm install |
| 型エラー | Type error | error-recovery agent |
| ビルドエラー | Build failed | error-recovery agent |
| ランタイム | 画面が表示されない | ログ分析 |
| 環境設定 | 接続エラー | 環境変数確認 |
問題別対応
「ボタンが動かない / フォームが送信されない / UIが崩れる」
UIの不具合は、画面で再現して観測→修正→再検証するのが最短です。
- •agent-browser を最優先で使う(インストール:
npm install -g agent-browser)bash# ページを開いてスナップショット取得 agent-browser open https://example.com/target-page agent-browser snapshot -i -c # 要素参照でクリック・入力 agent-browser click @e1 agent-browser fill @e2 "test"
- •対象URLで再現 → スナップショット/コンソールを根拠に原因を絞る
- •ソースコード(UI/状態管理/API/バリデーション)を確認して修正
- •同じ手順で再現しないことを確認
- •参考:
docs/OPTIONAL_PLUGINS.md
- •agent-browser が使えない場合のフォールバック
- •MCP ブラウザツール(chrome-devtools, playwright)
- •再現手順(URL/手順/期待値/実際)
- •スクリーンショット/動画
- •コンソールログ/ネットワークログ
「画面が真っ白」
code
🔍 診断中... 考えられる原因: 1. ビルドエラー 2. JavaScript エラー 3. ルーティング問題 🔧 自動チェック: - ビルドログを確認... ✅ エラーなし - コンソールエラーを確認... ❌ エラー発見 💡 解決策: 「直して」と言ってください。自動修正を試みます。
「npm install が失敗」
code
🔍 診断中... エラー: `ERESOLVE unable to resolve dependency tree` 🔧 解決策: 1. キャッシュをクリア 2. node_modules を再インストール 実行してもいいですか?(はい/いいえ)
「Git がおかしい」
code
🔍 診断中... 検出: マージコンフリクト発生 🔧 解決策: 1. コンフリクト箇所を表示 2. 解決方法を提案 「解決して」と言えば自動マージを試みます。
VibeCoder向け応答パターン
パターン1: 自動修正可能
code
⚠️ 問題を検出しました **問題**: モジュールが見つかりません **原因**: 依存関係の未インストール 🔧 **自動修正します** → `npm install` を実行中... ✅ 修正完了!もう一度試してください。
パターン2: 確認が必要
code
⚠️ 問題を検出しました **問題**: 設定ファイルの変更が必要 **影響**: 動作に影響する可能性 🤔 **確認させてください**: 設定を変更しても大丈夫ですか? → 「変更して」で実行 → 「説明して」で詳細を確認
パターン3: エスカレーション
code
⚠️ 複雑な問題を検出しました
**問題**: {{問題の概要}}
**試した修正**: 3回失敗
🆘 **Cursor (PM) への相談をおすすめします**
以下を Cursor に共有してください:
- エラー内容: {{要約}}
- 試した対応: {{リスト}}
- 推定原因: {{分析}}
「報告書を作って」で共有用レポートを生成します。
よくある質問への自動応答
| 質問 | 自動応答 |
|---|---|
| 「なぜエラーになった?」 | エラーログを分析して原因を説明 |
| 「どうすれば直る?」 | 具体的な解決手順を提示 |
| 「前は動いてたのに」 | git log で最近の変更を確認 |
| 「同じエラーが何度も」 | パターンを分析して根本対策を提案 |
診断コマンド
クイック診断
code
「診断して」 → 全般的な健全性チェック → 問題があれば報告 → なければ「問題なし」
詳細診断
code
「詳しく診断して」 → 依存関係チェック → ビルドテスト → テスト実行 → 環境変数確認 → 詳細レポート出力
Claude Code 固有の診断(CC 2.1.30+)
複雑なセッション問題には /debug コマンドが有効です。
| 症状 | 推奨 |
|---|---|
| 「セッションがおかしい」 | /debug でセッション診断 |
| 「MCPが動かない」 | /debug で MCP 状態確認 |
| 「何度試してもダメ」 | /debug で詳細ログ出力 |
| 「コンテキストが変」 | /debug でコンテキスト情報取得 |
VibeCoder 向け
code
🔍 より詳しい診断が必要な場合 「もっと詳しく診断して」と言われたら: → `/debug` コマンドの使用を推奨 /debug コマンドは以下を診断します: - セッション状態 - MCP サーバー接続 - プラグイン設定 - メモリ使用状況 - エラーログの詳細 💡 使い方: チャット欄で `/debug` と入力してください
トラブルシューティング連携フロー
code
troubleshoot スキルでの診断
↓
一般的な問題を自動チェック
↓
┌─────────────────────────────────────────┐
│ 解決できた? │
├─────────────────────────────────────────┤
│ YES → 修正完了 │
│ NO → 複雑な問題の可能性 │
└─────────────────────────────────────────┘
↓
/debug コマンドを推奨
↓
セッション・MCP・設定の詳細診断
↓
診断結果をもとに解決策提示
/debug が特に有効なケース
| ケース | 理由 |
|---|---|
| 3回修正しても解決しない | 環境設定の問題の可能性 |
| MCP ツールが応答しない | MCP サーバー接続の診断が必要 |
| セッション再開後の動作不良 | セッション状態の確認が必要 |
| 他のプロジェクトでは動く | プロジェクト固有設定の問題 |
予防的アドバイス
問題を未然に防ぐため、以下をおすすめ:
- •定期的な
npm run build: 問題を早期発見 - •こまめなコミット: 問題発生時に戻しやすい
- •Plans.md の更新: 変更履歴を追跡可能に
注意事項
- •自動修正は3回まで試行
- •3回失敗したらエスカレーション
- •破壊的な操作は必ず確認を取る
- •修正履歴は session-log.md に記録
🔧 LSP 機能の活用
問題解決では LSP(Language Server Protocol)を活用して正確に原因を特定します。
LSP Diagnostics による問題検出
code
🔍 LSP 診断実行中... 📊 診断結果: | ファイル | 行 | メッセージ | |---------|-----|-----------| | src/api/user.ts | 23 | 'userId' は undefined の可能性があります | | src/components/Form.tsx | 45 | 型 'string' を型 'number' に割り当てることはできません | → 2件の問題を検出 → 上記が「動かない」原因の可能性が高い
Go-to-definition による原因追跡
code
🔍 原因追跡 エラー: Cannot read property 'name' of undefined 追跡: 1. src/pages/user.tsx:34 - user.name を参照 2. src/hooks/useUser.ts:12 - user を返す ← Go-to-definition 3. src/api/user.ts:8 - API レスポンスが null の可能性 → API エラー時のハンドリング不足が原因
VibeCoder 向けの使い方
| 症状 | LSP 活用 |
|---|---|
| 「動かない」 | Diagnostics でエラー箇所を特定 |
| 「どこがおかしい?」 | Go-to-definition で原因を追跡 |
| 「いつから壊れた?」 | Find-references で変更影響を確認 |