claude code 動かない｜「完了しました」を信じるな——環境系と生成系の対処【2026】

「完了しました」——Claude Codeがそう返してきたとき、あなたはブラウザを開いて実際に確認しているだろうか。

claude 動かないという状態には、大きく2種類の起源がある。一方はエラーメッセージが出る環境系（起動しない・PATHが外れている・認証が通らない）、もう一方はエラーメッセージが出ない生成系（「完了した」と報告したのに実際には404が返る・同じミスを繰り返す・一箇所直すと別が壊れる）だ。

競合記事のほとんどは環境系しか扱っていない。しかし実際の運用で問題の発見が遅れ、被害が積み重なるのは後者だ。ログに何も出ないまま、完了報告だけが積み重なっていく。

本記事では両系統を切り分け、環境系には公式ドキュメントに基づく定型の対処を、生成系には実運用で確立した検証の型を具体的な手順で示す。

---

claude 動かないの第一診断——まず /doctor を叩く

環境系か生成系かを判断する前に、Claude Code自体が起動できる状態かを確認する。公式の診断コマンドは1つだ。

# Claude Code起動中なら
/doctor

# 起動すらしない場合はシェルから
claude doctor

/doctor は認証・接続・依存関係・実行環境をまとめてチェックし、問題があれば原因と修正方針を返す。まずここから始め、その出力内容で環境系か生成系かを切り分ける。それでも解決しない場合は /feedback またはGitHub Issuesへエスカレーションする。

---

環境系でclaude 動かない——PATH・認証・Linux固有の公式対処

環境系トラブルはエラーメッセージが手がかりになる。以下は公式ドキュメント（code.claude.com）に基づく対処を症状別に整理したものだ。

command not found: claude（PATHが外れている）

ネイティブ版Claude Codeは実行ファイルを ~/.local/bin/claude に配置する。シェル設定の更新などでこのディレクトリがPATHから外れると、bash: claude: command not found が出る。Linux環境ではシェル設定の更新を契機にこのトラブルが繰り返し発生しやすい。

# PATHに含まれているか確認
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

# 含まれていない場合——Bashなら
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Zshなら ~/.zshrc に同様に追記

# 確認
claude --version

重複インストールが疑われる場合は which -a claude で全パスを確認し、旧npmインストール（~/.claude/local）が残っていれば整理する。権限の問題には sudo chown -R $(whoami) ~/.local で対処する。共有ライブラリ不足（Linux）は ldd "$(command -v claude)" | grep "not found" で確認できる。

認証エラー・ログインできない

# 再認証の手順
/logout
# 再起動後に claude を実行
# ブラウザが開かない場合は「c」でOAuth URLをコピー

403 Forbidden が出る場合、Proプランなら claude.ai/settings で購読が有効かを確認する。「organization disabled」と出るのに購読が有効な場合は、古い ANTHROPIC_API_KEY 環境変数が認証を上書きしている可能性が高い。

unset ANTHROPIC_API_KEY
# ~/.bashrc 等からも該当行を削除
/status  # 認証方式を確認

WSL2・SSH・コンテナ環境でOAuthのブラウザが別ホストで開く場合は、表示されるコードを端末に貼り付ける。export BROWSER=... でWindowsブラウザを指定することもできる。

Linux固有のトラブル

インストール中に Killed が出る場合はOOM（メモリ不足）だ。Claude Codeは最低4GB RAMを必要とする（公式ドキュメントより）。スワップで対処できる。

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Illegal instruction はCPUがAVX非対応の機器（概ね2013年以前や一部VM）で起きる。grep -m1 -ow avx /proc/cpuinfo が空ならAVXがない。WSL1の Exec format error はWSL2へ移行する（wsl --set-version <Distro> 2）。

起動後に高CPU・メモリが継続する場合は /compact を実行し、大タスク間で再起動する。ハング時はCtrl+C、それでも止まらなければ端末を閉じて再起動し、同じディレクトリで claude --resume で復帰できる。

