troubleshoot

Original source / Raw SKILL.md

---
name: troubleshoot
description: "Guides diagnosis and resolution when problems occur. Use when user mentions 動かない, エラーが出た, 壊れた, うまくいかない, broken, doesn't work, error. Do NOT load for: 正常なビルド, 新機能実装, レビュー."
allowed-tools: ["Read", "Grep", "Bash"]
context: fork
---

# 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の不具合は、**画面で再現して観測→修正→再検証**するのが最短です。

1. **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`
2. **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 で最近の変更を確認 |
| 「同じエラーが何度も」 | パターンを分析して根本対策を提案 |

---

## 診断コマンド

### クイック診断

```
「診断して」
→ 全般的な健全性チェック
→ 問題があれば報告
→ なければ「問題なし」
```

### 詳細診断

```
「詳しく診断して」
→ 依存関係チェック
→ ビルドテスト
→ テスト実行
→ 環境変数確認
→ 詳細レポート出力
```

---

## 予防的アドバイス

問題を未然に防ぐため、以下をおすすめ：

1. **定期的な `npm run build`**: 問題を早期発見
2. **こまめなコミット**: 問題発生時に戻しやすい
3. **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 で変更影響を確認 |

詳細: [docs/LSP_INTEGRATION.md](../../docs/LSP_INTEGRATION.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../../docs/LSP_INTEGRATION.md

```markdown
# LSP Integration Guide

Claude Code の LSP（Language Server Protocol）機能を活用するためのガイドです。

---

## LSP 機能の概要

Claude Code v2.0.74+ で利用可能な LSP 機能：

| 機能 | 説明 | 活用シーン |
|------|------|-----------|
| **Go-to-definition** | シンボルの定義元へジャンプ | コード理解、影響範囲調査 |
| **Find-references** | シンボルの全使用箇所を検索 | リファクタリング前の影響分析 |
| **Rename** | シンボル名を一括変更 | 安全なリネーム操作 |
| **Diagnostics** | コードの問題を検出 | ビルド前の問題検出、レビュー |
| **Hover** | シンボルの型情報・ドキュメント表示 | コード理解 |
| **Completions** | コード補完候補の提示 | 実装作業 |

### 対応言語

- TypeScript / JavaScript
- Python
- Rust
- Go
- C/C++
- Ruby
- PHP
- C#
- Swift
- Java
- HTML/CSS

---

## ゼロからのセットアップ（推奨）

LSP を使うには **2つのもの** が必要です:

1. **言語サーバー** - 実際にコード解析を行うプログラム
2. **LSP プラグイン** - Claude Code と言語サーバーを接続

### Step 1: 言語サーバーをインストール

