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=0

Step 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 診断実行中...

📊 診断結果:

→ 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 で変更影響を確認

詳細: docs/LSP_INTEGRATION.md