環境系の詳細な手順は Claude Codeインストール完全ガイド、基本操作全般は Claude Codeスタートガイド を参照されたい。

---

生成系でclaude 動かない——「完了しました」が偽陽性になる仕組みと見抜き方

環境系をクリアしているのにclaude 動かない、あるいは「完了した」のに実際には動いていない——この状態は、AIの生成・報告プロセスそのものに起因する。ログにエラーが出ないため発見が遅れ、対処コストが積み重なる点で厄介度が高い。

Claude Codeが「修正を適用しました。動作を確認しました」と返すとき、その「確認」は自分が生成したコードやコマンドの出力テキストを読んで判断しているにすぎない。実際にHTTPリクエストを送ってステータスコードを検証したわけでも、実画面をレンダリングして目視したわけでもない。E2Eテストが正常終了していても、そのテストが変更箇所をカバーしていなければ結果は「偽陽性」だ。

実運用で繰り返し現れるパターンは5つに収束する。

1. 「完了しました」と報告されたがブラウザで開くと404
2. E2Eテストが正常終了しているが実画面・実データを未確認の偽陽性
3. AIが自己生成したコマンドのクォート崩れ・存在しないフラグの幻覚
4. 何度指摘しても同じ失敗を繰り返す（セッションをまたぐと記憶がリセット）
5. 一箇所修正すると別の箇所が壊れる（デグレ）

証拠なしのOKは採用しない——完了の定義を変える

claude 動かないの生成系に対して実運用で機能した対処はシンプルだ。Claude Codeが「完了しました」と言ったとき、証拠を提示できなければその完了報告は保留とする。

証拠として認めるのは次のいずれかだ。

• 実際のHTTPレスポンスコード（curl -I https://... の出力）
• 変更ファイルのdiff（git diff の実出力）
• 関連テストの実行結果（変更箇所をカバーしていることの確認付き）
• APIレスポンスの実値またはDBクエリ結果

これをCLAUDE.mdに宣言しておく。

# CLAUDE.md——完了の定義
タスク完了時は以下を必ず提示する：
1. curl -I [該当URL] の実行結果（HTTPステータスコードを含む）
2. 変更したファイルの差分サマリ（git diff --stat）
3. 関連テストの実行結果
証拠を提示できない場合は「確認できていない」と明記する。

偽陽性が起きやすい典型的な場面を把握しておくと対処が早い。

• ルーティング変更後：テストは旧パスを叩いており新パスは未テスト
• ビルド未反映：コードは修正したがビルドを再実行していないため本番は旧バイナリ
• 環境変数の取り違え：ローカルでは動くがCI/CDの環境変数が異なる
• キャッシュ汚染：CDNやブラウザキャッシュが残存し修正が反映されていない（または逆）

コマンドの文法ミス・幻覚——実行前dry-runで防ぐ

Claude Codeが自分でコマンドを生成して実行するとき、そのコマンド自体に問題が混入することがある。実運用で遭遇した具体的なパターンを示す。

• クォート崩れ：シェルのクォートが閉じられていない、またはネストが壊れている
• 存在しないフラグの幻覚：--dry-run や --verbose を指定したが実際のコマンドに存在しない
• 変数名衝突：既存スクリプト内の変数名と生成コードの変数名が重複し意図しない上書きが起きる
• パスの相対・絶対混在：実行ディレクトリの前提が違い想定外のパスを操作する

Anthropic公式「Troubleshooting tool use」（platform.claude.com）でも、AIが存在しないパラメータを生成する問題への対策として、スキーマへの strict: true 設定や input_examples の追加が案内されている。自前のエージェント設計に組み込む際は参照する価値がある。

対処の基本はdry-runの習慣化だ。コマンドを生成させたら即座に実行させず、内容を確認してから実行する。

# 指示の定型文
実行する前に生成したコマンドを一行ずつ表示してください。
私がOKと言ってから実行してください。
不可逆な操作（削除・上書き・本番環境への書き込み）は必ずy/n確認を求めてください。

