本文へ移動
BenriWorks LabBenriWorks トップ

ガイド更新日

Claude Codeが止まったときの、原因の探し方

この記事で分かること

Claude Code 集中講座の第15回。「起動しない」「設定が効かない」「結果が違う」を切り分けます。診断コマンドとセーフモードを使い、次に調べる場所を絞ります。

エラーの出た画面とメモを見比べながら、こちらを向いている女性の開発者
目次 読みたいところから

昨日まで動いていたClaude Codeが、今日は進まない。起動しないのか、依頼の途中で止まるのか、返ってきた結果が違うのか。ひとまず設定を変える前に、止まっている場所を分けます。

道具、設定、実行、結果、画面の5つを順に見ます。診断結果を残せば、直らなかった場合にも次に調べる場所を絞れます。

層を決めてから調べる

エラーの文面から原因を当てにいくと、当たるまで探し続けることになります。代わりに、下から順に「ここまでは正しい」を確かめます。

層問い使う道具
5実際の画面で正しく動いているかブラウザのペイン
4出てきたものが合っているか/context、/compact
3依頼が届いて実行できているか権限モード、/permissions
2設定が効いているか/context、--safe-mode
1道具が動いているかclaude doctor、/status
切り分けの5つの層を下から積み上げた図。道具が動くか、設定が効いているか、依頼が届いているか、出てきたものが合っているか、実際の画面で正しいかの順に並び、各層で使う診断コマンドが右に書かれている
下から確かめる。上の層の調査は、下が正しいと分かってから

Claude Code に特徴的なのは第2層です。設定できることが多いぶん、自分の設定が原因で動かなくなる場面が他の道具より多くなります。

層1: 道具が動いているか

専用の道具があります。

claude doctor

第2回でも使ったこのコマンドを、執筆環境で実行した実物です。

Claude Code doctor

Running: native (2.1.318)
Commit: ca1fa9dea62c
Platform: linux-x64
Path: /opt/claude-code/bin/claude
Config install method: unknown
Search: OK (/usr/bin/rg)
Auto-updates: disabled (set by env: DISABLE_AUTOUPDATER)
Auto-update channel: latest
Last update attempt: none recorded
Managed settings (remote): none configured for this organization
Organization policy: Loaded from api.anthropic.com

Remote Control
Inside a cloud session — Remote Control is unavailable here. Use it from the local session instead.

3 warnings found
- Running native installation but config install method is 'unknown'
  Fix: Run claude install to update configuration
- claude command at /root/.local/bin/claude missing or broken
  Fix: Run claude install to repair the installation.
- Leftover npm global installation at /opt/node22/bin/claude
  Fix: Run: npm -g uninstall @anthropic-ai/claude-code

For a full setup checkup that can also fix issues, run /doctor in a Claude Code session.

セッションの中からは /doctor を使います。こちらは点検に加えて、直せるものは直します。

もう1つ見る場所が /status です。いま使われている資格情報、組織、モデルが出ます。

思っていたモデルと違うものが動いていたは、実際によくあります。特にターミナル版では、環境変数に ANTHROPIC_API_KEY が残っていて使用を承認すると、サインインしたアカウントではなくそちらが使われます。意図せず従量課金になっていた、という形で気づくことが多い落とし穴です。

層2: 設定が効いているか

ここが Claude Code の切り分けで一番効く層です。

CLAUDE.md に書いたのに守られない、スキルが呼ばれない、フックが動かない。こういうときの手順は2つです。

まず /context を見ます。読み込まれたファイルの一覧が出ます。そこに無ければ、書いた内容ではなく置いた場所の問題です。第9回で見たとおり、読まれる場所は決まっています。

次に --safe-mode です。

claude --safe-mode

公式ドキュメントによれば、これは全部のカスタマイズを切った状態で起動します。CLAUDE.md、スキル、プラグイン、フック、MCP サーバー、自作のコマンドとサブエージェント、出力スタイル、キーバインドまで、全部です。

これで症状が消えるなら、原因はあなたの設定のどれかです。消えないなら、設定以外の場所を探すことになります。この1回の実行で、探す範囲が半分になります。

原因の設定を絞り込むときは、疑わしいものから1つずつ戻します。設定が多いほど、この二分の探し方の価値は上がります。

より詳しく見たいときは /debug を有効にします。記録は ~/.claude/debug/<セッションID>.txt に書かれます。

層3: 依頼が届いて実行できているか

道具も設定も正常だが、作業が進まない場合です。

まず、いまの権限モードを確認します。dontAsk になっていると、確認が必要な操作は全部自動で拒否されます。CI 用の設定を手元に残したまま作業していると、この状態になります。

次に /permissions を見ます。過去に「今後は聞かない」を押したものと、deny 規則が並びます。自分で塞いだことを忘れているのは、実際によくあります。

auto モードで止まっている場合は、分類器が理由を返しています。第5回で見たとおり、多くの場面で理由は規則の名前として返ります。同じ操作が繰り返し止まるなら、操作そのものを変えるか、必要なら明示的な allow 規則を書きます。

範囲の問題もあります。作業フォルダの外のファイルを触ろうとしているなら、--add-dir で足すか、開くフォルダを変えます。

