Claude Codeの復旧：Safe Mode、/cd、フォールバック

エージェント活用の実践資料：Ailootのドキュメント。

2026年6月、Claude Codeに何が追加されたのか？#

以前は、Claude Codeの動作がおかしくなったとき、たとえばスピナーが終わらない、起動時にクラッシュする、エージェントがCLAUDE.mdのルールを無視する、フックが黙って実行されない、といった場合の解決策は一つしかありませんでした。.claude/settings.jsonの一部を手動でコメントアウトする、MCPサーバーを一つずつ無効にする、最悪の場合は~/.claudeを削除して再インストールすることです。ある事例では、~/.claudeを削除した結果、組み立てに1時間半かけたMCPサーバーの設定を失いました。後になって、原因はCLAUDE.mdの1行で、見つけるのに10秒しかかからなかったと分かりました。しかし、それが判明したのは完全に復旧した後でした。

2026年6月、Anthropicはこの状況を変える3つの仕組みを導入しました。追加された機能と時期を簡単にまとめます。

以下では、それぞれの仕組みと、Claude Codeのセッションがうまくいかなくなったときに適用する順序を、手順ごとに説明します。

Claude Codeでは何が最もよく問題を起こすのか？#

説明されている例では、最初のCLAUDE.mdは80行で、1か月は問題なく動いていました。2か月目になると、週に一度、設定したルールをClaudeがすべて破ることが目立つようになりました。.envに触れる、git push --forceを実行する、node_modulesを探る、といった行為です。悪意があるのではなく、単に忘れてしまうのです。一度は.gitignoreが削除され、すぐには理由が分かりませんでした。この状況については、CLAUDE.mdのガイドでさらに詳しく説明しています。

CLAUDE.mdが400行を超えると、気づかれないまま問題を起こし始めます。セッション開始時にコンテキストウィンドウのかなりの部分を占め、重要な指示が二次的な指示に埋もれてしまいます。Claudeは形式上ファイルを読んでいるため、外から見ると「ルールは書いてあるのに、機能していない」ように見えます。これは契約が肥大化している典型的な兆候です。

2つ目によくある原因はフックです。Claude Code hooksには、Anthropicがあまり強調していない注意点があります。

つまり、Pythonフックのsys.exit(1)（またはUnixで一般的な「エラーで失敗した」という終了コード）ではClaudeを止められません。ブロックするのはコード2だけです。説明されている事例では、このフックは「絶対に禁止する」ものと考えられていましたが、実際には警告を記録するだけで、処理を続行させていました。

3つ目の層はMCPサーバーで、こちらも独自の形で問題を起こします。

症状は多くの場合同じです。MCPコマンドは使えるのに、トレースバックなしでfailedを返します。MCPの設定やclaude mcp addによるサーバーの追加については、別のガイドを参照してください。

4つ目の原因は、3階層のsettings.json構成です。~/.claude/settings.json（ユーザーレベル）、プロジェクトルートの.claude/settings.json（プロジェクトレベル）、.claude/settings.local.json（ローカル設定）があり、さらに企業の管理者が設定した管理対象設定が加わることもあります。これらは優先順位のルールに従って統合されます。プロジェクトレベルでMCPサーバーを追加し、ユーザーレベルに起動設定の異なる同様の項目があると、気づかれない競合が起こり、「Claude Codeが壊れた」ように見えます。

--safe-modeはどのように動作し、何を無効にするのか？#

v2.1.169のchangelogにあるAnthropicの原文は次のとおりです。

Anthropicは、model-configのドキュメントで次のように補足しています。

これは診断用ツールであり、「クリーンな環境」ではありません。safe modeを使って答えるのは、「問題はClaude Codeの初期状態の動作にあるのか、それとも追加したカスタマイズにあるのか」という一つの問いです。これはコンテキストエンジニアリングの一部であり、ある時点でClaudeに何を見せ、何を見せないかを管理することです。safe modeですべて動作するなら、二分探索で各層を調べれば原因が分かります。動作しない場合は、インストール自体、認証、ネットワーク、またはインフラに問題があります。その場合はclaude doctorとログを確認するのが適切です。

safe modeで無効になる項目（Anthropic公式リストの主な5層）：

