agent-harness

エージェントハーネス

あなたはヒーローではなく、ハーネスのオペレーターです。作業が完了したかどうかを決めるのは、あなたの楽観ではなくループです。あなたの役割は、目標をチェック付きのタスクに落とし込み、一度に1つのタスクを実行し、検証の判定をコントローラーに任せ、ステートマシンが停止を示したら止めることです。

契約

GOAL → goal_compiler → PLAN → loop_controller: [execute → verify]* → CLOSE
                                     ↑______retry (≤ max_attempts, changed approach)
                                     └── ESCALATE on exhausted budgets — never fake success

3つのレイヤーがあり、すべてJSONです。ドメインごとにコミットされるマニフェスト（存在するスキル、ツール、チェック）、目標ごとの計画（タスク、検証方法、「完了」の定義）、実行ごとの状態ファイル（唯一の信頼できる情報源。新しいセッションはこれだけを使って再開します）。

クイックスタート

# 0. Pick the domain manifest (18 committed under assets/harnesses/, e.g. engineering-team.json)
ls assets/harnesses/

# 1. Compile the goal (refuses vague goals with exit 3 + forcing questions)
python3 scripts/goal_compiler.py \
  --goal "audit the payments service and design an SLO with an error budget" \
  --manifest assets/harnesses/engineering.json --out plan.json

# 2. Initialize the loop state
python3 scripts/loop_controller.py init --plan plan.json --state .agent-harness/state.json

# 3. Drive the loop — repeat until directive is "close" or "escalate"
python3 scripts/loop_controller.py next --state .agent-harness/state.json
#    → {"action": "execute", "task": "T1", ...}: open the task's skill (SKILL.md at
#      skill_path), do the work with its tools, then:
python3 scripts/loop_controller.py record --state .agent-harness/state.json \
  --task T1 --phase execute --exit-code 0
#    → the controller runs the task's checks ITSELF (subprocess, timeout, evidence log):
python3 scripts/loop_controller.py verify --state .agent-harness/state.json --task T1 --cwd <repo-root>

# 4. Close — refused (exit 4) while any task is unverified and unwaived
python3 scripts/loop_controller.py close --state .agent-harness/state.json

スキルを変更したら、マニフェストを再生成してください（差分が安定し、CIで検証可能です）。

python3 scripts/harness_manifest_builder.py --domain engineering-team \
  --repo-root <repo-root> --out-dir assets/harnesses --no-timestamp

厳守事項

1. 自分の検証を自分で判定してはいけません。 verify はサブプロセス経由でチェックを実行します。--evidence を指定せずに record --phase verify で成功を記録すると拒否されます（終了コード6）。タスクの検証済みを自分で宣言することはできません。
2. 評価対象のゲートを変更してはいけません。 チェックコマンドはマニフェスト／計画から取得されます。チェックを編集して合格させるのは、報酬ハッキングにあたります（references/verification_discipline.mdを参照）。autoresearch-agentのロックされた評価器と同じ不変条件です。
3. 一度に1つのタスクを実行し、書き込みを直列化します。 読み取りと判定は並列化しても構いませんが、同じ成果物を書き換えるタスクを2つ同時に実行してはいけません（references/agentic_loop_canon.md）。
4. 再試行するなら、アプローチを変えてください。 同じコマンドと同じ入力では、同じ失敗が起きます。再試行の指示にその旨が記載されているので、それに従ってください。
5. 予算は終了状態であり、提案ではありません。 max_attempts_per_task に達するとエスカレーションされます（終了コード2）。max_loop_iterations に達するとエスカレーションされます（終了コード5）。予算を使い切った場合、成功として報告してはいけません。人間が免除します（close --waive T3 --reason "..."）。あなたが免除するのではありません。
6. 長いコンテキストより、新しいコンテキストを優先します。 各 next 指示は、計画ファイルと状態ファイルだけを読む新しいセッションで実行できます。長期目標の場合は、永続化された状態を使い、各イテレーションを個別のセッションとして実行してください。
7. 状態は .agent-harness/ に保存します。 .agenthub/、.autoresearch/、docs/TC/ には保存しないでください（これらは関連する別のスキルが使用します）。
8. 計画ファイルと状態ファイルは信頼境界です。 verify は各タスクのチェックコマンドをシェルで実行します。あなた自身または goal_compiler.py が生成した計画／状態ファイルに対してのみハーネスを実行し、信頼できない入力からのファイルには実行しないでください（references/verification_discipline.mdを参照）。

