nextaltair Goal Prompt Crafter
曖昧な要望を「自律実行エージェントまたは評価器が達成判定できる、測定可能な完了条件文」へ
練り上げる。汎用コアは完了条件設計。/goal 系コマンドを持つ環境 (Claude Code など) では
その入力文として、持たない環境では自律ループの停止条件・Definition of Done・レビュー基準として、
同じ条件文をそのまま流用できる。対象例: Claude Code、Codex CLI、Stop hook、外部オーケストレータ。
When to Use
- ユーザーが
/goal・done criteria・Definition of Done・stop condition を作りたいとき - 「達成するまで自律的に回してほしい」タスクを安全に定義したいとき
- タスク記述を、テスト・lint・build・ファイル生成・issue 消化などの二値判定できる 完了条件に落としたいとき
- 自律ループ (loop / cron / Stop hook / 外部オーケストレータ) の停止条件を設計するとき
Not for
- 1ターンで終わる単発タスク (条件文を作るまでもない)
- 要件仕様そのものの精緻化 (それは prompt-optimizer 等の要件系スキルの領分)
Target Adapters (出力先の3類型)
同じ完了条件文を、達成を判定する主体に応じて出し分ける。既定は最も保守的な output-only evaluator を想定して条件文を組む (それが通れば他の2類型にも通る)。
1. Output-only evaluator — 評価器がエージェント出力しか見ない
Claude Code の /goal が代表例。評価器 (既定 Haiku 相当の軽量モデル) は
エージェントの出力テキストのみを観測し、自分で shell を叩かない。
/goal <条件文>で設定。条件達成まで各ターン終了後に判定し、未達なら次ターンを自動開始する (Claude Code の /goal 対応版が前提。挙動は導入時に実機で確認する)- 条件文は最大 4000 字。
/goal単体で状態表示、/goal clearで解除、再指定で置換 - 検証結果は出力に現れなければ判定できない。「テストが通る」を条件にするなら、 エージェントに検証コマンドを実際に実行させ、コマンド・exit code・要約を出力させる文言を 条件文に必ず含める
- 参照: https://code.claude.com/docs/en/goal.md
2. Tool-capable evaluator / orchestrator — shell・CI・workspace を直接検査できる
外部オーケストレータや、検証器自身がコマンドを実行できる自律ループ。
検証コマンドの実行結果そのものを判定対象にしてよい (出力への転記を義務付けなくてよい)。
/goal 系コマンドを持つ環境ではその入力文として、持たない環境では自律ループの
停止条件・Definition of Done・レビュー基準としてそのまま流用する。
PR 保守のような外部状態監視 loop では、完了条件を自然言語の印象ではなく、ツールで観測できる
state predicates として定義する。例: gh pr checks が成功、isDraft == false、
期待する bot review artifact が存在、blocking comment が 0、head SHA が最後に確認した値と一致。
Codex のように /goal primitive を前提にしない環境では、この predicate 群を inline polling loop の
停止条件として扱う。
3. Human-reviewed loop — 人間が達成を確認する
条件文はレビュー基準として使う。人間が観測できるなら output-only 制約は緩めてよいが、 「二値判定できる測定可能性」は必ず保つ。
Workflow
Step 1: 入力判定 (5点チェック)
ユーザーの要望を以下でチェックし、欠けている項目だけを Step 2 で聞く。 全部そろっていれば Step 3 へ直行してよい。
- 単一の測定可能ゴールか — 「テストが通る」「lint がゼロ」など二値判定できるか。 複数ゴールの混在は分割するか、and で明示的に束ねる
- 検証方法が具体か — どのコマンドの exit code / 出力を見れば達成と言えるか
- スコープ制約があるか — 触ってはいけないファイル・変えてはいけない挙動
- 停止上限があるか — ターン数・時間の上限 (暴走保険)
- 評価器から観測可能か — 既定の output-only evaluator を想定し、出力に現れない条件 (人間の承認、外部システムの状態) を含んでいないか。tool-capable / human-reviewed の adapter (Target Adapters 参照) と分かっている場合のみ、この制約を緩めてよい
Step 2: 不足分のヒアリング
不足している軸だけを質問する。全部そろっているのに聞き直さない。
- 質問 UI があるエージェント (Claude Code の AskUserQuestion 等) ではそれを使う。 無い環境ではプレーンテキストの質問にフォールバックする
- ユーザーが不在・応答不能な文脈 (自律実行中の再帰利用など) では、 欠落軸を保守的な仮定で埋め、仮定として条件文と一緒に明示する
聞く軸と定番の選択肢:
| 軸 | 質問例 | 定番の答え |
|---|---|---|
| 検証方法 | 何を実行すれば達成と分かるか | テストコマンド exit 0 / lint 0件 / build 成功 / 特定ファイルの存在 |
| スコープ制約 | 変えてはいけないものは | 他のテストを書き換えない / 公開 API 不変 / 特定 dir 不可侵 |
| 停止上限 | 何ターン・何分で打ち切るか | or stop after 20 turns 相当 |
| 部分達成 | 全件必須か、一部除外を許すか | flaky test の除外リスト / 既知失敗の skip 許容 |
Step 3: 成果物の組み立て (完了条件 + 実行ブリーフ)
成果物は2部構成にする。完了条件文は評価器が観測する測定可能な条件、 実行ブリーフは自律ループに渡す作業指示 (サブエージェント委譲方針を含む)。
3-1: 完了条件文 (/goal に渡す部分)
[検証可能ゴール: <検証コマンド> を実行して <期待する結果> になる]
[不変制約: ただし <触ってはいけないもの> は変更しない]
[上限: 達成できなければ <N> ターンで停止する]
- output-only evaluator (既定) 向けには、検証コマンドをエージェント自身に実行・出力させる 文言にする (評価器が出力から判定できるように)。tool-capable な adapter では 実行結果そのものを判定できるので、この転記は必須ではない
- 4000 字制限内に収める。長大な背景説明は条件文に入れず、実行ブリーフへ回す
- サブエージェント委譲は「作業のやり方」なので条件文には入れない (評価器が観測するのは達成状態であって、手段ではない)
3-2: 実行ブリーフ (自律ループに渡す作業プロンプト)
自律的な複数ターン実行は、素朴に回すとメインコンテキストが調査・検証の出力で 埋まり、ループ後半で息切れする。ブリーフにはサブエージェント委譲方針を必ず含める:
## タスク
<何をするか (背景・設計指示はここに置く。条件文には入れない)>
## サブエージェント委譲方針 (必須スロット)
- 広い調査・grep・複数ファイル読みは調査系サブエージェントに委譲し、結論だけ受け取る
(メインコンテキストにファイルダンプを溜めない)
- 独立した並行作業は複数サブエージェントに fan-out する
- テスト実行・レビューなどの検証もサブエージェントに投げ、要約だけ受ける
- メインループは「委譲先の結論を統合して次の一手を決める」役に徹する
## スコープ制約
<触ってはいけないもの・変えてはいけない挙動>
- 委譲方針は削除・省略しない (欠けると素朴なシングルコンテキスト実行に退行する)
- 委譲先の呼称は対象に合わせる (subagent / task tool / worker agent / parallel agent / reviewer agent 等)
- これら委譲機能が対象エージェントに無い場合のみ、その旨を明記した上で「長いファイル ダンプを避け、調査結果を短い要約に圧縮してからメインで次に進む」方針に差し替える
Step 4: セルフチェック (アンチパターン照合)
生成した条件文を以下と照合し、該当したら Step 3 に戻って修正する:
- 曖昧語: "improve" / "clean up" / "きれいにする" — 二値判定できない
- 複数ゴールの暗黙混在: 「テストを直してドキュメントも整える」— and で束ねるか分割
- 観測不能条件: 「レビューが承認されたら」「デプロイが安定したら」— 評価器はエージェント出力しか見えない
- 検証コマンド欠落: 「テストが通る」とだけ書き、実行を義務付けていない
- 自己言及の抜け穴: 「達成したと報告する」— 報告だけで達成扱いになる条件は不可
- 上限なし: 達成不能なゴールで無限ループする保険がない
Step 5: 出力 (md ファイル保存 + メッセージ提示)
成果物はファイルシステムに書き込める環境では必ず md ファイルとして保存する
(メッセージ出力だけで終わらせない)。条件文とブリーフは長くなりがちで、後から /goal に
貼り直したり別セッションで再利用したりするため、揮発するメッセージだけでは足りない。
配布先の開発エージェント (Claude Code / Codex CLI 等) はいずれも file-capable
なので、保存を既定とする。書き込めない環境でのみ、同じ # 完了条件 / # 実行ブリーフ
/ # 仮定 の構造をメッセージ内に出力し、ユーザーが自分で保存できる形にする。
- md ファイルに保存 (書き込める環境では必須):
- 保存先はユーザー指定パス。未指定なら作業ディレクトリの
goal-<slug>.md(slug はゴールから生成)。scratchpad が使える環境ではそちらでもよい - ファイル構成:
# 完了条件(Step 3-1 の条件文) →# 実行ブリーフ(Step 3-2) → Step 2 で置いた仮定があれば# 仮定 - 保存後、ファイルパスをユーザーに報告する
- 保存先はユーザー指定パス。未指定なら作業ディレクトリの
- メッセージでも提示:
- Claude Code:
/goal <条件文>をコピペ可能なコードブロックで示す。 slash command はユーザーが打つものなので、スキル側で実行しない。 実行ブリーフは初回プロンプトとして貼るか、保存した md を参照させる旨を添える - その他のエージェント: 条件文を「完了条件 (Definition of Done)」として返し、 自律ループの停止判定・タスク定義・レビュー基準への流用先を一言添える
- Step 2 で仮定を置いた場合は、仮定の一覧を条件文の直後にも明示する
- Claude Code:
良い例 / 悪い例
以下の「良い/悪い」は /goal に渡す完了条件文の対比。実際の成果物は
これに実行ブリーフ (サブエージェント委譲方針を含む) を足して md 保存する。
完全な成果物の見本 (保存する md)
# 完了条件
uv run pytest tests/unit を実行して全件 pass し、uv run ruff check src/ が 0 件になる。
ただし tests/ 配下の既存テストは修正しない。達成できなければ 15 ターンで停止。
# 実行ブリーフ
## タスク
失敗している unit テストを修正する。実装バグが原因ならプロダクションコードを直す。
## サブエージェント委譲方針
- 失敗原因の調査 (該当モジュールの grep・関連ファイル読み) は調査系サブエージェントに委譲し、
結論だけ受け取る
- 修正後の検証 (pytest / ruff 実行) はテスト実行系サブエージェントに投げ、要約を受ける
- メインループは委譲結果を統合して次の修正対象を決める役に徹する
## スコープ制約
- tests/ 配下の既存テストは書き換えない
- 公開 import パスを変えない
テスト修復系
# 良い
/goal uv run pytest tests/unit を実行して全件 pass し、uv run ruff check src/ が
0 件になる。ただし tests/ 配下の既存テストは修正しない。達成できなければ 15 ターンで停止。
# 悪い
/goal テスト周りをいい感じに直す # 測定不可・検証コマンドなし・上限なし
リファクタ系
# 良い
/goal src/big_module.py を 3 つ以上のモジュールに分割し、各ファイルが 300 行以下に
なり、uv run pytest が分割前と同じ pass 数を維持する。公開 import パスは変えない。
20 ターンで停止。
# 悪い
/goal コードをきれいに分割する # 「きれい」は判定不能
backlog 消化系
# 良い
/goal gh issue list --label quick-fix --state open の件数が 0 になる。各 issue は
修正 commit を作り issue 番号を commit message に含める。main には push しない。
30 ターンまたは全 issue 着手済みで停止。
# 悪い
/goal issue を全部片付ける # 「片付ける」の定義がない・安全制約なし
制約・注意
/goalの仕様 (バージョン・字数上限・評価モデル) は Claude Code 側の変更で変わりうる。 挙動が説明と食い違う場合は公式ドキュメント (Target Adapters の URL) を優先する。 4000 字・output-only といった制約は output-only evaluator adapter 固有のもので、 tool-capable / human-reviewed の adapter には当てはまらない- 条件文は達成判定のためのもの。作業手順・背景・設計指示・サブエージェント委譲方針は 実行ブリーフ側に置き、条件文に混ぜない
- 成果物 (完了条件 + 実行ブリーフ) は書き込める環境では必ず md 保存し、パスを報告する。 書き込めない環境ではメッセージ内に同じ構造で出力する
- 破壊的操作 (push / deploy / 削除) を含むゴールでは、不変制約に安全境界 (「main に push しない」等) を必ず入れる