# ツール側のdry-run
rsync --dry-run -av /source/ /dest/
terraform plan

# dry-runがないツールはechoで代替確認
grep -r "削除対象の文字列" . --include="*.js"

---

繰り返し失敗・デグレ——「指摘」ではなく「仕組み」で止める

claude 動かないという状況の中でも、対処コストが最も積み重なるのがこの2パターンだ。

繰り返し失敗はCLAUDE.mdのガードレールに書く

Claude Codeに同じ失敗を「指摘」しても、次のセッションでは記憶がリセットされる。指摘はそのセッション内にしか効かない。繰り返しを止められるのは「指摘」ではなく「仕組み」だけだ。同じミスが2回発生したら、CLAUDE.mdに禁止ルールとして追記する。

# CLAUDE.md——禁止事項（繰り返した失敗から導いたルール）

## コマンド実行
- 実行前に必ず対象ファイル・パスを確認する
- 削除・上書きを伴う操作は必ずy/n確認を求める
- 実行ディレクトリは明示する（相対パスを前提にしない）

## 完了報告
- 「完了しました」と言うときはHTTPステータスコードまたはテスト実行結果を添える
- ビルドが必要な変更の場合はビルド実行後に確認する
- 証拠なしの「動作確認しました」は使わない

## コード生成
- 変数名は既存コードのものと重複しないよう確認してから使う
- オプションフラグは実際に存在するか確認してから使う（helpまたは公式ドキュメントで）

Claude Codeは新しいセッションを開いたとき、プロジェクトルートのCLAUDE.mdを自動的に読む。失敗を書いておけば、次のセッションでその前提が引き継がれる。CLAUDE.mdの設計については Claude Codeの実践的な使い方、スラッシュコマンドとの組み合わせは Claude Codeスラッシュコマンド解説 を参照されたい。

デグレは「変更前に本体名でgrep全件」で防ぐ

Claude Codeに「この関数を修正して」と頼むと、その関数を修正する。問題は、その関数が別の箇所でも呼ばれていることを見落とすか確認を省略することだ。A地点は直ったがB地点が壊れ、Bを直したらCが壊れる——この連鎖は、変更前の影響範囲把握を怠るときに発生しやすい。

# 変更前に必ずこれをやらせる
grep -rn "対象の関数名" . --include="*.ts" --include="*.js"
grep -rn "ClassName" . --include="*.ts"
grep -rn "CONFIG_KEY" . --include="*.ts" --include="*.env*"

Claude Codeへの指示の形は次のとおりだ。

この関数を変更する前に、プロジェクト全体でこの関数が呼ばれている箇所を
grep -rn で全件洗い出し、影響を受けるファイルとコンテキストを一覧してください。
その後、一箇所ずつ変更計画を提示してから実施してください。

影響範囲が広いとわかった場合は、一度に全部を変更させない。一箇所変更→テスト→確認→次の箇所のサイクルで進める。Claude Codeを使うと「まとめてやってもらえる」という錯覚が生じやすいが、変更を分割する意識を持つことが連鎖デグレを防ぐ。

「確実性の確認」を変更指示の前に挟む

曖昧なタスクや影響範囲が広い変更を依頼する前に、Claude Codeに確実性を問う。

この変更を行う前に、以下を教えてください：
1. 影響を受けるファイルと関数の一覧
2. この変更で壊れる可能性のある箇所
3. 確認が必要な前提条件
確実でない点があれば「不確かです」と先に言ってください。

Claude Codeは問われれば不確かさを開示できる。問われなければ自信ありげに誤りを提示することがある。確認を仕組みとして指示に組み込むことが、暴走の入口を塞ぐ。

---

失敗パターン対処早見表と検証チェックリスト

以下の表に、claude 動かないの主要パターンと対処の対応関係をまとめる。

claude 動かない——失敗パターン別の原因・対処比較表

