🎯 技術調査 - Claude Code /goal コマンド

調査日: 2026-05-14 / 対象バージョン: Claude Code v2.1.139 (GitHub Releases 表示: 2026-05-11 UTC / JST: 2026-05-12)
一次情報: Keep Claude working toward a goal - Claude Code Docs

概要

背景

Claude Code はターン制で動作します。
Claude が 1 ターンの作業を終えると制御がユーザーに戻り、次の指示を待ちます。
大規模な移行作業やバックログ処理のように反復が必要な作業では、ユーザーが手動で何度も次の指示を送る必要がありました。

/goal コマンドは反復コストを解消するために Claude Code v2.1.139 (2026 年 5 月、UTC ベースで 5-11、JST ベースで 5-12 公開) で追加されました。
完了条件をあらかじめ宣言しておくと、Claude が条件を満たすまで自律的に複数ターンを継続します。

位置づけ

/goal はセッションスコープの自律実行機能です。
Claude がターンを終えるたびに、小型の高速モデル (デフォルト: Haiku) が完了条件を評価します。
条件未達なら Claude が次のターンを開始し、条件達成時点でゴールが自動的にクリアされます。

類似機能との比較

/goal は「前のターンが終わったら次を開始する」仕組みです。
他のアプローチとの違いを以下に整理します。
公式ドキュメントの比較範囲は /goal / /loop / Stop Hook / Auto Mode / スケジュール機能までで、Plan Mode と TaskCreate は本記事独自の整理として並べます。

補足事項を以下に挙げます。

• /goal と Stop Hook はどちらもターン終了後に動作します。/goal はセッション限定の簡易設定で、Stop Hook は設定ファイルに保存されセッション横断で適用されます。Stop Hook を選ぶ条件は、セッション横断で恒久的に適用したい場合、またはスクリプトで非 LLM 判定 (終了コード・パターンマッチ等) をしたい場合です。
• ScheduleWakeup は時刻トリガーであり、条件達成までの自律継続を目的とした /goal とは交わりません。CI バッチで一定時刻に /goal を起動する組み合わせは可能です。
• Auto Mode は /goal と相補的な関係です。Auto Mode がターン内のツール承認を省略し、/goal がターン間の手動操作を省略します。組み合わせると完全な自律実行になります。

特徴

• 完了条件ベースの自律実行: 条件文を宣言するだけで、Claude が達成まで複数ターンを継続します。
• 独立した評価モデル: 作業中の Claude とは別の小型高速モデル (Haiku) が条件を判定し、客観的な評価を行います。
• 評価理由のフィードバック: 条件未達成時にその理由が次ターンへ渡され、Claude が方向を修正できます。
• リアルタイムの進捗表示: 経過時間・ターン数・トークン消費量をオーバーレイで確認できます。
• セッション復元: --resume または --continue でセッションを再開すると、アクティブなゴールが復元されます。
• ターン・時間制限の宣言: 条件文に「20 ターン後に停止」などのクローズを含めて実行上限を設定できます。
• 複数モードで動作: インタラクティブ・-p (非インタラクティブ)・Remote Control のいずれでも利用できます。
• 条件文の上限は 4,000 文字: 詳細な完了基準を記述できます。
• フックシステムの利用: 内部実装はセッションスコープのプロンプトベース Stop Hook のラッパーです。

構造

公式に図示されていないため、ドキュメント記述から論理的に整理した構造図です。

システムコンテキスト図

システムコンテキスト要素

コンテナ図

コンテナ要素

コンポーネント図

Goal Evaluator のドリルダウンを示します。

Goal Evaluator コンポーネント要素

データ

公式 ER 図は未提示。/goal のコマンドリファレンスおよび Hooks リファレンスのドキュメント記述から論理的に整理した概念/情報モデルです。

概念モデル

Session が 1 つの Goal を保持し、Goal の評価は Turn 単位で実施されます。
各 Turn が完了するたびに Evaluation が生成され、その結果を Transcript が記録します。

概念モデル要素

情報モデル

Session

1 セッションに対して 1 つの Goal のみ有効化できます。
セッション再開時 (--resume/--continue) に Goal は復元されますが、Turn カウント・経過時間・トークン消費のベースラインはリセットされます。

Goal

