goal-loop

エージェントの/goalループ

/goalとは

/goalを使うと、エージェントはplan → act → test → review → iterateのサイクルを継続します。 目標を達成する前にターンが終了した場合、入力を待たずに自動で続行します。ループは、停止条件に達したとき、ユーザーが一時停止したとき、またはトークン予算の上限に達したときに終了します。「Ralphループ」とも呼ばれます。

実行時の手順を案内する前に、ヘルプ、公開されているツール、または最新の公式ドキュメントを参照して、インストール済みのエージェントとインターフェースが目標設定に対応しているか確認してください。機能フラグ、認証、制限を検証し、あるエージェントの要件を別のエージェントに適用しないでください。ライフサイクルの状態、予算、一時停止と再開の方法は、実行環境によって異なります。

目標は、検証を通じて契約を適用するものです。予算を指定するコマンドでも、安全境界でも、「永遠に実行する」指示でも、/planの代替でもありません。

使用する場面

テストの合格、目標カバレッジの達成、eval ≥ X、ビルドの成功など、検証可能な停止条件がある自律的な反復作業に使用します。コード作業では、まずビルドが正常に動作し、関連するチェックが実行できる状態にしてください。タスクの所要時間に最低条件はありません。

適した用途：移行、カバレッジの向上、TDDによる機能開発、契約テストを伴うリファクタリング、プロンプトやevalの最適化、デプロイの再試行ループ、バグの再現と修正。

適さない用途：探索的な作業、「改善する」のように曖昧なタスク、完了の定義がない作業、本番環境の認証情報、共有インフラに対する破壊的な操作。

4つの要素からなる契約（すべての目標に必要）

1. 目的 — 具体的な成果を1文で記述します。
2. 制約 — 変更してはならないもの（公開API、ファイル、ライブラリ、規約）を指定します。
3. 検証コマンド — 進捗を証明する正確なシェルコマンド（pytest -q、pnpm testなど）を記述します。
4. 停止条件 — 「Xに合格したら停止」または「これ以上の変更に人間やプロダクト担当者の入力が必要になったら停止」のように、検証可能な条件を指定します。

最初に読むもの、チェックポイント、簡潔な進捗ログも指定してください。

目標の作成（主要な成果物）

目標プロンプトを求められたら、Markdownブロック内に契約本文のみを返し、各項目を1行ずつ記述してください。/goalは先頭に付けないでください。そのコマンドはユーザーが入力欄に追加します。

**Objective:** <one-sentence objective>
**Read first:** <files/PLAN.md/issue>
**Constraints:** <what not to change, libs, conventions>
**Validate:** <relevant checks during work and final acceptance command>
**Checkpoints:** work in checkpoints and log progress briefly
**Stop when:** <verifiable condition>, OR when further changes require human/product input

例（移行）

**Objective:** Migrate this project from Pydantic v1 to v2.
**Read first:** pyproject.toml, src/, tests/
**Constraints:** no public API changes; keep imports backwards-compatible via shims if needed; no new dependencies
**Validate:** run relevant tests during the migration; run `pytest -q` before declaring done
**Checkpoints:** work in checkpoints; log progress briefly
**Stop when:** full suite passes with zero deprecation warnings, OR when a change requires architecture decisions

例（カバレッジの向上）

**Objective:** Raise coverage in src/auth/ from ~38% to ≥75%.
**Read first:** src/auth/, tests/auth/, AGENTS.md
**Constraints:** no new deps; mirror existing test style; do not modify production code unless strictly required for testability
**Validate:** `pytest --cov=src/auth --cov-report=term-missing`
**Checkpoints:** work in checkpoints; log coverage delta each one
**Stop when:** coverage ≥75% AND all tests pass, OR when uncovered code needs design changes

作成ルール

