Claude Code safe modeで「壊れた」設定を1コマンドで切り分ける
claude --safe-modeは全カスタマイズを無効化して起動し、不調の原因がCLAUDE.mdやhooks、MCPサーバーにあるかを1コマンドで切り分けます。--bareとの違いと、切り分けが終わらないときの次の一手を手順化します。
Claude Codeの不調は「設定側」か「本体側」かをまず分ける
claudeの挙動がおかしいとき、原因は大きく2つに分かれます。CLAUDE.mdやHooks、MCPサーバー、プラグインといった自分やチームが積んだカスタマイズが原因の場合と、Claude Code本体やネットワーク、認証といったカスタマイズの外側が原因の場合です。これを切り分ける最短経路がclaude --safe-modeです。Claude Code v2.1.169で追加され、キャッシュを壊さず作業ディレクトリを移れる/cdと同じリリースに入っていました。
--safe-modeを付けて起動すると、CLAUDE.md・skills・プラグイン・Hooks・MCPサーバー・カスタムコマンドとサブエージェント・output styles・workflows・カスタムテーマ・カスタムキーバインド・ステータスラインとファイル候補コマンド・LSPサーバー・auto memoryが一切読み込まれません。認証・モデル選択・組み込みツール・権限は普段どおり動きます。この状態で症状が消えれば、カスタマイズのどれかが原因だと確定します。
claude --safe-modesafe modeで消えるなら「どのカスタマイズか」を個別に確認する
safe modeで症状が消えたら、次は原因を1つに絞り込みます。全部を一度に戻すのではなく、/context /hooks /mcp /skills /permissionsで読み込み状況を確認しながら、疑わしいものから1つずつ通常起動に戻して再現するのが早道です。
| コマンド | 確認できること |
|---|---|
/context | 確認できることCLAUDE.md・ルール・skill説明文が実際に読み込まれているか |
/hooks | 確認できること登録済みのHook設定(イベント別) |
/mcp | 確認できること接続中のMCPサーバーと承認状態 |
/permissions | 確認できること現在有効なallow / denyルール |
/doctor | 確認できることインストール・設定ファイルの妥当性・重複拡張の診断 |
/status | 確認できること有効な設定ソース(managed settingsが効いているか含む) |
/contextにCLAUDE.mdが出てこないなら、そもそも読み込まれていません。サブディレクトリのCLAUDE.mdはセッション開始時ではなく、そのディレクトリのファイルをReadツールで読んだタイミングで読み込まれる点も見落としがちです。
Hookが/hooksには表示されるのに発火しないなら、まずmatcherを疑います。複数ツールを対象にするときは"Edit|Write"のようにパイプ区切りの単一文字列にします(v2.1.191以降はカンマ区切りも同じ意味になりましたが、それより前のバージョンではカンマは文字どおりのマッチになり一致しません)。ツール名は大文字小文字を区別するため、"bash"のような小文字表記も無言で不一致になります。Hookの設定自体を1から見直したい場合はClaude Code Hooksの設定方法が手順を追っています。
safe modeでも消えないときの次の一手
safe modeを試しても症状が変わらない、あるいは設定ファイル自体を疑いたいときは、~/.claude配下を丸ごとバイパスするさらに一段深い切り分けに進みます。空のディレクトリをCLAUDE_CONFIG_DIRに指定し、.claudeも.mcp.jsonもCLAUDE.mdも無い場所から起動します。
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeこの状態にはユーザー設定もプロジェクト設定もHookもMCPサーバーもメモリもありません。初回起動はテーマ選択などの初期セットアップ画面から始まり、これが表示されればクリーンな設定ディレクトリが効いている証拠です。ここでも症状が出るなら、原因はユーザー・プロジェクト設定の外側(Claude Code本体、ネットワーク、認証、または組織のmanaged settings)にあります。/statusでmanaged settingsが効いていないか確認し、次に環境変数を疑います。
症状が消えた場合は、/tmp/claude-cleanに自分の設定ファイルを1つずつコピーしながら再現させ、原因のファイルを特定します。プロジェクトから起動しているなら、疑わしいプロジェクトだけを個別に試すのも有効です。
--safe-modeと--bareは目的が違う
Claude Codeにはもう1つ、カスタマイズを減らして起動するフラグとして--bareがあります。名前が似ていて混同しやすいのですが、狙いが違います。
| 項目 | --safe-mode | --bare |
|---|---|---|
| 主目的 | --safe-mode設定起因の不調を切り分ける | --bare起動を高速化する(スクリプト実行向け) |
| 無効化対象 | --safe-modeCLAUDE.md・skills・プラグイン・Hooks・MCP・カスタムコマンド/エージェント・output styles・workflows・テーマ・キーバインド・LSP・auto memory | --bareHooks・skills・プラグイン・MCPサーバー・auto memory・CLAUDE.mdの自動探索 |
| ツールアクセス | --safe-mode組み込みツールはフルセット | --bareBash・ファイル読み取り・ファイル編集のみ |
| managed settings | --safe-mode適用される | --bare(--bareは速度目的で切り分け用途ではない) |
| 対応する環境変数 | --safe-modeCLAUDE_CODE_SAFE_MODE | --bareCLAUDE_CODE_SIMPLE |
--bareはツールセット自体を絞るため、切り分け中に「ツールが足りないだけなのか、設定が原因なのか」が混ざりやすい欠点があります。設定の原因究明が目的なら--safe-mode、claude -pをCIやスクリプトから素早く呼びたいだけなら--bare、と使い分けます。CLAUDE_CODE_SAFE_MODEやCLAUDE_CODE_SIMPLEを含む環境変数の全体像はClaude Code環境変数リファレンスにまとめています。
典型的な不調と、公式が挙げる原因
Hookが発火しない・設定ファイルの値が反映されない・MCPサーバーが読み込まれない、といった典型的な症状には、公式ドキュメントが原因と対処をパターン化しています。safe modeで犯人が「カスタマイズ側」まで絞れたら、次にこの一覧で当たりを付けると早く着地します。
| 症状 | よくある原因 |
|---|---|
| Hookが一切発火しない | よくある原因matcherがJSON配列になっている(単一文字列である必要がある) |
settings.jsonの値が無視される | よくある原因同じキーがsettings.local.jsonにもあり、そちらが優先される |
skillが/skillsに出てこない | よくある原因.claude/skills/name.mdのように単一ファイルで置いている(フォルダ+SKILL.mdが必要) |
| skillは出るがClaudeが自分で呼ばない | よくある原因frontmatterにdisable-model-invocation: trueがあるか、descriptionが依頼文と噛み合っていない |
| サブディレクトリのCLAUDE.mdが効かない | よくある原因セッション開始時ではなく、そのディレクトリのファイルをReadした時点で読み込まれる仕様 |
.mcp.jsonのMCPサーバーが出てこない | よくある原因ファイルが.claude/配下にある、またはClaude Desktopの設定形式で書かれている(リポジトリ直下の.mcp.jsonが正しい置き場所) |
| プロジェクトMCPサーバーが追加したのに出ない | よくある原因初回承認プロンプトを閉じてしまい未承認のまま止まっている(/mcpから承認) |
これらは--safe-modeを使わなくても/hooks``/mcp``/doctorだけで見えることも多いですが、複数のカスタマイズが絡み合っているときはsafe modeで土台を空にしてから1つずつ足す方が早く収束します。認証エラーやVS Code拡張の起動失敗など、カスタマイズと無関係な症状が疑わしいときはClaude Codeでよくあるエラー10選を先に当たったほうが早いこともあります。
メモリやCPUの高使用にもsafe modeは使える
不調は「動かない」だけでなく「重い」形でも出ます。公式のトラブルシューティングガイドは、CPUやメモリ使用量が高いときの切り分け手順の中に--safe-modeを組み込んでいます。/compactで会話を圧縮し、大きなビルドディレクトリを.gitignoreに追加してもなお重いなら、プラグインやMCPサーバー、Hookが原因になっていないかをsafe modeで確認します。
メモリ使用量が高いまま残る場合は/heapdumpでヒープスナップショットと診断用JSONを~/Desktop(Linuxでデスクトップフォルダーが無い環境はホームディレクトリ)へ書き出せます。ヒープスナップショットには会話内容や資格情報を含む文字列がすべて含まれるため、公開のGitHub Issueに添付しないよう注意が必要です。GitHub Issueへ報告する場合は、統計情報だけを含む-diagnostics.jsonのほうを使います。
いつsafe modeを使うべきか
すべての不調にsafe modeが必要なわけではありません。設定を厚く積んでいる環境ほど効果が大きく、標準設定に近い環境では確認する対象自体が少ないため恩恵は限定的です。
| 状況 | safe modeの効き方 |
|---|---|
| CLAUDE.md・Hooks・MCPサーバーを複数重ねた環境で挙動がおかしい | safe modeの効き方明確な恩恵あり。まず最初に試す価値がある |
| プラグインを入れた直後から重くなった、CPU/メモリが高い | safe modeの効き方条件次第。--safe-modeで切り分けたうえで/heapdumpも検討 |
| 標準設定に近い個人環境で単発の不具合が出た | safe modeの効き方ほぼ影響なし。/doctorやclaude --version確認が先 |
| 組織のmanaged settingsポリシーが原因かもしれない | safe modeの効き方safe modeでは切り分けきれない。/statusでポリシー適用を確認 |
まとめ
claude --safe-modeは、CLAUDE.md・skills・プラグイン・Hooks・MCPサーバーなど、自分やチームが積んだカスタマイズを一括で無効化して起動するオプションです。症状が消えれば原因はカスタマイズ側、消えなければCLAUDE_CONFIG_DIRを空ディレクトリに向けたクリーンな起動でさらに切り分けます。速度目的の--bareとは狙いが異なるため混同しないこと、managed settingsはsafe modeでも生き続けることの2点を押さえておけば、原因不明の不調に当たったときの最初の一手として機能します。設定を厚く積んだチーム開発環境ほど、この1コマンドの価値は大きくなります。なお、ここで扱うのは環境側の不具合の切り分けです。自分のコードのバグを直す場面での情報の渡し方はClaude Codeデバッグの精度は、渡す情報の質で決まるで扱っています。逆に「原因は分かったが、Claudeが加えた変更やここまでの会話を今すぐ元に戻したい」場合は、切り分けではなく/rewindによるコードと会話の巻き戻しが使う道具になります。
よくある質問
safe modeとbypassPermissionsは何が違いますか
別物です。--safe-modeはCLAUDE.mdやHooks、MCPサーバーといったカスタマイズを無効化する起動オプションで、権限確認そのものは普段どおり動きます。一方--dangerously-skip-permissions(bypassPermissionsモード)は権限確認自体をスキップするモードで、カスタマイズの読み込みには影響しません。目的が完全に別なので、切り分け用途では--safe-modeを使います。
safe modeを使うとプロンプトキャッシュは無効になりますか
safe modeはセッションの起動オプションなので、通常のセッション開始と同じ扱いです。セッション実行中にモデルやeffortレベルを切り替えるとキャッシュが無効化されますが、safe modeでの起動自体がキャッシュに特別な影響を与えるという情報は公式ドキュメントにはありません。
組織のmanaged settingsが原因かどうかはどう確認しますか
/statusでmanaged settingsが有効かどうかを確認できます。safe modeで症状が消えないのにHook・MCP・プラグインが疑わしい場合、それらがmanaged設定として配布されている可能性があります。managed hooksとステータスライン・ファイル候補コマンドはsafe modeでも動き続けるため、通常のsafe modeの切り分けからは見えません。
CLAUDE_CODE_SAFE_MODE環境変数と--safe-modeフラグはどちらを使うべきですか
効果は同じです。CIやスクリプトなど、フラグを毎回書き足すのが面倒な場面ではCLAUDE_CODE_SAFE_MODE=1を環境変数として設定しておくと、claudeを素のコマンドで起動してもsafe modeが有効になります。単発の切り分けなら--safe-modeフラグの方が明示的で分かりやすいです。