/goal <condition> で設定されます。
同一セッションで再度 /goal <condition> を実行すると既存の Goal を置き換えます。

Turn

Goal がアクティブな間、前の Turn 完了後に自動的に次の Turn が開始されます。

Evaluation

/goal はセッションスコープのプロンプトベース Stop フックのラッパーとして動作します。
各 Turn 完了後に condition_text と会話履歴がモデルに送信され、yes/no の判定と短い理由が返されます。

評価モデルはツールを呼び出せないため、Claude が会話に出力したテキストのみを根拠に判定します。

Transcript

セッションの全履歴を JSONL 形式で記録するファイルです。
評価モデルは会話履歴 (このファイル由来) をもとに Goal の条件を判定します (ファイルを直接読むかは公式に未記載)。

構築方法

前提条件

• インターネット接続が必須です。
• 対応プラットフォームは macOS 13.0 以上、Windows 10 1809 以上、Ubuntu 20.04 以上、Debian 10 以上、Alpine Linux 3.19 以上です。
• ハードウェアは RAM 4GB 以上、x64 または ARM64 プロセッサが必要です。

アカウント・認証要件

• Claude Pro、Max、Team、Enterprise、または Console (API アクセス) アカウントが必要です。
• 無料の Claude.ai プランは Claude Code へのアクセスを含みません。
• Amazon Bedrock、Google Vertex AI、Microsoft Foundry 経由でも利用できます。
• Anthropic API キーを直接使用する場合は、環境変数 ANTHROPIC_API_KEY に設定します。

インストール

ネイティブインストール (推奨)

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

• ネイティブインストールはバックグラウンドで自動更新されます。

Homebrew (macOS)

brew install --cask claude-code        # 安定版チャンネル
brew install --cask claude-code@latest # 最新版チャンネル

• Homebrew インストールは自動更新されません。手動で brew upgrade claude-code を実行します。

WinGet (Windows)

winget install Anthropic.ClaudeCode

npm (Node.js 18 以上が必要)

npm install -g @anthropic-ai/claude-code

Linux パッケージマネージャ

# apt (Debian / Ubuntu)
sudo apt install claude-code

# dnf (Fedora / RHEL)
sudo dnf install claude-code

# apk (Alpine Linux)
apk add claude-code

インストールの確認

claude --version
claude doctor   # 詳細な診断チェック

認証

claude   # 初回起動時にログインプロンプトが表示される
/login   # ブラウザプロンプトに従ってログイン

/goal 利用のための追加要件

• /goal コマンドはワークスペースでトラストダイアログに同意済みのセッションでのみ動作します。
• フックシステムの一部として動作するため、disableAllHooks が設定されている場合は利用できません。
• allowManagedHooksOnly が managed 設定で有効な場合も利用できません。
• 制限がある場合、コマンドはサイレントに失敗せず理由を表示します (v2.1.139 以降)。

利用方法

引数・サブコマンド一覧

基本構文 /goal <condition>

/goal <完了条件>

• ゴールを設定すると、その条件文がディレクティブとしてすぐにターンが開始されます。
• 別途プロンプトを送る必要はありません。
• ゴールがアクティブな間、◎ /goal active インジケーターに経過時間が表示されます。
• 1 セッションにつき 1 ゴールのみ有効です。新たに設定すると既存のゴールを上書きします。

実例を以下に示します。

/goal all tests in test/auth pass and the lint step is clean

/goal CHANGELOG.md has an entry for every PR merged this week

/goal fix the failing checkout test and stop after tests pass

状態確認 /goal (引数なし)

/goal

アクティブなゴールがある場合、以下の情報を表示します。

• 設定された完了条件
• 経過時間
• 評価済みターン数
• 現在のトークン消費量
• エバリュエーターの最新判定理由

ゴールがすでに達成済みの場合は、達成済み条件・経過時間・ターン数・トークン消費量を表示します。

クリア /goal clear (および各エイリアス)

/goal clear
/goal stop
/goal off
/goal reset
/goal none
/goal cancel

完了条件が満たされる前にアクティブなゴールを手動で削除します。

注意: /goal stop はゴールクリアの省略形であり、バックグラウンドセッションを停止する /stop コマンドとは別物です。

非対話 (headless) 実行

