goal-prompt-crafter

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 へ直行してよい。

1. 単一の測定可能ゴールか — 「テストが通る」「lint がゼロ」など二値判定できるか。 複数ゴールの混在は分割するか、and で明示的に束ねる
2. 検証方法が具体か — どのコマンドの exit code / 出力を見れば達成と言えるか
3. スコープ制約があるか — 触ってはいけないファイル・変えてはいけない挙動
4. 停止上限があるか — ターン数・時間の上限 (暴走保険)
5. 評価器から観測可能か — 既定の 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 なので、保存を既定とする。書き込めない環境でのみ、同じ # 完了条件 / # 実行ブリーフ / # 仮定 の構造をメッセージ内に出力し、ユーザーが自分で保存できる形にする。

1. md ファイルに保存 (書き込める環境では必須):
   • 保存先はユーザー指定パス。未指定なら作業ディレクトリの goal-<slug>.md (slug はゴールから生成)。scratchpad が使える環境ではそちらでもよい
   • ファイル構成: # 完了条件 (Step 3-1 の条件文) → # 実行ブリーフ (Step 3-2) → Step 2 で置いた仮定があれば # 仮定
   • 保存後、ファイルパスをユーザーに報告する
2. メッセージでも提示:
   • Claude Code: /goal <条件文> をコピペ可能なコードブロックで示す。 slash command はユーザーが打つものなので、スキル側で実行しない。 実行ブリーフは初回プロンプトとして貼るか、保存した md を参照させる旨を添える
   • その他のエージェント: 条件文を「完了条件 (Definition of Done)」として返し、 自律ループの停止判定・タスク定義・レビュー基準への流用先を一言添える
   • Step 2 で仮定を置いた場合は、仮定の一覧を条件文の直後にも明示する

良い例 / 悪い例

以下の「良い/悪い」は /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 しない」等) を必ず入れる