よくあるエラーと対処法

症状・対象

次のどれかに当てはまる場合の切り分け表です。

症状	最初に確認するもの
同じ型エラーを繰り返す	実際の検証コマンドの先頭エラー
Allow? が何度も出る	/permissions
MCP ツールが見えない	claude mcp list と /mcp
長い会話で指示を見失う	/compact
カスタマイズ後だけ起動に失敗する	claude --safe-mode

最短解決

1. エラー全文と、失敗した直後のコマンドを保存する。
2. --safe-mode でカスタマイズを外し、再現するか確認する。
3. 再現するなら本体・プロジェクト側、再現しないなら Hook・MCP・Plugin・CLAUDE.md を一つずつ戻して原因を特定する。

コピペ例

まず環境診断と安全モードでの再現確認を行います。

claude --version
claude --safe-mode

TypeScript エラーなら、要約ではなく実際の出力を渡します。

npx tsc --noEmit 2>&1 | tee /tmp/claude-code-tsc-error.log

MCP 接続なら設定を消す前に状態を確認します。

claude mcp list

直前のセッションへ戻る場合は次です。

claude --continue

期待結果

• --safe-mode だけ成功する場合、カスタマイズ層に原因を絞れる。
• 型エラーは再現コマンドとログファイルで共有できる。
• MCP は接続済みサーバー名と設定エラーを確認できる。
• セッション終了後も --continue で直前の会話を再開できる。

検証

修正後に、最初に失敗した同じコマンドを再実行します。さらに通常モードでも起動し、/doctor と /status に警告がないことを確認します。

> /doctor
> /status

型エラーなら npx tsc --noEmit、MCP なら /mcp の reconnect、権限なら /permissions と、症状ごとの観測点まで確認して完了です。

落とし穴

• エラー文を見ずに依存関係の再インストールや設定削除を始めると、原因と証拠を同時に失います。
• 権限問題に bypassPermissions を使うと症状を隠すだけです。allow / ask / deny のルールを直します。
• MCP の認証情報をコマンド履歴やスクリーンショットへ貼りません。
• /compact は会話の要約であり、プロジェクト状態の保存ではありません。未コミット差分は git status で別に確認します。

次の一手

• パーミッションモードを使い分ける — 繰り返す確認を安全に減らす
• /compact でコンテキストウィンドウを最適化する — 長い会話を整理する
• MCP ツールをスラッシュコマンドとして呼び出す — MCP 接続を検証する