-p フラグでゴールを非対話モードで実行できます。

claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

• 条件が満たされるまでループを実行して 1 回の呼び出しで完結します。
• Ctrl+C で途中停止できます。

追加フラグとの組み合わせ例を以下に示します。

# ツール自動承認と組み合わせる
claude -p "/goal all tests pass" --allowedTools "Bash,Read,Edit"

# 出力を JSON 形式で取得する
claude -p "/goal fix all type errors" --output-format json

セッションの再開とゴールの復元

# 最新セッションを継続
claude -c

# セッションピッカーを開く (引数なし)
claude -r

# 特定セッションを再開 (session-id 指定)
claude -r <session-id>

• セッション終了時にゴールがアクティブだった場合、--resume または --continue で再開するとゴールが復元されます。
• ターン数・タイマー・トークン消費のベースラインは再開時にリセットされます。
• 達成済みまたはクリア済みのゴールは復元されません。

Remote Control 経由

• /goal は Remote Control 経由でも動作します。
• 非対話モードと同様に、設定した条件が満たされるまでループが継続します。

条件文の書き方

エバリュエーターは Claude の会話出力のみを判断材料にします。
ファイルを直接読んだりコマンドを実行したりしません。
Claude 自身が出力として示せる内容を条件にします。

効果的な条件文の要素を以下に整理します。

条件文の文字数上限は最大 4,000 文字です。

推奨パターン例を以下に挙げます。

/goal all TypeScript errors are resolved, tests pass with `npm test`, and no ESLint warnings remain — no other test files are modified

/goal migrate the auth module to the new API until every call site compiles and tests pass, or stop after 30 turns

/goal split large-file.ts into focused modules until each is under 300 lines, verified by running `wc -l src/*.ts`

避けるべき条件例も整理します。

1 セッションあたり 1 ゴール制約と上書き挙動

• セッション内でアクティブなゴールは常に 1 つです。
• 新しい /goal <condition> を実行すると、既存のゴールが即座に上書きされます。
• /clear で会話履歴をリセットすると、アクティブなゴールも同時に削除されます。

評価の仕組み

• /goal はセッションスコープのプロンプトベース Stop フックのラッパーです。
• 各ターン終了後、完了条件と会話内容が設定済みの小型高速モデル (デフォルト: Haiku) に送られます。
• モデルは yes/no の判定と短い理由を返します。
• "no" の場合、Claude に次のターンへの指針として理由が渡されます。
• "yes" の場合、ゴールがクリアされ達成エントリがトランスクリプトに記録されます。
• 評価トークンは主ターンの消費量に比べると軽微です。

運用

ゴール実行中のステータス確認

/goal を引数なしで実行すると、現在のゴール状態を確認できます。

/goal

表示される情報を以下に示します。

• 設定した条件文
• ゴールが動き始めてからの経過時間
• 評価済みのターン数
• 現在のトークン消費量
• 評価モデル (Haiku) が最後に返した判断理由

インタラクティブモードでは、セッション中に ◎ /goal active というインジケーターが表示され、ゴールが稼働中であることを示します。

トランスクリプトでのターン数・トークン記録の確認

各ターン終了後、評価モデルは条件が満たされているかどうかと短い理由を返します。
この判断理由はステータスビューとトランスクリプトの両方に記録されます。
セッション終了後にトランスクリプトを確認する場合は、~/.claude/projects/<project-path>/ 以下に保存されている .jsonl ファイルを参照します。

ゴールが達成されると、トランスクリプトに「achieved」エントリが記録されます。
達成済みゴールの情報 (条件・経過時間・ターン数・トークン消費量) は、同一セッション内では、その後の /goal コマンドで参照できます。

トークン使用量の詳細確認には /usage コマンドを使用します。

/usage

出力例を以下に示します。

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

途中介入の方法

ゴール実行中に Claude の動作が意図と異なると判断した場合、以下の方法で介入します。

• Escape キー押下: 現在実行中のツール呼び出しまたはターンを即座に中断します。
• 新しいゴールの設定: /goal <新しい条件> を実行すると、既存のゴールが置き換わります。
• 非対話モードでの中断: claude -p "/goal ..." で起動した場合、Ctrl+C でプロセスを停止できます。

ゴールのキャンセル方法

