troubleshoot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Troubleshoot Skill

問題発生時の診断と解決をガイドするスキル。 VibeCoder が技術的な知識なしで問題を解決できるよう支援します。

A skill that guides diagnosis and resolution when issues occur. It helps VibeCoder resolve problems without requiring technical knowledge.

トリガーフレーズ

Trigger Phrases

このスキルは以下のフレーズで自動起動します：

「動かない」「エラーが出た」「壊れた」
「うまくいかない」「失敗した」
「なぜ？」「原因は？」
"it's broken", "doesn't work", "error", "why?"

This skill automatically activates for the following phrases:

"It doesn't work", "An error occurred", "It's broken"
"It didn't go well", "It failed"
"Why?", "What's the cause?"
"it's broken", "doesn't work", "error", "why?"

概要

Overview

問題が発生したとき、VibeCoder は技術的な詳細を理解する必要はありません。このスキルが自動的に診断し、解決策を提示します。

When an issue occurs, VibeCoder doesn't need to understand technical details. This skill automatically diagnoses and presents solutions.

診断フロー

Diagnosis Flow

Step 1: 症状の確認

Step 1: Confirm Symptoms

🔍 何が起きましたか？

簡単に教えてください：

「画面が真っ白」

「ボタンが動かない」

「データが保存されない」

🔍 What happened?

Please tell us briefly:

"The screen is completely white"

"The button won't work"

"Data isn't saving"

Step 2: 自動診断

Step 2: Automatic Diagnosis

bash

undefined

bash

undefined

環境チェック

node -v npm -v git status -sb

エラーログ確認

npm run build 2>&1 | tail -20 npm test 2>&1 | tail -20

依存関係チェック

npm ls --depth=0

undefined

npm ls --depth=0

undefined

Step 3: 問題カテゴリの特定

Step 3: Identify Problem Category

