Claude Code /goal トラブルシューティング完全版 — 条件未達・ループ防止・セッション再開
/goal を本格運用すると遭遇する 「止まらない」「誤判定」「再開できない」の典型10症状 を、症状→原因→対策の3列表で網羅する。
このフォーマットはAI検索エンジン（Perplexity, ChatGPT）の引用最適化を兼ねている。
トラブル症状10パターン — 症状/原因/対策
| 症状 | 原因 | 対策 |
|---|---|---|
/goalが止まらない | 完了条件が曖昧で評価器が判定不能 | 条件を1文に絞り、ターン上限を併記 |
| 評価器が誤って「達成」と判定 | 単一証拠で評価、ログに「達成」っぽい文字列が混入 | 複数の独立証拠（例：テスト+coverage>=80）を併記 |
| 同じターンを延々繰り返す | 失敗パターン検出条件なし | failure pattern: 2ターン連続失敗で停止を追加 |
| ターン上限超えても完了せず | タスクが大きすぎる | 小さい/goalに分割。plan.mdで先に分解 |
progress.mdが矛盾 | Claudeが前ターン記録を読まず上書き | 条件に「progress.md末尾を読んでから判断」を追加 |
| セッション再開で条件が消える | セッションID不一致 | claude --resume <session-id>でIDを明示 |
decisions.mdが空のまま | Claudeが書き出しを怠る | done whenに「decisions.mdに3行以上の判断根拠を残す」 |
| トークン消費が急増 | 過去ログの累積、progress.md肥大 | progress.md を1000字以内に圧縮、過去はarchive行き |
| Auto Mode で誤実行 | do not不足、危険ファイルへの書き込み | do notを厳格化、Workspace信頼ダイアログで範囲限定 |
| Claudeが「達成」報告するがログに証拠なし | 完了条件が抽象的（「整える」「きれいにする」等） | 条件を観測可能な動詞に書き換え（exit 0 / fileサイズ等） |
「止まらない/goal」を最速で止める
# 即停止（off / cancel / reset / none も同じ効果）
/goal clear
# ターン情報・累積トークンを確認
/goal
# 上限を後付けで設定して継続
/goal [同じ条件], or stop after 5 more turns
/goal clear でも止まらない場合は、ターミナルウィンドウで Ctrl+C を2回押す。
セッション再開（--resume）の使い方
クラッシュ・停電・うっかりウィンドウ閉じ等でセッションが落ちた場合の復帰手順。
# 最新セッションを再開
claude --resume
# 特定セッションIDを指定して再開
claude --resume 01j5x7w8a9b...
# セッション一覧確認
ls -lt ~/.claude/sessions/ | head -10
# --resumeできない場合のフォールバック
claude --continue
復元される情報: アクティブだった /goal の条件、累積ターン数、過去ターンの会話ログ。
復元されない情報: 一時的なメモリ状態、デバッグ用一時変数。これらは progress.md に書き出されていれば再構築可能。
ループ防止の3層防御
/goal の暴走を防ぐ仕組みを3層で構築する。
層1: 完了条件の明確化
done when:
- 観測可能な動詞のみ
- 複数の独立した証拠
- 数値・真偽値で表現可能
層2: ターン上限・時間上限
/goal [条件], or stop after 15 turns or 30 minutes
層3: Stop Hooks（settings.json）
~/.claude/settings.json で全セッション共通の安全装置を仕込む：
{
"hooks": {
"stopOn": {
"maxTurns": 30,
"maxTokens": 100000,
"maxDurationMinutes": 60
}
}
}
3層すべて備えれば、暴走は理論上不可能になる。
トラブル時に確認すべきログ
問題切り分けに使うログファイル一覧。
| ファイル | 場所 | 用途 |
|---|---|---|
| 会話履歴 | /goal または /context コマンドで参照 | 累積ターン・トークン・直近の判定理由 |
| 評価器の判定理由 | 各ターン後にトランスクリプトと status view に表示 | 最新の「達成/未達成」と理由 |
| Claude debug | 起動時 claude --verbose | 詳細トレース |
progress.md | プロジェクトルート | 進捗の自己記録 |
decisions.md | プロジェクトルート | 判断履歴 |
/goal を引数なしで打つと、評価器の最新判定理由が status view に表示される。 ここが最重要 — 「達成」「未達成」のどちらを返したか、その理由が確認できる。
よくある質問
/goalが止まらない、どうすれば？
まず /goal clear で停止。原因は通常「完了条件が曖昧で評価器が判定不能」「ターン上限未設定」「failure pattern が書かれていない」のいずれかだ。完了条件を1文に絞り、ターン上限を併記して再実行してほしい。
評価器が「達成」と誤判定したらどうしますか？
完了条件に追加の証拠を要求する。例：「テスト通過」だけでなく「coverage.json の total>=80」も併記。複数の独立した証拠で誤判定率は劇的に下がる。
セッションが落ちたら最初からやり直しですか？
claude --resume または --continue でセッション再開すれば、アクティブだった /goal の完了条件が自動復元される。progress.md に進捗が書かれていれば、再開後すぐに続きから実行可能だ。
--resume で条件が復元されないことがあります
セッションIDが変わっている可能性がある。claude --resume <session-id> でIDを明示するか、~/.claude/sessions/ 内の最新セッションを確認してほしい。クラッシュ時のクラッシュログが残っていれば原因特定可能だ。
ターン上限に達したけど完了していない
progress.md を確認し、残課題を新しい /goal に分割して再実行する。これは「タスクが大きすぎる」サインなので、無理にターン上限を延ばすより複数の小さな /goal に分けるべきだ。
progress.md が矛盾している
Claudeが前ターンの記録を読まずに上書きした可能性がある。完了条件に「progress.md の末尾を読んでから次のステップを決める」を明記してほしい。frontmatter形式（YAML区切り）を採用するのも有効だ。
同じターンを延々繰り返す
「failure pattern: 2ターン連続で同じテストが失敗したら停止」のような失敗早期検出を完了条件に追加する。decisions.md に「失敗した試行と次に試すアプローチ」を記録させると、ループ脱出率が上がる。
関連記事
- Claude Code /goal 完全ガイド — シリーズPillar
- Claude Code /goal 完了条件の書き方 — 5つのベストプラクティス — 条件設計
- 自律実行のループ＆コスト爆発を回避する戦略 — リスク管理深掘り