条件が達成される前にゴールを終了させるには、/goal clear を実行します。

/goal clear

以下のエイリアスも同じ動作をします。

/goal stop
/goal off
/goal reset
/goal none
/goal cancel

セッション全体をリセットする /clear コマンドを実行した場合も、ゴールは自動的に削除されます。

ベストプラクティス

測定可能なゴール条件の設計

ゴールの評価モデルはツールを実行しません。
Claude が会話の中で明示した情報だけを判断材料にします。
そのため、条件は「Claude 自身の出力で証明できる形」で記述します。

効果的な条件の 3 要素を以下に整理します。

1. 単一の測定可能な終了状態: テスト結果・ビルド終了コード・ファイル数・キューの空など
2. 検証手段の明示: npm test が終了コード 0 で終わる、git status がクリーンなど
3. 途中で守るべき制約: 「他のテストファイルを変更しない」など副作用の境界を含める

良い条件例を以下に示します。

/goal all tests in test/auth pass (`npm test` exits 0) and lint is clean, without modifying any file outside test/auth

ターン上限の付け方

条件文の中にターン数または時間の節を含めると、実行の上限を設けられます。

/goal all tests pass, or stop after 20 turns

Claude は各ターンで当該節に対する進捗を報告し、評価モデルもその情報をもとに判断します。

非対話モード (-p、print mode) 専用フラグとして --max-turns も使用できます (対話モードでは使用不可)。

claude -p --max-turns 20 "/goal all tests in test/auth pass"

上限に達した場合、プロセスはエラーで終了します。

無限ループ防止

/goal 自体は条件不一致が続く限りターンを繰り返します。
以下の対策を組み合わせるとループを防止できます。

• 条件に "or stop after N turns" 節を含める: 評価モデルがターン数を追跡し、上限到達と判断するとゴールを完了扱いにします。ただし自然言語条件として評価されるため、確実に止めたい場合は --max-turns を併用します。
• Stop フックによる介入: 同じファイルの繰り返し読み取り、エラーの連続発生などのパターンを検出して additionalContext で方針転換を促すスクリプトを Stop フックに登録します。decision: "block" は「停止を阻止して継続させる」挙動である点に注意します。
• --max-turns フラグの使用 (非対話モード専用): ハードリミットとしてターン数を設定します。確実な停止を保証する手段はこちらです。

Stop フックでアプローチ転換を促す介入例を以下に示します (継続させつつ別アプローチを指示する用途)。

#!/bin/bash
# ~/.claude/hooks/circuit-breaker.sh
DATA=$(jq . < /dev/stdin)
TRANSCRIPT=$(jq -r '.transcript_path' <<< "$DATA")

# 直近 3 ターンで同じエラーが繰り返されていれば停止
RECENT_ERRORS=$(tail -20 "$TRANSCRIPT" | grep -c "same_error_pattern" || true)
if [ "$RECENT_ERRORS" -ge 3 ]; then
  jq -n '{
    "decision": "block",
    "reason": "同じエラーが3回連続しました。別のアプローチを試みてください。",
    "hookSpecificOutput": {
      "hookEventName": "Stop",
      "additionalContext": "直近3ターンで同じエラーが繰り返されています。現在のアプローチを変更してください。"
    }
  }'
  exit 0
fi
exit 0

settings.json への登録例を以下に示します。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/circuit-breaker.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

コスト管理

ゴールを使用した長時間実行セッションではトークン消費が大きくなります。
以下の設定と習慣でコストを抑制できます。

• モデルの使い分け: Sonnet でゴールを実行し、複雑な設計判断のみ Opus を使用します。サブエージェントには model: haiku を指定します。
• コンテキストを小さく保つ: 無関係な作業の前に /clear を実行し、CLAUDE.md は 200 行以下に保ちます。
• MCP サーバーの絞り込み: 使っていないサーバーは /mcp で無効化します。各サーバーの定義がターンごとにコンテキストに追加されるためです。
• エフォートレベルの調整: 単純な繰り返し作業には /effort low を使用します。
• 予算上限の設定 (非対話モード専用、print mode のみ): --max-budget-usd フラグで金額上限を設けます。

claude -p --max-budget-usd 5.00 "/goal all tests pass"