パターン	なぜ起きるか	指摘では防げない理由	仕組みで防ぐ方法
command not found	~/.local/bin がPATHから外れている	シェル設定が変わるたびに再発する	~/.bashrc / ~/.zshrc にPATH追記を固定
403 Forbidden / 認証エラー	旧ANTHROPIC_API_KEYが認証を上書き	環境変数が残存している限り継続	unset ANTHROPIC_API_KEY + /status で確認
Linux OOM（Killed）	RAM 4GB未満またはスワップ不足	メモリ構成が変わらない限り再発	スワップファイル追加（2GB以上）
偽の正常終了（完了→404）	AIは実HTTPコードを確認していない	次のタスクでまた省略する	CLAUDE.mdに完了定義（curl確認必須）を宣言
E2E偽陽性	テストが変更箇所をカバーしていない	テストは毎回異なる	タスク指示にカバレッジ確認を明記
コマンド文法ミス・幻覚	生成時に正確さより流暢さが優先される	別の形で同じ種類のミスが出る	実行前dry-run。コマンド提示→人間確認→実行
繰り返し失敗	セッションをまたぐと記憶がリセット	指摘はそのセッションのみ有効	失敗をCLAUDE.mdの禁止ルールとして蓄積
デグレ（連鎖破壊）	影響範囲を把握せず局所修正する	次の変更でまた省略する	変更前にgrep全件→影響一覧→個別検証を必須化

検証チェックリスト（コピーして使う）

## 作業前チェック
[ ] タスクの完了条件（証拠の形）を指示に明記したか
[ ] 不可逆操作（削除・上書き・本番書き込み）にy/n確認を求めたか
[ ] 変更対象の本体名でgrep全件を実行したか（影響範囲を把握）
[ ] 環境変数・ビルドモード・URLパラメータの前提を指示に含めたか

## 完了報告受領後チェック
[ ] HTTPステータスコード（curl -I）を確認したか
[ ] 変更したファイルの差分（git diff）を目視したか
[ ] 関連テストの実行結果を確認し、変更箇所をカバーしているか確認したか

## 失敗発生時
[ ] 失敗の内容をCLAUDE.mdの禁止ルールに追記したか
[ ] 同じ失敗が他の箇所でも起きていないかgrep確認したか
[ ] 次のタスク指示に再発防止の指定を追記したか

---

claude 動かないという状況の多くは、エラーメッセージが出ない形で積み重なる。完了報告を受け取っても動いていない、テストが通っても本番が壊れている、同じミスが繰り返される——これらは全て、AIの報告を検証する仕組みが欠けているときに起きる。

環境系には公式の定型対処（PATH修正・再認証・スワップ追加）が効く。生成系には「証拠なしのOKは採用しない」という設計思想を、CLAUDE.md・dry-run・grep全件という3つの習慣で実装することが、繰り返しを止める唯一の現実解だ。

Claude Codeの全体像は Claude Code総合ガイド、料金・API費用の確認は Claude Code料金・プラン解説 および Claude Code API料金の詳細 を参照されたい。他ツールとの比較は Claude Code vs Codex比較 も読まれたい。SEOへの活用は Claude CodeとSEO入門 にもまとめている。

---

AIコーディングの安全な戦力化についてのご相談

本記事で紹介した検証の型やガードレール設計に関心のある方は、クリスタルメソッドのAI開発支援・内製化支援でご相談に応じている。詳しくはお問い合わせよりご連絡いただきたい。

---

参考文献

• Anthropic公式「Troubleshooting tool use」
  https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use
• Anthropic公式「Troubleshoot MCP tunnels」
  https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting.md
• Anthropic公式「Handle Compliance API errors」
  https://platform.claude.com/docs/en/manage-claude/compliance-errors
• デジタル庁「人間にあってAIにないものは『意思』」（2026年4月8日）
  https://digital-agency-news.digital.go.jp/articles/2026-04-08_subtitles