harness-engineering

ハーネスエンジニアリング

ハーネスエンジニアリングでは、エージェントを取り巻く制御システムを設計します。エージェントが編集できる対象、フィードバックの受け取り方、状態の書き込み先、失敗からの復旧方法、取り消せない操作を誰が承認できるかを定めます。ハーネスがあることで、単に役立つエージェントとのセッションと、目的を損なうことなく何日も実行できる自律ループとの違いが生まれます。

使用するタイミング

次のような場合に、このスキルを使用します。

• 自律的な調査ループや実験ループを構築する場合
• 指標がロックされ、コードやコンテンツを編集できるエージェント環境を設計する場合
• PR を作成するエージェントやバックグラウンドエージェントを作成する場合
• 人間から頻繁にプロンプトを受け取らずに、エージェントを安全に実行できるか評価する場合
• エージェントのワークフローに新規性の確認、アブレーション、プルーニング、ロールバック、永続的なログ記録を追加する場合
• エージェントによるベンチマークの不正利用や評価基準の弱体化を防いだり、コンテキスト圧縮時の状態消失を防いだりする場合

ほかのスキルが担当する関連作業には、このスキルを使用しないでください。

• 自律制御の仕組みを伴わない、一般的な品質ゲート、回帰テストスイート、成果指標：evaluation。
• ハーネスツールのツールスキーマ、応答形式、復旧エラー：tool-design。
• プロジェクトレベルのタスクとモデルの適合性、パイプラインの構成、コスト計画：project-development。
• リモートサンドボックス、ウォームプール、ホスト型セッションのインフラストラクチャ：hosted-agents。

コアコンセプト

ハーネスの境界

エージェントと、そのエージェントが動作する環境を分離します。エージェントがアクションを提案し、ハーネスが許可される操作対象、フィードバック、永続化、昇格ルールを定めます。

4 種類の操作対象を使用します。

操作対象	例	ルール
ロック済み	評価指標、評価基準、検証スクリプト、マージポリシー	エージェントは読み取りと変更の提案はできますが、ルールを変更して自分自身を評価することはできません
編集可能	スキルのドラフト、実験ファイル、プロンプト、テスト対象の設定	エージェントはループの実行中に変更できます
追記専用	結果ログ、調査スレッド、却下されたアイデア	エージェントは追記できますが、書き換えることはできません
人間が管理	マージ、本番環境へのデプロイ、認証情報、破壊的な操作	人間による明示的な承認が必要です

素早いフィードバックループ

フィードバックが迅速で、曖昧さがなく、不正利用しにくいとき、自律性は機能します。Karpathy の autoresearch は最小限のパターンです。編集可能なファイルが 1 つ、ロックされた評価ファイルが 1 つ、固定された実時間の予算、単一のスカラー指標、Git によるロールバック、永続的な結果ログで構成されます。ここでの教訓は、すべてのハーネスに指標が 1 つ必要だということではなく、フィードバックが曖昧だと自律的な動作も曖昧になるということです。

自由度の高い調査からスキルを作成する作業では、スカラー指標の代わりに、ロックされた評価基準、決定論的な構造チェック、情報源の追跡可能性、人間によるレビューのしきい値を使用します。

永続的な状態

長時間実行するエージェントは、状態を外部に保存する必要があります。計画、情報源のキュー、結果、失敗、引き継ぎ内容をファイルに保存し、後続のエージェントがチャット履歴に頼らずに作業を再開できるようにします。Prime Intellect の自律型 nanoGPT の取り組みからは、永続的なスクラッチパッドと THREAD.md 形式のログが、復旧、監視、監査に役立つことが示されました。

次の内容は追記専用ログに記録します。

• 試したこと
• 改善または失敗したこと
• 候補を採用、破棄、またはレビューに回した理由
• 確認した上流の情報源
• 次のエージェントが行うべきこと

探索の規律

エージェントは、最も近い操作対象を悪用し、複雑さを積み重ね、プルーニングを十分に行わない傾向があります。明示的な探索ルールを追加します。

1. スケジュールに従って上流の情報源を更新します。
2. 大きな予算を使う前に、新規性の確認を必須にします。
3. 同じものを再発見しないよう、却下した試行を保持します。
4. 複数の追加要素があるスタックに対して、リーブワンアウト・プルーニングを実施します。
5. 品質が同等の場合は、簡素化を優先します。
6. 昇格の前に、独立した検証を行います。