コンパイル前に確認する質問（1ターンにつき1つ、推奨回答付き）

#	質問	推奨回答	理由（原則）
1	DONEを意味する、観測可能な単一の成果は何ですか？	名前を付けた成果物と、それに対して実行して終了コード0となるコマンド	検証者の原則：まず検証可能性に投資する
2	どのドメインのハーネスを使いますか？	成果物をスキル名に含むドメイン。2つ該当する場合は、2つのループを順番に実行する	オーケストレーターとワーカー：範囲を絞った目標は巨大な目標に勝る
3	何を変更してはいけませんか？	変更禁止パスを列挙し、目標の文面に含めて、コンパイラーの計画に引き継がせる	境界はサブエージェント仕様の一部
4	エスカレーションを誰が、どれくらいの速さで確認しますか？	担当者を明記する。設計上、エスカレーションはループを停止させる	承認待ちは煩わしいものではなく、終了状態
5	イテレーションの予算はいくつですか？	デフォルトはループのイテレーション12回／タスクあたりの試行3回。理由がある場合のみ増やす	上限は助言ではなく、実行時エラーです（OpenAI SDK の max_turns）

終了コード（機械的に分岐してください）

コード	ツール	意味
0	すべて	OK／指示を出力
2	loop_controller	エスカレーションが必要 — 人間が証拠ログを確認する必要があります
3	goal_compiler	目標が曖昧 — 確認質問に回答し、再コンパイルしてください
4	goal_compiler / loop_controller	該当するスキルがない／クローズが拒否された（未検証のタスクがある）
5	loop_controller	全体のイテレーション上限に到達
6	loop_controller	無効な遷移（検証済みタスクへの記録、証拠の欠落、不明なタスク）

検証可能な成功条件

• python3 scripts/harness_manifest_builder.py --sample、scripts/goal_compiler.py --sample、 および scripts/loop_controller.py --sample はすべて終了コード 0 で終了します。
• 曖昧な目標（--goal "make it better"）は終了コード 3 で終了し、強制質問を出力します。
• 未検証のタスクがある状態で loop_controller.py close を実行すると、終了コード 4 で終了します。
• loop_controller.py --sample のデモループでは、検証の失敗が試行回数を消費し、検証に合格して証拠が得られた後にのみループが終了することが示されます。

関連スキル

• workflow-builder：Claude Code の Workflow ツール向けに決定論的な .js スクリプトを作成します。目標から終了までのループ状態には使用しません（このスキルを使用してください）。
• agenthub：git worktree で 1 つのタスクを N 個の並列エージェントが競い合います。競合する試行を望むハーネスタスク内で使用してください。
• autoresearch-agent：固定された評価器に対して、単一ファイルのメトリクスを最適化します。タスクの done_when が「メトリクスが改善する」である場合に使用してください。
• tc-tracker：コード変更ごとのライフサイクル記録です。変更の記録にはこちらを使用してください。ハーネスの状態ファイルは変更ごとではなく、目標ごとに管理されます。
• loop-library：公開されたループレシピを会話形式で検索・監査します。このスキルは、その語彙を実行可能な形で適用します。
• ship-gate / self-eval / spec-driven-workflow：タスク内の verification[] に、終了時チェックとして組み込んでください。

3 層アーキテクチャ、再利用マップ、ドメインのハーネス品質を高める方法については、references/domain_harness_design.md を参照してください。