つまずいたとき、設定を疑う前に設定を全部切る

14回かけて道具をそろえました。実際に歩くと、あちこちで詰まります。

この回で並べるのは、個別の対処法ではありません。どこで止まっているかを先に決める順番です。順番さえ決まっていれば、見たことのない症状でも調べる場所を絞れます。

層を決めてから調べる

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

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

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

専用の道具があります。

claude doctor

執筆環境で実行した実物を、第2回から再掲します。

Running: native (2.1.268)
Platform: linux-x64
Path: /opt/claude-code/bin/claude
Config install method: unknown
Search: OK (/usr/bin/rg)
Auto-updates: enabled

3 warnings found
- Running native installation but config install method is 'unknown'
- claude command at /root/.local/bin/claude missing or broken
- Leftover npm global installation at /opt/node22/bin/claude

セッションの中からは /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行が、これにあたります。

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

次の回

道具の話はここで終わりです。

最終回は道具の話をやめます。ここまで積んだ仕組みの上で、何を任せて何を自分で決めるか。この講座が結局のところ何のためのものだったかを書きます。

参照した公式情報

• Anthropic「Advanced setup」「Troubleshooting」「Debug your configuration」「Checkpointing」（code.claude.com/docs、2026年9月時点）
• claude doctor の出力は Claude Code 2.1.268 を執筆環境で実行して取得