メカニズムレジストリ

調査からスキルを作成するシステムでは、採用されたメカニズムを文章とは別に追跡します。メカニズムの記録には、安定した mechanism_id、owning_skill、status、有効化シナリオ、動作の変化、エビデンス、失敗モードを含めてください。新規性の判定では、より広範なコーパスとの重複を調べる前に、このレジストリと照合します。キーワードの重複で検出できるのは古い表現ですが、メカニズムの比較では実際の重複を検出できるためです。

ガバナンス

自律型エージェントが PR を準備することはできますが、ガバナンスは明確に定める必要があります。エージェントは変更の下書きを作成し、チェックを実行し、PR の概要を作成できます。ユーザーが特定の操作について明示的に許可していない限り、人間の承認なしにマージ、デプロイ、プッシュを行ってはいけません。

詳細なトピック

オートリサーチ形式のループ

安定した評価器に対してアーティファクトを最適化する場合に、このパターンを使用します。

read locked context -> choose hypothesis -> edit allowed surface -> commit/checkpoint
-> run evaluator -> log result -> keep if better -> discard or rollback if worse
-> repeat

必須の特性：

• 評価器が編集可能な範囲の外部にある。
• 試行を比較できる程度に、フィードバックの間隔が一定である。
• 失敗した試行の監査証跡が残る。
• ロールバックのコストが低い。
• クラッシュやタイムアウトに対するポリシーがエージェントにある。

調査からスキルを作成するループ

ソースをスキルの変更に反映する場合に、このパターンを使用します。

discover -> retrieve -> gate -> score -> extract mechanism
-> map to existing or new skill -> draft proposal -> validate structure
-> prepare PR -> human review

ロックされた評価器は、ソースの評価基準、スキル変更の評価基準、構造チェック、レビュアーの承認を組み合わせたものです。編集可能なアーティファクトは、提案されたスキルの差分です。

指標の攻略への耐性

最適化を行うエージェントはハーネスを学習すると想定してください。次の点に注意してください。

• 評価コードや評価基準を編集してから、新しいバージョンを使って自己承認する
• 評価者には好まれるものの、スキルの有効化を損なう冗長な内容を追加する
• 取得していないソースを引用する
• 重要な評価項目で失敗しながら、全体スコアを最適化する
• 失敗した結果をログに残さない

緩和策：実行ごとに評価基準をロックし、評価項目ごとのスコアを報告し、ソース取得のエビデンスを必須にし、却下された試行を保持し、ガバナンスの変更を人間によるレビューに回します。

エージェントの監視

長時間の実行には監視エージェントを使用します。ただし、明示的に指示された場合を除き、読み取り専用の報告に制限してください。監視の出力では、次の項目を報告します。

• 現在の最良候補
• 実行中のジョブまたは下書き
• 最後に上流を更新した時点
• 失敗したループまたは古くなったループ
• ログと申告された状態の不一致
• 次のアクションとブロッカー

実践ガイド

ハーネス設計チェックリスト

1. 目的を一文で定義します。
2. ロックされた範囲、編集可能な範囲、追記専用の範囲、人間が管理する範囲を特定します。
3. フィードバックの仕組みを選びます。単一のスコア、評価基準、決定論的テスト、人間によるレビュー、またはそれらの組み合わせです。
4. 維持、破棄、クラッシュ、タイムアウト、レビューの各状態を定義します。
5. ループの開始前に、永続的なスレッドログを作成します。
6. 長時間実行されるループには、ソースの更新、メカニズムレジストリによる新規性の判定、プルーニングのルールを追加します。
7. エージェントが確認なしで実行できる操作と、承認が必要な操作を定義します。
8. 既知の良好なアーティファクトと既知の不良なアーティファクトをそれぞれ一つ使って、ハーネスを検証します。

ファイル構成

research-run/
  THREAD.md
  sources/
    queue.md
    evaluations/
  proposals/
  logs/
    results.tsv
    rejected.md
  drafts/

追記専用の機械可読ログには TSV または JSONL を使用します。引き継ぎやレビュアー向けの概要には Markdown を使用します。

例

例 1：ロックされた指標

エージェントは train.py を最適化しますが、データの読み込みと評価は prepare.py が担います。エージェントはモデルを編集できますが、指標は変更できません。失敗した実験はログに記録され、ロールバックされます。

例 2：ロックされた評価基準