• /usage でのリアルタイム監視: ゴール実行中でも別ターミナルから /usage で消費状況を把握できます。

ワークスペース単位の支出上限は Claude Console の Workspace Limits で設定できます。
Bedrock・Vertex・Foundry 環境では LiteLLM などのゲートウェイを使うと API キー単位のコスト追跡が可能です。

副作用の制約

ゴール条件の中に「変更してはいけないファイルやディレクトリ」を明記すると、副作用を制限できます。

/goal all tests in test/auth pass, without modifying any file outside the src/auth directory

さらに強い制約が必要な場合は --allowedTools で使用可能なツールを限定します。

claude -p --allowedTools "Read,Bash(npm test *),Bash(git status *)" \
  "/goal all tests pass"

CI / 非対話モードでの安全運用

CI 環境でゴールを使用する際は、以下のポイントを守ります。

• --permission-mode dontAsk または acceptEdits を指定: パーミッションプロンプトで処理が止まらないようにします。
• --max-turns と --max-budget-usd を両方設定: ターン数と金額の両面でセーフガードを設けます。
• --output-format json で結果を構造化出力: total_cost_usd や session_id を後続処理で活用できます。

CI での使用例 (シェル) を以下に示します。

claude -p \
  --permission-mode acceptEdits \
  --allowedTools "Bash(npm test *),Read,Edit" \
  --max-turns 30 \
  --max-budget-usd 10.00 \
  --output-format json \
  "/goal all tests pass and lint is clean"

GitHub Actions ワークフローでの最小例を以下に示します。

- name: Run /goal
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p \
      --permission-mode acceptEdits \
      --max-turns 30 \
      --max-budget-usd 10.00 \
      --output-format json \
      "/goal all tests pass and lint is clean"

/goal はフックシステムを使用しているため、disableAllHooks や allowManagedHooksOnly が有効な環境では使用できません。
その場合は Stop フックを直接設定するか、--max-turns による代替手段を使用します。

トラブルシューティング

症状・原因・対処 一覧

デバッグ方法

フックの評価ログを詳細に確認するには --debug フラグを使用します。

claude --debug "hooks" -p "/goal all tests pass"

特定ファイルにデバッグログを書き出す場合は以下を使います。

claude --debug-file /tmp/claude-goal-debug.log "/goal all tests pass"

Stop フックの入力を確認する最小構成フックの例を以下に示します。

#!/bin/bash
# デバッグ用: Stop フックに渡される全入力をログに書く
jq . < /dev/stdin >> /tmp/stop-hook-input.jsonl
exit 0

まとめ

Claude Code v2.1.139 で追加された /goal コマンドは、完了条件をセッションに宣言するだけで Claude が条件達成まで自律的に複数ターンを継続する機能です。
内部はセッションスコープの prompt-based Stop Hook ラッパーで、設定済みの小型高速モデル (デフォルト: Haiku) が各ターン後に yes/no を判定し、条件文には「or stop after N turns」「他ファイルを変更しない」などの上限・副作用制約も自然言語で記述できます。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNS でのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント
  • Keep Claude working toward a goal - Claude Code Docs
  • Commands reference - Claude Code Docs
  • Hooks reference - Claude Code Docs
  • Automate workflows with hooks (Guide) - Claude Code Docs
  • Run Claude Code programmatically (headless) - Claude Code Docs
  • Claude Code クイックスタート
  • Claude Code セットアップ (詳細)
  • CLI reference - Claude Code Docs
  • Manage costs effectively - Claude Code Docs
  • Settings - Claude Code Docs
• GitHub
  • Releases · anthropics/claude-code (公式 Changelog)
  • Release v2.1.139 · anthropics/claude-code
• 記事
  • Claude Code 2.1.139 adds /goal command - explainx.ai
  • Claude Code v2.1.139 Release Notes - ClaudeWorld
  • Claude Code コマンドチートシート - scriptbyai.com
  • Claude Code Changelog - claudelog.com
  • Claude Code Token Optimization - Build to Launch
  • 23 Tips for Smart Claude Code Token Saving - Analytics Vidhya
  • Claude Code Autonomous Mode Guide - pasqualepillitteri.it
  • Claude Code as an Autonomous Agent: Advanced Workflows 2026 - SitePoint