| 言語 | Language Server | インストールコマンド |
|------|-----------------|---------------------|
| **TypeScript/JS** | typescript-language-server | `npm install -g typescript typescript-language-server` |
| **Python** | pyright | `pip install pyright` または `npm install -g pyright` |
| **Rust** | rust-analyzer | [公式手順](https://rust-analyzer.github.io/manual.html#installation) |
| **Go** | gopls | `go install golang.org/x/tools/gopls@latest` |
| **C/C++** | clangd | macOS: `brew install llvm` / Ubuntu: `apt install clangd` |

### Step 2: 公式 LSP プラグインをインストール

**プロジェクトで使用する言語に必要なプラグインのみ**インストールしてください。

```bash
# 例: TypeScript/JavaScript プロジェクトの場合
claude plugin install typescript-lsp

# 例: Python プロジェクトの場合
claude plugin install pyright-lsp

# 例: Go プロジェクトの場合
claude plugin install gopls-lsp
```

**どのプラグインが必要か分からない場合**:
- `/plugin` コマンドで "lsp" を検索して、プロジェクトの言語に該当するものを選択
- または `/lsp-setup` コマンドで自動検出・提案を受ける

**利用可能な公式プラグイン**: typescript-lsp, pyright-lsp, rust-analyzer-lsp, gopls-lsp, clangd-lsp, jdtls-lsp, swift-lsp, lua-lsp, php-lsp, csharp-lsp（詳細は下記「公式LSPプラグイン一覧」参照）

### Step 3: Claude Code を起動

```bash
claude
```

**これで完了！** Go-to-definition、Find-references、Diagnostics が使えるようになります。

---

## 公式 LSP プラグイン一覧

以下の言語向けに公式LSPプラグインが提供されています。**プロジェクトで使用する言語に必要なものだけ**インストールしてください。

| プラグイン | 言語 | 必要な言語サーバー |
|-----------|------|-------------------|
| `typescript-lsp` | TypeScript/JS | typescript-language-server |
| `pyright-lsp` | Python | pyright |
| `rust-analyzer-lsp` | Rust | rust-analyzer |
| `gopls-lsp` | Go | gopls |
| `clangd-lsp` | C/C++ | clangd |
| `jdtls-lsp` | Java | jdtls |
| `swift-lsp` | Swift | sourcekit-lsp |
| `lua-lsp` | Lua | lua-language-server |
| `php-lsp` | PHP | intelephense |
| `csharp-lsp` | C# | omnisharp |

**インストール方法**:
```bash
# 例: TypeScript/JavaScript プロジェクトの場合
claude plugin install typescript-lsp

# 例: Python プロジェクトの場合
claude plugin install pyright-lsp
```

または `/plugin` コマンドで "lsp" を検索して、該当言語のプラグインをインストール。

> **重要**: プラグインは言語サーバーのバイナリを**含みません**。Step 1 で言語サーバーを別途インストールしてください。

> **迷ったら**: `/lsp-setup` コマンドが、プロジェクトの言語を自動検出して必要なプラグインを提案します。

---

## 既存プロジェクトへの導入

既存プロジェクトに LSP を追加するには `/lsp-setup` コマンドを使用:

```
/lsp-setup
```

このコマンドは:
1. プロジェクトの言語を自動検出
2. 必要な言語サーバーのインストール確認・実行
3. 公式プラグインのインストール
4. 動作確認


---

## VibeCoder 向けの使い方

技術的な詳細を知らなくても、自然な言葉で LSP 機能を活用できます：

| 言いたいこと | 言い方 |
|-------------|--------|
| 定義を見たい | 「この関数の定義はどこ？」「`handleSubmit` の中身を見せて」 |
| 使用箇所を調べたい | 「この変数はどこで使われてる？」「`userId` の参照箇所を探して」 |
| 名前を変えたい | 「`getData` を `fetchUserData` にリネームして」 |
| 問題を検出したい | 「このファイルに問題ある？」「エラーをチェックして」 |
| 型情報を知りたい | 「この変数の型は何？」 |

---

## コマンド・スキルでの LSP 活用

### `/work` - 実装時

```
LSP 活用ポイント:
- 定義ジャンプで既存コードの理解を高速化
- 参照検索で影響範囲を事前把握
- 診断で実装中のエラーを即座に検出
```

### `/harness-review` - レビュー時

```
LSP 活用ポイント:
- Diagnostics で型エラー・未使用変数を自動検出
- Find-references で変更の影響範囲を確認
- 静的解析結果をレビュー観点に追加
```

### `/refactor` - リファクタリング時

```
LSP 活用ポイント:
- Rename でシンボルを安全に一括変更
- Find-references で漏れのない変更を保証
- Diagnostics で変更後の問題を即座に検出
```

### `/troubleshoot` - 問題解決時

```
LSP 活用ポイント:
- Diagnostics でエラー箇所を正確に特定
- Go-to-definition で問題のあるコードの原因を追跡
- 型情報で期待値と実際の不一致を発見
```

### `/validate` - 検証時

```
LSP 活用ポイント:
- プロジェクト全体の Diagnostics を実行
- 型エラー・警告の一覧を生成
- ビルド前に問題を検出
```

---

## LSP 診断の出力形式

```
📊 LSP 診断結果

ファイル: src/components/UserForm.tsx

| 行 | 重要度 | メッセージ |
|----|--------|-----------|
| 15 | Error | 型 'string' を型 'number' に割り当てることはできません |
| 23 | Warning | 'tempData' は宣言されていますが、使用されていません |
| 42 | Info | この条件は常に true です |

合計: エラー 1件 / 警告 1件 / 情報 1件
```

---

## LSP と Grep の使い分け

LSP と Grep はそれぞれ得意分野が異なります。適切に使い分けることで効率が上がります。

### 使い分け早見表

| 目的 | 推奨 | 理由 |
|------|------|------|
| シンボルの定義を探す | **LSP** | スコープを理解し、同名の別変数を区別 |
| シンボルの参照箇所を探す | **LSP** | 意味論的に正確な参照のみ抽出 |
| 変数・関数のリネーム | **LSP** | 漏れなく一括変更、安全 |
| 型エラー・構文エラー検出 | **LSP** | ビルド前に検出可能 |
| 文字列リテラル内を検索 | **Grep** | LSP はコード構造のみ対象 |
| コメント内を検索 | **Grep** | `TODO:` や `FIXME:` など |
| 正規表現パターン検索 | **Grep** | 柔軟なマッチング |
| 設定ファイル・ドキュメント | **Grep** | LSP はコードのみ対象 |
| LSP 非対応言語 | **Grep** | フォールバック |

### 具体例

```
❓「userId 変数はどこで使われてる？」
→ LSP Find-references（別スコープの userId を除外）

❓「"userId" という文字列はどこに書いてある？」
→ Grep（API レスポンス、コメント、ログも含む）

❓「TODO: を全部探して」
→ Grep（コメント内のテキスト）

❓「fetchUser を fetchUserById に変えたい」
→ LSP Rename（確実に全箇所変更）

❓「API エンドポイント /api/users を探して」
→ Grep（文字列リテラル検索）
```

### VibeCoder 向けの判断基準

| こう聞かれたら | 使うツール |
|---------------|-----------|
| 「この関数の定義はどこ？」 | LSP |
| 「この変数はどこで使われてる？」 | LSP |
| 「〇〇 を △△ にリネームして」 | LSP |
| 「"〇〇" という文字列を探して」 | Grep |
| 「TODO を全部リストして」 | Grep |
| 「〇〇 というテキストがどこにあるか」 | Grep |

---

## LSP 活用のベストプラクティス

### 1. 実装前に定義を確認

```
実装前:
1. 関連するシンボルの定義を LSP で確認
2. 既存のパターンを把握
3. 影響範囲を Find-references で調査
```

### 2. 変更後に診断を実行

```
変更後:
1. LSP Diagnostics を実行
2. エラー・警告を確認
3. 問題があれば即座に修正
```

### 3. リファクタリングは LSP Rename を使用

```
リファクタリング:
1. 変更対象を Find-references で確認
2. LSP Rename で一括変更
3. Diagnostics で問題がないことを確認
```

---

## Phase0: LSP tool_name の確認（開発者向け）

公式LSPプラグインの実際の `tool_name` を確認するには、Phase0ログを使用します。

### Phase0ログの有効化

Phase0ログはデフォルトで**無効**になっています。tool_name を確認する際のみ、環境変数で有効化してください。

```bash
# Phase0ログを有効化してClaude Codeを起動
CC_HARNESS_PHASE0_LOG=1 claude

# または、現在のセッションで有効化
export CC_HARNESS_PHASE0_LOG=1
claude
```

**重要**: tool_name確定後は、必ずPhase0ログを無効化してください（ログ肥大化防止）。

```bash
# Phase0ログを無効化（デフォルト状態に戻す）
unset CC_HARNESS_PHASE0_LOG
```

### 手順

1. **Phase0ログを有効化してセッション開始後、LSPツールを1回実行**:
   - 例: TypeScriptファイルで definition, references, diagnostics 等を実行

2. **tool-events.jsonl を確認**:
   ```bash
   cat .claude/state/tool-events.jsonl | grep -i lsp
   ```

3. **tool_name の検出条件を確認・調整**:
   - **現在の実装**: `scripts/posttooluse-log-toolname.sh` が `grep -iq "lsp"` で tool_name に "lsp" が含まれるかチェック
   - **tool_name が想定と異なる場合** (例: "lsp" を含まない名前の場合):
     - `scripts/posttooluse-log-toolname.sh` の LSP 検出条件（line 164付近）を更新:
       ```bash
       # 例: tool_name が "TypeScriptLSP" の場合
       if echo "$TOOL_NAME" | grep -iq "lsp\|TypeScriptLSP"; then
       ```
   - **matcher依存を回避**: PostToolUse は `matcher: "*"` で全ツールを観測するため、matcher設定は不要

4. **Phase0ログを無効化**:
   ```bash
   unset CC_HARNESS_PHASE0_LOG
   ```

### 想定される tool_name パターン

- `"LSP"` - 基本的なLSPツール
- `"typescript-lsp"` - 言語別プラグイン名
- `"LSP:definition"` - 操作別ツール名

いずれも "lsp" を含むため、デフォルトの検出条件（`grep -iq "lsp"`）で対応可能です。

**注意**: Phase0ログは最小フィールドのみ記録（tool_name, ts, session_id, prompt_seq）し、tool_input/tool_response は保存しません（漏洩リスク回避）。

---

## トラブルシューティング

### LSP が動作しない場合

1. 公式LSPプラグインがインストールされているか確認
2. 言語サーバーがインストールされているか確認（例: `which typescript-language-server`, `which pyright`）
3. `/lsp-setup` コマンドで設定を確認

### 診断結果が表示されない場合

1. 対応言語かどうかを確認
2. プロジェクトの設定ファイル（tsconfig.json 等）が正しいか確認
3. `restart_lsp_server` で言語サーバーを再起動

---

## 関連ドキュメント

- [ARCHITECTURE.md](./ARCHITECTURE.md) - プロジェクト全体の設計
- [OPTIONAL_PLUGINS.md](./OPTIONAL_PLUGINS.md) - オプションプラグインについて

```