カテゴリ	症状	自動対応
依存関係	`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
エージェントを使用して自動診断・修正を行います。

Category	Symptoms	Automatic Response
Dependencies	`Cannot find module`	`npm install`
Type Errors	`Type error`	error-recovery agent
Build Errors	`Build failed`	error-recovery agent
Runtime	Screen not displaying	Log analysis
Environment Settings	Connection errors	Environment variable check
CI/CD	CI failed, pipeline failure	Dispatch to ci skill

CI/CD Issues: When CI failures, test failures, or pipeline issues are detected, the process is delegated to the
ci
skill located at
skills/ci/
. The ci skill uses the
ci-cd-fixer
agent to perform automatic diagnosis and correction.

問題別対応

Issue-Specific Solutions

「ボタンが動かない / フォームが送信されない / UIが崩れる」

"Buttons won't work / Forms won't submit / UI is broken"

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/手順/期待値/実際）
- スクリーンショット/動画
- コンソールログ/ネットワークログ

For UI issues, the fastest way is to reproduce and observe on the screen → fix → re-verify.

Prioritize using agent-browser (Installation:

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"

Reproduce on the target URL → Narrow down the cause based on snapshots/console logs
Check source code (UI/state management/API/validation) and fix
Verify the issue no longer reproduces using the same steps
Reference:
```
docs/OPTIONAL_PLUGINS.md
```

Fallback if agent-browser is unavailable
- MCP browser tools (chrome-devtools, playwright)
- Reproduction steps (URL/steps/expected result/actual result)
- Screenshots/videos
- Console logs/network logs

「画面が真っ白」

"Screen is completely white"

🔍 診断中...

考えられる原因:
1. ビルドエラー
2. JavaScript エラー
3. ルーティング問題

🔧 自動チェック:
- ビルドログを確認... ✅ エラーなし
- コンソールエラーを確認... ❌ エラー発見

💡 解決策:
「直して」と言ってください。自動修正を試みます。

🔍 診断中...

考えられる原因:
1. ビルドエラー
2. JavaScript エラー
3. ルーティング問題

🔧 自動チェック:
- ビルドログを確認... ✅ エラーなし
- コンソールエラーを確認... ❌ エラー発見

💡 解決策:
「直して」と言ってください。自動修正を試みます。

Translated content for the above block:

🔍 Diagnosing...

Possible causes:
1. Build error
2. JavaScript error
3. Routing issue

🔧 Automatic checks:
- Checking build logs... ✅ No errors
- Checking console errors... ❌ Error found

💡 Solution:
Say "Fix it" to attempt automatic correction.

「npm install が失敗」

"npm install failed"

🔍 診断中...

エラー: `ERESOLVE unable to resolve dependency tree`

🔧 解決策:
1. キャッシュをクリア
2. node_modules を再インストール

実行してもいいですか？（はい/いいえ）

🔍 Diagnosing...

Error: `ERESOLVE unable to resolve dependency tree`

🔧 Solutions:
1. Clear cache
2. Reinstall node_modules

Can I execute these steps? (Yes/No)

「Git がおかしい」

"Git is behaving strangely"

🔍 診断中...

検出: マージコンフリクト発生

🔧 解決策:
1. コンフリクト箇所を表示
2. 解決方法を提案

「解決して」と言えば自動マージを試みます。

🔍 Diagnosing...

Detected: Merge conflict occurred

🔧 Solutions:
1. Show conflict locations
2. Propose resolution methods

Say "Resolve it" to attempt automatic merging.

VibeCoder向け応答パターン

Response Patterns for VibeCoder

パターン1: 自動修正可能

Pattern 1: Automatically Fixable

⚠️ 問題を検出しました

**問題**: モジュールが見つかりません
**原因**: 依存関係の未インストール

🔧 **自動修正します**
→ `npm install` を実行中...
✅ 修正完了！もう一度試してください。

⚠️ Issue detected

**Problem**: Module not found
**Cause**: Dependencies not installed

🔧 **Automatic fix in progress**
→ Executing `npm install`...
✅ Fix completed! Please try again.

パターン2: 確認が必要

Pattern 2: Confirmation Required

⚠️ 問題を検出しました

**問題**: 設定ファイルの変更が必要
**影響**: 動作に影響する可能性

🤔 **確認させてください**:
設定を変更しても大丈夫ですか？

→ 「変更して」で実行
→ 「説明して」で詳細を確認

⚠️ Issue detected

**Problem**: Configuration file needs to be changed
**Impact**: May affect functionality

🤔 **Please confirm**:
Is it okay to modify the configuration?

→ Say "Change it" to execute
→ Say "Explain it" to check details

パターン3: エスカレーション

Pattern 3: Escalation

⚠️ 複雑な問題を検出しました

**問題**: {{問題の概要}}
**試した修正**: 3回失敗

🆘 **Cursor (PM) への相談をおすすめします**

以下を Cursor に共有してください:
- エラー内容: {{要約}}
- 試した対応: {{リスト}}
- 推定原因: {{分析}}

「報告書を作って」で共有用レポートを生成します。

⚠️ Complex issue detected

**Problem**: {{Issue summary}}
**Fix attempts made**: 3 failures

🆘 **Recommended to consult Cursor (PM)**

Please share the following with Cursor:
- Error details: {{Summary}}
- Attempted fixes: {{List}}
- Estimated cause: {{Analysis}}

Say "Create a report" to generate a sharing report.

よくある質問への自動応答

Automatic Responses to Common Questions

質問	自動応答
「なぜエラーになった？」	エラーログを分析して原因を説明
「どうすれば直る？」	具体的な解決手順を提示
「前は動いてたのに」	git log で最近の変更を確認
「同じエラーが何度も」	パターンを分析して根本対策を提案

Question	Automatic Response
"Why did I get an error?"	Analyze error logs and explain the cause
"How do I fix it?"	Present specific resolution steps
"It worked before, why not now?"	Check recent changes using git log
"I keep getting the same error"	Analyze patterns and propose root cause solutions

診断コマンド

Diagnosis Commands

クイック診断

Quick Diagnosis

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

"Diagnose"
→ General health check
→ Report issues if any
→ Reply "No issues found" if none

詳細診断

Detailed Diagnosis

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

"Diagnose in detail"
→ Dependency check
→ Build test
→ Test execution
→ Environment variable check
→ Output detailed report

Claude Code 固有の診断（CC 2.1.49+）

Claude Code-Specific Diagnosis (CC 2.1.49+)

複雑なセッション問題には

/debug

コマンドが有効です。

症状	推奨
「セッションがおかしい」	`/debug` でセッション診断
「MCPが動かない」	`/debug` で MCP 状態確認
「何度試してもダメ」	`/debug` で詳細ログ出力
「コンテキストが変」	`/debug` でコンテキスト情報取得
「認証エラー」	`claude auth status` で認証状態確認 (CC 2.1.41+)

For complex session issues, the

/debug

command is effective.

Symptom	Recommendation
"Session is behaving strangely"	Use `/debug` for session diagnosis
"MCP isn't working"	Use `/debug` to check MCP status
"It still doesn't work after multiple attempts"	Use `/debug` to output detailed logs
"Context is odd"	Use `/debug` to get context information
"Authentication error"	Check authentication status with `claude auth status` (CC 2.1.41+)

認証診断（CC 2.1.41+）

Authentication Diagnosis (CC 2.1.41+)

CC 2.1.41 で

claude auth

サブコマンドが追加されました:

bash

claude auth status   # 認証状態の確認
claude auth login    # 再ログイン
claude auth logout   # ログアウト

API キーの問題や認証切れの診断に有用です。

The

claude auth

subcommand was added in CC 2.1.41:

bash

claude auth status   # 認証状態の確認
claude auth login    # 再ログイン
claude auth logout   # ログアウト

Useful for diagnosing API key issues and expired authentication.

VibeCoder 向け

For VibeCoder

🔍 より詳しい診断が必要な場合

「もっと詳しく診断して」と言われたら:
→ `/debug` コマンドの使用を推奨

/debug コマンドは以下を診断します:
- セッション状態
- MCP サーバー接続
- プラグイン設定
- メモリ使用状況
- エラーログの詳細

💡 使い方:
チャット欄で `/debug` と入力してください

🔍 When more detailed diagnosis is needed

If told "Diagnose in more detail":
→ Recommend using the `/debug` command

/debug command diagnoses the following:
- Session status
- MCP server connection
- Plugin settings
- Memory usage
- Detailed error logs

💡 How to use:
Enter `/debug` in the chat box

トラブルシューティング連携フロー

Troubleshooting Collaboration Flow

troubleshoot スキルでの診断
    ↓
一般的な問題を自動チェック
    ↓
┌─────────────────────────────────────────┐
│  解決できた？                            │
├─────────────────────────────────────────┤
│  YES → 修正完了                         │
│  NO  → 複雑な問題の可能性               │
└─────────────────────────────────────────┘
    ↓
/debug コマンドを推奨
    ↓
セッション・MCP・設定の詳細診断
    ↓
診断結果をもとに解決策提示

troubleshoot skill diagnosis
    ↓
Automatic check for common issues
    ↓
┌─────────────────────────────────────────┐
│  Issue resolved?                        │
├─────────────────────────────────────────┤
│  YES → Fix completed                     │
│  NO → Possible complex issue             │
└─────────────────────────────────────────┘
    ↓
Recommend `/debug` command
    ↓
Detailed diagnosis of session, MCP, and settings
    ↓
Propose solutions based on diagnosis results

/debug

が特に有効なケース

Cases Where

/debug

Is Particularly Effective

ケース	理由
3回修正しても解決しない	環境設定の問題の可能性
MCP ツールが応答しない	MCP サーバー接続の診断が必要
セッション再開後の動作不良	セッション状態の確認が必要
他のプロジェクトでは動く	プロジェクト固有設定の問題

Case	Reason
Issue not resolved after 3 fix attempts	Possible environment configuration issue
MCP tools not responding	Need to diagnose MCP server connection
Malfunction after resuming session	Need to check session status
Works in other projects	Possible project-specific configuration issue

予防的アドバイス

Preventive Advice

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

定期的な
npm run build
: 問題を早期発見
こまめなコミット: 問題発生時に戻しやすい
Plans.md の更新: 変更履歴を追跡可能に

To prevent issues, we recommend the following:

Regularly run
npm run build
: Detect issues early
Frequent commits: Easy to revert if issues occur
Update Plans.md: Enable tracking of change history

注意事項

Notes

自動修正は3回まで試行
3回失敗したらエスカレーション
破壊的な操作は必ず確認を取る
修正履歴は session-log.md に記録

Automatic fixes are attempted up to 3 times
Escalate if 3 attempts fail
Always confirm before performing destructive operations
Record fix history in session-log.md

🔧 LSP 機能の活用

🔧 Utilizing LSP Features

問題解決では LSP（Language Server Protocol）を活用して正確に原因を特定します。

For problem-solving, use LSP (Language Server Protocol) to accurately identify the cause.

LSP Diagnostics による問題検出

Issue Detection via LSP Diagnostics

🔍 LSP 診断実行中...

📊 診断結果:

| ファイル | 行 | メッセージ |
|---------|-----|-----------|
| src/api/user.ts | 23 | 'userId' は undefined の可能性があります |
| src/components/Form.tsx | 45 | 型 'string' を型 'number' に割り当てることはできません |

→ 2件の問題を検出
→ 上記が「動かない」原因の可能性が高い

🔍 Running LSP diagnostics...

📊 Diagnosis results:

| File | Line | Message |
|---------|-----|-----------|
| src/api/user.ts | 23 | 'userId' may be undefined |
| src/components/Form.tsx | 45 | Type 'string' cannot be assigned to type 'number' |

→ 2 issues detected
→ The above are highly likely to be the cause of "it doesn't work"

Go-to-definition による原因追跡

Cause Tracking via 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 エラー時のハンドリング不足が原因

🔍 Tracking cause

Error: Cannot read property 'name' of undefined

Tracking:
1. src/pages/user.tsx:34 - Referencing user.name
2. src/hooks/useUser.ts:12 - Returns user ← Go-to-definition
3. src/api/user.ts:8 - API response may be null

→ Cause is insufficient handling of API errors

VibeCoder 向けの使い方

Usage Guide for VibeCoder

症状	LSP 活用
「動かない」	Diagnostics でエラー箇所を特定
「どこがおかしい？」	Go-to-definition で原因を追跡
「いつから壊れた？」	Find-references で変更影響を確認

詳細: docs/LSP_INTEGRATION.md

Symptom	LSP Utilization
"It doesn't work"	Identify error locations with Diagnostics
"What's wrong?"	Track causes with Go-to-definition
"When did it break?"	Check change impacts with Find-references

Details: docs/LSP_INTEGRATION.md