Troubleshoot Skill
問題発生時の診断と解決をガイドするスキル。 VibeCoder が技術的な知識なしで問題を解決できるよう支援します。
トリガーフレーズ
このスキルは以下のフレーズで自動起動します：
- 「動かない」「エラーが出た」「壊れた」
- 「うまくいかない」「失敗した」
- 「なぜ？」「原因は？」
- "it's broken", "doesn't work", "error", "why?"
概要
問題が発生したとき、VibeCoder は技術的な詳細を理解する必要はありません。 このスキルが自動的に診断し、解決策を提示します。
診断フロー
Step 1: 症状の確認
🔍 何が起きましたか？ 簡単に教えてください： - 「画面が真っ白」 - 「ボタンが動かない」 - 「データが保存されない」
Step 2: 自動診断
# 環境チェック
node -v
npm -v
git status -sb
# エラーログ確認
npm run build 2>&1 | tail -20
npm test 2>&1 | tail -20
# 依存関係チェック
npm ls --depth=0Step 3: 問題カテゴリの特定
| カテゴリ | 症状 | 自動対応 |
|---|---|---|
| 依存関係 | Cannot find module | npm install |
| 型エラー | Type error | error-recovery agent |
| ビルドエラー | Build failed | error-recovery agent |
| ランタイム | 画面が表示されない | ログ分析 |
| 環境設定 | 接続エラー | 環境変数確認 |
| CI/CD | CI が落ちた、パイプライン失敗 | ci スキルに dispatch |
CI/CD 問題: CI 障害・テスト失敗・パイプライン問題を検出した場合、ciスキル（skills/ci/）に処理を委譲します。ci スキルはci-cd-fixerエージェントを使用して自動診断・修正を行います。
問題別対応
「ボタンが動かない / フォームが送信されない / UIが崩れる」
UIの不具合は、画面で再現して観測→修正→再検証するのが最短です。
- agent-browser を最優先で使う（インストール:
npm install -g agent-browser）# ページを開いてスナップショット取得 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/手順/期待値/実際） - スクリーンショット/動画 - コンソールログ/ネットワークログ
「画面が真っ白」
🔍 診断中...
考えられる原因:
1. ビルドエラー
2. JavaScript エラー
3. ルーティング問題
🔧 自動チェック:
- ビルドログを確認... ✅ エラーなし
- コンソールエラーを確認... ❌ エラー発見
💡 解決策:
「直して」と言ってください。自動修正を試みます。「npm install が失敗」
🔍 診断中...
エラー: `ERESOLVE unable to resolve dependency tree`
🔧 解決策:
1. キャッシュをクリア
2. node_modules を再インストール
実行してもいいですか？（はい/いいえ）「Git がおかしい」
🔍 診断中...
検出: マージコンフリクト発生
🔧 解決策:
1. コンフリクト箇所を表示
2. 解決方法を提案
「解決して」と言えば自動マージを試みます。VibeCoder向け応答パターン
パターン1: 自動修正可能
⚠️ 問題を検出しました
**問題**: モジュールが見つかりません
**原因**: 依存関係の未インストール
🔧 **自動修正します**
→ `npm install` を実行中...
✅ 修正完了！もう一度試してください。パターン2: 確認が必要
⚠️ 問題を検出しました
**問題**: 設定ファイルの変更が必要
**影響**: 動作に影響する可能性
🤔 **確認させてください**:
設定を変更しても大丈夫ですか？
→ 「変更して」で実行
→ 「説明して」で詳細を確認パターン3: エスカレーション
⚠️ 複雑な問題を検出しました
**問題**: {{問題の概要}}
**試した修正**: 3回失敗
🆘 **Cursor (PM) への相談をおすすめします**
以下を Cursor に共有してください:
- エラー内容: {{要約}}
- 試した対応: {{リスト}}
- 推定原因: {{分析}}
「報告書を作って」で共有用レポートを生成します。よくある質問への自動応答
| 質問 | 自動応答 |
|---|---|
| 「なぜエラーになった？」 | エラーログを分析して原因を説明 |
| 「どうすれば直る？」 | 具体的な解決手順を提示 |
| 「前は動いてたのに」 | git log で最近の変更を確認 |
| 「同じエラーが何度も」 | パターンを分析して根本対策を提案 |
診断コマンド
クイック診断
「診断して」
→ 全般的な健全性チェック
→ 問題があれば報告
→ なければ「問題なし」詳細診断
「詳しく診断して」
→ 依存関係チェック
→ ビルドテスト
→ テスト実行
→ 環境変数確認
→ 詳細レポート出力Claude Code 固有の診断（CC 2.1.49+）
複雑なセッション問題には /debug コマンドが有効です。
| 症状 | 推奨 |
|---|---|
| 「セッションがおかしい」 | /debug でセッション診断 |
| 「MCPが動かない」 | /debug で MCP 状態確認 |
| 「何度試してもダメ」 | /debug で詳細ログ出力 |
| 「コンテキストが変」 | /debug でコンテキスト情報取得 |
| 「認証エラー」 | claude auth status で認証状態確認 (CC 2.1.41+) |
| 「エージェントが動かない」 | claude agents list でエージェント定義確認 (CC 2.1.50+) |
| 「スキルが古い内容で動作する」 | /clear を実行してスキルキャッシュをリセット (CC v2.1.63+) |
エージェント診断（CC 2.1.50+）
CC 2.1.50 で claude agents CLI コマンドが追加されました:
claude agents list # 登録済みエージェントの一覧エージェントの spawn 失敗、Team 初期化エラーの診断に有用です。 Breezing で Implementer/Reviewer が起動しない場合に確認してください。
認証診断（CC 2.1.41+）
CC 2.1.41 で claude auth サブコマンドが追加されました:
claude auth status # 認証状態の確認
claude auth login # 再ログイン
claude auth logout # ログアウトAPI キーの問題や認証切れの診断に有用です。
VibeCoder 向け
🔍 より詳しい診断が必要な場合
「もっと詳しく診断して」と言われたら:
→ `/debug` コマンドの使用を推奨
/debug コマンドは以下を診断します:
- セッション状態
- MCP サーバー接続
- プラグイン設定
- メモリ使用状況
- エラーログの詳細
💡 使い方:
チャット欄で `/debug` と入力してくださいトラブルシューティング連携フロー
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 による問題検出
🔍 LSP 診断実行中...
📊 診断結果:
| ファイル | 行 | メッセージ |
|---------|-----|-----------|
| src/api/user.ts | 23 | 'userId' は undefined の可能性があります |
| src/components/Form.tsx | 45 | 型 'string' を型 'number' に割り当てることはできません |
→ 2件の問題を検出
→ 上記が「動かない」原因の可能性が高いGo-to-definition による原因追跡
🔍 原因追跡
エラー: 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 で変更影響を確認 |