エージェントは新しい Anthropic または OpenAI のエンジニアリング関連の投稿を評価しますが、実行中はソース選定の評価基準がロックされています。ソースが基準を満たすと、エージェントはスキルの提案を作成します。ソースを採用するために、評価基準のしきい値を下げることはできません。

例 3：自動マージなしの自動 PR

エージェントは、ソース、スキル、構造のチェックに合格した後、ブランチと PR の本文を準備します。PR には未解決のリスクが記載され、人間によるマージ承認を待ちます。

ガイドライン

1. ループを開始する前に評価器をロックします。
2. 信頼性の高い差分を得られるよう、編集可能な範囲を狭く保ちます。
3. コンテキストの圧縮で状態が失われる前に、永続的なログを書き込みます。
4. 集計スコアだけでなく、次元ごとのスコアを報告します。
5. 引用する前に、ソースを取得することを必須にします。
6. 幅広い検索には新規性ゲートを、複雑なスタックには刈り込みゲートを追加します。
7. 品質が同等なら、簡素化を優先します。
8. PR の準備とマージの権限を分離します。
9. ハーネスの変更は、新旧両方の評価器で再検証します。
10. 自律ループが停止した場合は、エージェントの性格上の問題ではなく、ハーネスの障害として扱います。

注意点

1. 変更可能な評価器：エージェントが指標を編集できると、タスクではなくベンチマークを最適化する可能性があります。実行中はルーブリックと評価コードをロックしておきます。
2. チャットだけの記憶：計画が会話履歴にしかないと、コンテキスト圧縮後に長時間の実行が失敗します。最初からスレッドログと結果ファイルを書き込みます。
3. 破棄記録がない：却下した試行のログがないと、エージェントは失敗したアイデアを繰り返します。再発見を防げるだけの詳細とともに、失敗を保存します。
4. 複雑さの蓄積：エージェントは変更を積み重ね、削除することはほとんどありません。刈り込みラウンドを必須にし、同等の品質を保つ簡素化を評価します。
5. 時期尚早な新規性の主張：エージェントは既存要素の組み合わせを新規性のあるものとして扱います。新規性を主張する前に、既存のリポジトリスキル、ソースキュー、却下ログと比較します。
6. モニターの誤報：監視エージェントは古い状態や矛盾した状態を要約することがあります。主張の根拠となるファイルやログを引用させます。
7. 人間による承認の曖昧さ：「PR を準備する」は「PR をマージする」ことではありません。ハーネス内で承認の境界を明確にします。
8. 変動の激しいソースの陳腐化：急速に変化する研究機関の主張はすぐに古くなります。日付入りの証拠を参考資料に記載し、再検証を予定します。

統合

このスキルは、以下と連携します。

• evaluation - ルーブリックと品質ゲートにより、フィードバックの範囲をロックできます
• advanced-evaluation - ペアワイズ比較とバイアス軽減により、提案のレビューを改善できます
• filesystem-context - 永続的なログ、スクラッチパッド、スレッドファイルにより状態を保持できます
• multi-agent-patterns - リサーチャー、検証者、モニター、ライターの各エージェントには、分離されたコンテキストが必要です
• tool-design - ハーネスのツールには、明確な契約と復旧エラーを備える必要があります
• project-development - ファイルベースのパイプラインとタスク・モデル適合性の分析により、ループをシンプルに保てます
• hosted-agents - バックグラウンド実行には、サンドボックス、スナップショット、承認の境界が必要です

参考資料

内部資料：

• researcher/README.md - リポジトリに適した、リサーチからスキルを作成する運用システムを実装する際に参照します
• researcher/rubrics/harness-change.md - エージェントハーネスの変更を評価する際に参照します
• researcher/runbooks/autonomous-research-loop.md - ソースからスキルを作成するループを実行する際に参照します

外部リソース：

• Karpathy の autoresearch - 評価をロックした、制約付きの自律実験ループ
• Prime Intellect の自律型 nanoGPT スピードラン - 永続的なスクラッチパッド、引き継ぎ、監視、自律性の失敗モード
• AlphaEvolve と FunSearch - 系統的な評価器と組み合わせた、LLM 生成の候補
• HELM と LM Evaluation Harness - 透明性が高く、再現可能な評価基盤

---

スキルのメタデータ

作成日：2026-05-14 最終更新日：2026-05-15 作成者：Agent Skills for Context Engineering Contributors バージョン：1.1.0