• **目的は1つ、停止条件も1つです。**バックログにしないでください。
• 動作、セットアップ、使用方法の説明が必要な場合、またはタスクで求められる場合は、ドキュメントを更新してください。
• 変更内容と最終的な受け入れ基準に合わせてチェックを設定してください。編集のたびに全テストを実行する必要はありません。
• エージェントに新しいADRを作成するよう指示しないでください。ADRの作成にはユーザーの明示的な承認が必要です。目標プロンプトで事前承認したり、作成を促したりしてはいけません。
• 報酬のハッキングを禁止してください：「目標に合格するために、テストを削除、スキップ、弱体化、または対象範囲の縮小をしないでください」と記述します。
• 実行環境の文字数制限を守ってください。詳細が長い場合は、PLAN.md／GOAL_BRIEF.mdにリンクしてください。
• 正確なパス、コマンド、イシュー番号を使用してください。
• スコープの拡大を明示的に禁止してください：「無関係なコードをリファクタリングしないでください。依存関係を追加しないでください」と記述します。
• 一時停止する条件をエージェントに伝えてください：「<条件>の場合は、一時停止してから続行前に確認してください」と記述します。

別のエージェントと下書きを作成する

別のAIセッションにコードベースへのアクセスを許可します。コードを調査して前提、制約、エッジケースを洗い出し、4つの要素からなる契約を構造化して作成するよう依頼してください。その契約を目標エージェントに貼り付けます。

Claude Codeのcmuxに関する注意：Claudeが処理を終えると、次にユーザーが送ると予測したメッセージが入力欄に事前入力されることがあります。その下書きはClaudeが作成したものであり、ユーザーが発言したものではありません。

自分で目標を設定する

create_goalなど、対応している目標作成ツールを使用するのは、ユーザーが目標の設定を明示的に依頼した場合に限ります。ユーザーは「このリポジトリを調査してから、検証可能な停止条件を含む/goalを自分で作成し、それに取り組んでください」のように、高水準の意図を伝えることができます。その場合は、読み込むファイル、制約、検証コマンドを指定してください。意図が不明確な場合は、目標を設定する前に確認の質問をしてください。

ゴールの開始と制御

1. エージェント、バージョン、インターフェース、および対象の作業ディレクトリまたはセッションを特定します。
2. サポートされているゴール関連のコマンドやツールと、セットアップや認証の要件を確認します。
3. 実行環境でサポートされているインターフェースを使い、合意した契約に従ってゴールを開始します。
4. ゴールが実行中であることを確認し、状態の確認、一時停止／停止、再開の方法を把握します。

セッションをまたいで再開する前に、その実行環境でゴールの状態がどこに保存されるか、またどのセッションを再度開く必要があるかを確認します。サーバー側で状態が保持されること、ユーザー入力時に自動で一時停止すること、置き換え動作、または予算の更新後に再開されることを前提にしないでください。

ゴールが逸脱した場合

• 軽微な逸脱： 修正指示を送り、エージェントがそれを反映したことを確認します。
• 曖昧な目標： 実行環境でサポートされている一時停止／停止操作を使い、状態を確認してから、目標を明確にして再開します。
• 深刻な問題： ゴールを停止し、差分を確認して、その実行に属すると特定できた変更だけを元に戻します。ユーザーや他のエージェントの作業は保持し、全体を一括でリセットしたり、スタッシュしたりしないでください。再開する前にゴールを書き直します。

逸脱を見つけたら、速やかに修正するか停止してください。

運用上のヒント

• 実行環境でサポートされているコマンドまたはツールを使い、定期的に状態を確認します。監視の確認を行うたびに、エージェントが何をしているか、予定どおり進んでいるかを簡潔な一文でユーザーに伝えてください。
• マージする前に、必ず差分を確認します。 人間による監督は引き続き不可欠です。
• 承認やサンドボックスの設定は厳格に保ち、デフォルトの権限を使用してください。
• 一晩中実行する前に、まず小さなタスクで実行環境の停止方法を確認します。一晩中実行するには、スリープしないマシンが必要です。ノートパソコンを閉じた状態で Claude Code を実行し続ける方法を参照してください。
• 繰り返し適用するポリシーは AGENTS.md に記載し、各ゴールで言い直さなくてもすべてのゴールに適用されるようにします。完了を宣言する前の敵対的な視点での自己レビュー、テストが通っていても追加で行う QA パス、標準の検証コマンドを含めます。各ゴールの説明で繰り返す手間を省けます。

トラブルシューティング

• ゴールコマンドが見つからない： 更新や設定変更を提案する前に、インストール済みのエージェントとインターフェースでサポート状況とセットアップを確認します。
• 開始または続行できない： 実際のエラー、ゴールの状態、認証、制限を調べます。その実行環境で文書化されている復旧手順に従います。
• 保存済みのゴールがない： 置き換えを作成する前に、セッションと状態の保持動作を確認します。