層4: 出てきたものが合っているか

動いてはいるが、返ってくるものが的外れな場合です。

原因が2つに分かれます。

依頼が足りていないなら、第7回の3つを見直します。文脈と制約と完了の条件。抜けているのはたいてい完了の条件です。

会話が長すぎるなら、/compact で畳みます。/context で、どれだけ埋まっているかを先に見てください。作業を変えたのに会話を続けている状態が、この症状の一番多い原因です。

差分が大きすぎて読めないときは、直す先が依頼の側です。1つの依頼で20ファイルが変わるなら、依頼が大きすぎます。

第8回で扱った巻き戻しが効かない場合もあります。「復元できませんでした」と出るときは、記録の保持期間を過ぎていることがあります。既定では、そのセッションが最後に記録を保存してからおよそ30日です。

層5: 実際の画面で正しく動いているか

検査も通り、ビルドも通っているのに、開くと動かない場合です。ここが一番やっかいで、実際に開いて確かめるしかありません。

BenriWorks で実際に踏んだものを2つ挙げます。

ひとつは、開発用のサーバーで確認していて気づかなかった例です。開発用サーバーの通信がうまくつながらず、画面は出るのに操作が一切効かない状態になっていました。ビルドしたものを配信する形で起動し直したら、そのまま動きました。開発用の起動でおかしいときは、本番と同じ組み立て方で一度確かめる。

もうひとつは、画面の部品の中に文字列として埋め込んだ処理で、エスケープが壊れていた例です。ブラウザでは構文の誤りになっていましたが、サーバー側の検査は全部通っていました。この件のあと、埋め込んだ結果の構文を検査する項目をビルドの前に足しました。

2つに共通するのは、ソースコードを読んでも分からないことです。第3回で紹介したブラウザのペインは、この層のためにあります。

「見つかりませんでした」を疑う

層の話とは別に、1つ書いておきます。

Claude から「見つかりませんでした」という報告を受け取ったら、どこを探したかを聞いてください。探した範囲が狭ければ、その報告は「ない」ではなく「その範囲にはない」です。

BenriWorks では、実際にこれで間違えました。ある設定がリポジトリの中に無いことを確かめて「設定なし」と結論しましたが、実際には配信の設定として付いていました。本番の応答を見れば分かったことです。経緯はCodex 集中講座の第16回に書いています。

探した場所にないことは、存在しないことを意味しません。人がやっても同じ間違いをします。

直せないときに残すもの

全部が直るわけではありません。時間の都合で、分からないまま進めることもあります。

そのときに残すのは2つです。再現する手順と出たエラー、そして確かめていないと分かる形の印です。BenriWorks では、本文に TODO: 要確認 の形で残す約束にしています。第9回で引用した規約の1行が、これにあたります。

一番まずいのは、直っていないのに直ったことにすることです。次に困る人が、直っている前提で調べはじめます。

症状から確認先を選ぶ

「起動しない」「設定を書いたのに効かない」「動くが結果が違う」の3つについて、本文の層と最初の確認先を対応づけます。現在困っている症状があれば、実行したコマンドと出力も残してください。

試したことと結果が並べば、同じ設定変更を繰り返さずに次の調査へ進めます。

次の回

止まった場所を調べる手段が揃ったら、次に任せる仕事と、人が判断する部分を決めます。「Claude Codeに任せる仕事と、人が決める仕事」へ進めます。

参照した公式情報

  • Anthropic「Advanced setup」「Troubleshooting」「Debug your configuration」「Checkpointing」(code.claude.com/docs、2026年11月時点)
  • Anthropic「Authentication」「Error reference」(code.claude.com/docs、2026年11月時点)
  • claude doctor の出力は Claude Code 2.1.318 を執筆環境で実行して取得

READ NEXT

次はこれを読む

Claude Code 集中講座の次の回へ

Claude Codeに任せる仕事と、人が決める仕事

Claude Code 集中講座の最終回。次に任せたい仕事を、規約、強制する設定、審査、人の判断に分けます。確認する基準と結果の読み方まで含めて、実際の依頼を組み立てます。

続きを読む →
作業を終えた机の前で、腕を組んでこちらを向いている男性の開発者

よくある質問

設定が効いていないときは何を見ますか
まず `/context` で、読み込まれたファイルの一覧を見てください。そこに無ければ、内容ではなく場所の問題です。それでも原因が分からないときは `--safe-mode` で起動し、全部のカスタマイズを切った状態と比べます。症状が消えるなら、あなたの設定のどれかが原因です。
思っていたモデルと違うものが動いている気がします
`/status` で確認できます。資格情報、組織、モデルが表示されます。ターミナル版では、`ANTHROPIC_API_KEY` が環境変数に設定されていて使用を承認すると、サインインしたアカウントではなくそちらが使われるため、意図しない課金になっていることがあります。
巻き戻そうとしたら復元できませんでした
ファイルの記録には保持期間があり、既定ではセッションが最後に記録を保存してからおよそ30日で削除されます。古いセッションは巻き戻せません。長く残したい場合は `cleanupPeriodDays` を設定してください。