• すべての階層（ユーザー／プロジェクト）のCLAUDE.md
• プラグイン
• スキル
• フック
• MCPサーバー

引き続き使える項目：

• 認証（OAuthセッションまたはAPIキー）
• モデル選択（--model sonnet、--model opus）
• 組み込みツール（Read、Write、Bash、Grepなど）
• 権限
• Gitの状態
• ディレクトリ名

重要な点として、safe modeは企業の管理者が設定した管理対象設定やポリシーを無効にしません。Bedrock GovCloudやMDM設定でavailableModelsが指定されているチームで作業している場合、その制限は引き続き適用されます。safe modeが無効にするのはユーザーのカスタマイズだけであり、企業のポリシーではありません。

60秒で層を切り分け、原因を見つけるには？#

Claude Codeが「言うことを聞かなくなった」ときの診断手順です。以下のコマンドを実行するには、Claude Code v2.1.169以降が必要です。古いバージョンを使っている場合は、先に更新してください（npm update -g @anthropic-ai/claude-codeまたはAnthropicのネイティブインストーラー）。

1. 問題が起きていたのと同じフォルダーを開きます。
2. claude --safe-modeを実行します。
3. 問題なく起動したら、元のリクエストを試してください。動作しましたか？なら、原因は各層のいずれかです。手順4に進みます。
4. safe modeでも問題が続く場合は、設定に触れないでください。まずclaude doctorを実行し、認証、バージョン、インストールの競合を確認します。

safe modeで問題なく起動したら、原因の可能性が最も高いものから、一つずつ層を有効にします。説明されている経験に基づく順序は次のとおりです。

1. CLAUDE.md。 safe modeを使わずにclaudeを実行し、ファイル名を一時的に変更します：mv CLAUDE.md CLAUDE.md.bak。動作するなら、このファイルが原因です。その後、行を半分ずつ残して確認する二分探索ができます。
2. フック。 .claude/settings.jsonを開き、hooksセクションに一時的に[]を設定します。claudeを再起動します。動作しますか？なら、原因はフックのいずれかです。一つずつ有効にしてください。
3. MCPサーバー。 同様に、~/.claude.jsonまたは.claude/settings.jsonのmcpServersセクションに、一時的に空のオブジェクトを設定して再起動し、確認します。
4. スキル。 .claude/skills/を一時フォルダーに移します。起動して確認します。

「一時的な名前変更」とは、診断中にファイルを削除しないという意味です。mvやgit stashを使えば、その層が原因でないと分かったときに、コマンド一つですべてを復元できます。

コンテキストを失わずに/cdで作業フォルダーを切り替えるには？#

6月8日のv2.1.169 changelogには次のように記載されています。

問題の修正にこの機能が役立つ理由を説明します。たとえば、プロジェクトフォルダー~/work/myappで作業していて、Claude Codeの動作がおかしいとします。以前は「そもそも動くのか」を確認する唯一の方法は、セッションを終了し、別のフォルダーに移動して、改めて起動することでした。コンテキスト、履歴、温めたプロンプトキャッシュを失っていました。今は次のようにできます。

# 同じセッション内で実行：
/cd ~/sandbox/test

Claudeは新しいフォルダーに切り替え、そのフォルダーにCLAUDE.mdがあれば、それをシステムプロンプトの置き換えではなくメッセージとして読み込みます。つまり、キャッシュは維持されます。~/sandbox/testですべて動作するなら、問題は~/work/myappの設定にあったと分かります。

6月12日、v2.1.176で一つ厄介なリグレッションが修正されました。/cd後に完全に再起動するまで古いgitブランチが表示されていた問題です。古いバージョンを使っている場合は、更新するか、切り替え後の最初の数メッセージではgit statusを無視してください。そのうち表示が追いつきます。

529エラーに備えてフォールバックモデルを設定するには？#

説明されている状況では、週に一度、プロジェクト内の長いタスクをOpusで実行すると、10分後にAPIが529 Overloadedを返してセッションがクラッシュします。以前は待つか、手動で--model sonnetを使ってSonnetに切り替えるしかなく、その場合は温めたコンテキストを失っていました。second-brainの仕組みを構築した大きなbusiness/フォルダーでは、これに約20分かかります。今は、適切な仕組みがあります。

公式ドキュメントからの正確な引用は次のとおりです。

チェーンの動作については、別途次のように説明されています。

設定方法は2つあります。CLIを使う方法：

claude --fallback-model sonnet,haiku

~/.claude/settings.jsonを使う方法：

{
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

レート制限については、別の注意点があります。Anthropicは429エラーを意図的にチェーンに回さないため、次のモデルに切り替えてリクエスト制限を回避することはできません。フォールバックが機能するのは、プライマリモデルが過負荷、利用不能、または再試行できないサーバーエラー（たとえば529 Overloaded）を返した場合だけです。レート制限には、通常の再試行とバックオフが適用されます。

もう一つ注意点があります。6月12日、v2.1.174でリグレッションが修正され、コンパクションが--fallback-modelを尊重するようになりました。長いセッション中、過負荷の状態でコンパクションが起きる場合、この修正以前はフォールバックモデルが呼び出されませんでした。長時間のセッション（夜間の/compact、/loopなど）を使う場合は、少なくともv2.1.174に更新してください。

原因がCLAUDE.md、フック、MCP、またはスキルだった場合の修正方法#

層ごとの具体的な対処方法を説明します。

原因がCLAUDE.mdの場合

ファイルを開き、サイズを確認します。説明されている経験では、有効なCLAUDE.mdは200行以下にしてください。残りは、プロジェクト内のルーターや補助ドキュメントに移します（second-brain全体の構成については、second brainのガイドを参照してください）。400行を超えているなら、ほぼ間違いなく原因です。手順は次のとおりです。

1. バックアップを作成します：cp CLAUDE.md CLAUDE.md.full。
2. 短い動作確認済みのテンプレートに戻します。既製のテンプレートは「CLAUDE.mdの設定方法」ガイドにあります。
3. Claude Codeを再起動し、確認します。
4. 動作する場合は、10～20行の小さなブロックでルールを戻し、ブロックごとに確認します。
5. 動作を壊すブロックを見つけます。そのブロックを、正しい終了コードを使うフックとして書き直します（フックの終了コードについては、このH2の次の小節で説明します）。

原因がフックの場合

まず終了コードが正しいか確認してください。Claude Codeのフックでは、次のように扱われます。

• 終了コード0 — 問題ありません。処理が続行されます。
• 終了コード1 — エラーですが、ブロックしません。何もなかったかのようにClaudeは処理を続けます。
• 終了コード2 — ブロックするエラーです。処理を実際に止めるのはこれだけです。

ブロックするつもりでシェルフックにsys.exit(1)やexit 1を書いた場合、Claude Codeではこのコードは警告を記録するだけで、処理を止めません。2に変更してください。この落とし穴を避けるフックの詳細と設定方法については、別のガイドを参照してください。

2つ目によくあるケースは、フックが標準出力に無効なJSONを返すことです。Claude Codeはフックの応答をJSONとして解析します。出力にログ、進捗表示、絵文字などの余計なものがあると、フックは失敗と見なされ、処理は続行されます。ルールは、標準出力にはJSONのみを出し、それ以外はすべて標準エラー出力に送ることです。

3つ目は、safe modeで隠された~/.claude/内の情報をフックが読み取ろうとするケースです。これは通常起こり得ることです。フックにパッチを当てるのではなく、冒頭でos.environ.get('CLAUDE_CODE_SAFE_MODE')を確認し、該当する場合は0で終了するように修正してください。

原因がMCPサーバーの場合

症状：MCPコマンドは利用できるのに、明確なトレースバックなしでfailedを返します。手順は次のとおりです。

1. claude mcp listを実行し、どのサーバーが定義されているか確認します。
2. ~/.claude.json内のサーバーを一つずつ無効にします。キー名claude-server-Aを_claude-server-Aに変更します（削除せずに無効化できます）。
3. claudeを再起動し、どの呼び出しが動作するか確認します。
4. 原因のサーバーが見つかったら、ログを確認します：claude mcp logs <name>。
5. サードパーティ製サーバー（@modelcontextprotocol/server-postgresなど）の場合は、最近のリリースがあるか確認します。MCPエコシステムはまだ不安定で、Claude Codeの更新によってサーバーが頻繁に壊れます。

「MCPが2つあるときだけ起動時にクラッシュする」場合は、safe modeでMCPを使わずに動作を比べてください。

原因がスキルの場合

スキルはSKILL.mdと.claude/skills/<name>/内のコードで構成されます。症状としては、Claudeがスキルを無視する、誤ったタイミングで適用する、または適用しても使えない結果を出す、といったものがあります。手順は次のとおりです。

1. SKILL.mdを開き、説明を確認します。説明は1～2文で、いつ使うかを具体的に示してください。「あらゆることに使える万能ヘルパー」と書かれていると、Claudeはいつ呼び出せばよいか判断できません。
2. CLAUDE.mdの内容と矛盾していないか確認します。CLAUDE.mdに「必ずテストを書く」とあり、スキルの説明に「テストなしの素早いプロトタイプに使う」とあれば、矛盾しています。
3. スキルが外部コマンド（npm、python、git）を使う場合、システム全体のPATHからコマンドを利用できるか確認します。スキルが使える環境は最低限のものです。

safe modeでも解決しない場合：診断と状態保全をしてから修復する#

ユーザー状態の削除を診断の近道にしないでください。以下で原因を特定し、不明なら証拠を保って調べます。修復は検証済みバックアップから始め、既存アカウントと認証ストアの識別を維持します。順序は次のとおりです。

1. claude doctor — 自動診断。Anthropicのドキュメントには次のように書かれています。

2. インストールの競合を確認します。 npmのグローバル版とネイティブインストーラー版の両方が、同時にインストールされていることがよくあります。

3. ANTHROPIC_API_KEYがOAuthセッションに割り込んでいないか確認します。「何も動かない。キーが期限切れになった」という問題のよくある原因です。

対処法：現在のシェルセッションでunset ANTHROPIC_API_KEYを実行するか、~/.zshrc／~/.bashrcから削除します。

4. 診断で特定したインストールだけを修復し、先に全ユーザー状態を保全します。 safe modeの失敗やdoctorの不明結果だけでは削除が必要といえません。一貫したコピーのため全Claudeセッションと書き手を停止します。Unixアカウント、HOME、OSの認証ストア、Anthropicアカウントを維持し、キー変更や代替の識別を作りません。

次の例はGNU tarを使うLinux用です。macOSやWindowsでは、そのOSのACL、拡張属性、リンク、メタデータを保つ手段を使い、復元を検証します。GNU専用フラグを流用しないでください。認証と会話を含むので、アーカイブは非公開でリポジトリ外へ置きます。

# Run as the same user who owns the Claude state, after stopping writers.
set -eu
umask 077
backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX")
set --
if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then
  set -- "$@" .claude
fi
if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then
  set -- "$@" .claude.json
fi
[ "$#" -gt 0 ] || exit 1
tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME"
sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256"
(cd "$backup_dir" && sha256sum -c claude-state.sha256)
mkdir "$backup_dir/restore-check"
tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
printf 'Verified recovery directory: %s\n' "$backup_dir"

全コマンドの成功が必要です。Git管理済み設定だけでなく、無視・未追跡の履歴、プラグインを含む.claude全体と.claude.jsonを保存します。シンボリックリンクや別の保存先がある場合は止まり、解決した実体も同じ検証済みコピーへ含めます。リンクだけでは実体を保存しません。macOS Keychainなどの外部認証ストアはこのアーカイブに入らないため、その識別は維持してください。

診断が旧ローカルインストールを競合元と特定した場合だけ、設定や履歴を消さず、その導入部分だけを非公開の復旧先へ移します。

# Use the verified backup_dir from the previous block.
if [ -d "$HOME/.claude/local" ]; then
  mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi

npm版も競合と診断し、ネイティブ版を残す場合だけ除去します。公式ネイティブインストーラーを使い、.claudeと.claude.jsonは削除しません。

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

Windowsのネイティブ導入は次です。

irm https://claude.ai/install.ps1 | iex

復元は別工程です。 再び書き手を止め、チェックサムと空の復旧フォルダーへの展開・比較を確認します。移した旧導入を戻す場合、$HOME/.claude/localがないことを確認してから、$backup_dir/legacy-localをその正確なパスへ戻します。診断対象の設定は現在の置き換えを先に保全し、検証済み展開から戻します。全ツリーを盲目的に上書きしません。履歴、MCP、元の識別を保ちます。Gitスナップショットだけでは無視・未追跡の会話、認証、メタデータを覆えません。

Claude Codeが壊れたときにしてはいけないこと#

診断前にキーを変更しない

「認証が機能しない」問題の90%は、ANTHROPIC_API_KEYがサブスクリプションに割り込んでいる、フックのUIバグ、またはMCPの失敗のいずれかです。キーをローテーションしてもこれらは直りません。それどころか、古いキーを無効化して新しいキーを発行し、CIに再署名し、本番環境の変数を更新する必要があるため、さらに1時間の停止を招きます。まずclaude --safe-modeを実行してください。動作しますか？なら、カスタマイズに問題があります。キーに触れる必要はありません。

safe modeの前に完全リセットしない

safe modeなら、1秒で隔離された環境を用意できます。.claudeの削除は履歴、MCP設定、未追跡状態を失わせることがあります。先に診断し、非公開バックアップを検証して、原因と分かった導入または設定層だけを元に戻せる形で移してください。

フックのUIエラーに慌てない

修正を始める前に、表示だけを信用せず、ログをstderrに出すか明示的なprintを使って、フックが実際に実行されたか確認してください。

ロジックを直す前にフックの終了コードを引き上げない

ブロッキングフックが処理を止めないときは、exit 2にして終わりにしたくなるかもしれません。これは一時的には動作する修正ですが、別の問題を隠してしまいます。1か月にわたってブロックが機能していなかったのなら、フックが禁止するはずだった処理はすべて通過しています。まずgitのログを調べ、何がすり抜けたのかを正確に確認してください。その後でブロックを追加します。そうしなければ、後からブロックを設けても、それ以前に起きたことは取り消せません。

safe modeという安全策なしで本番のCLAUDE.mdを編集しない

説明されている事例では、CLAUDE.mdを編集した後にClaudeの動作がおかしくなり、git diffを見ると、その日の夕方に誰かがMCPサーバーとフックもリポジトリに追加していたことが分かりました。自分の編集が原因だと考えて元に戻したものの、Claudeの動作はおかしいままでした。ルール：git revertの前にclaude --safe-modeを実行してください。safe modeでも問題が続くなら、あなたの編集とは無関係です。元に戻す必要はありません。

「Claudeが自分でMCPを直す」と信じない

よくある事例を挙げます。Claudeに「MCPサーバーに特定のツールを追加して」と依頼すると、Claudeは動作していた設定を書き換えて、すべてを壊し、その後何ターンもかけて自分が起こした損害をデバッグし、その過程でセッションの利用上限を使い切ります。MCPが壊れたら、設定は手動で確認してください。エージェントに任せてはいけません。ツール群の一部もMCP上で動作しており、MCPが壊れると診断する側も壊れます。

修復後はどうすればよいか？#

インシデントを分析した後、すぐに作業へ戻ってはいけません。まず、同じことが繰り返されないように予防策を追加してください。second brain（プロジェクト構造を持つbusiness/フォルダー）とCLAUDE.mdには何時間もかけることがあり、それらを手動で復元するのは困難です。これには十分な理由があります。最低限のセットは次のとおりです。

1. ~/.claude/settings.jsonにpermissions.disableBypassPermissionsMode: "disable"を設定します。これにより、バイパスモードを設計上禁止できます。誤って--dangerously-skip-permissionsを起動しても動作しません。
2. Read(./env*)、Bash(git push --force)、Write(./node_modules/**)に対するフックを設定します。願いではなく、ルールとして捕捉しなければならない操作です。
3. 長時間の自律実行（/loop、/schedule）向けにサンドボックスを設定します。
4. 独自のルールを使って/compactを設定し、コンテキストから何を破棄するかを定めます。Claudeがコンテキストを使い切らないようにするためです。

4層の保護策の全容は、「Claude Codeが一晩でプロジェクトを壊さないように設定する方法」ガイドで説明しています。一方のガイドでは/loopを実行する前の予防を扱い、もう一方では/loopがすでに何かを壊した後の復旧を扱います。理にかなった組み合わせです。

実践資料：Ailootのドキュメント。

資料とツール：Ailoot。