agent-harness-engineering

AI Agent Harness 工程宪章

Harness 是让模型作为 Agent 运行的整个系统 — 包括 Agent 循环、工具界面、上下文组装、护栏/授权、状态与持久性、停止条件、评估、可观测性。

Agent 的成果并非只由模型决定。同一模型在不同 Harness 下的成功率可能相差很大（Harness 敏感性），而且已有实证表明，Harness 导致的性能差异可能超过模型导致的差异。Harness 工程的目标是：最大限度地发挥模型能力，同时通过确定性机制提供绝不能交由模型负责的保障。

---

0. 核心公理

这些公理有意在 agent-harness-engineering / agent-native-project-design 这两个技能中保持相同内容（修订时须同时更新两个文件）。同时，应确保与 mastra-ai-architecture-rules 中的“设计根本原则”保持一致。

1. 判断交给模型。保障交给 Harness。确定性执行交给代码。 将 LLM 集成到服务中时（包括验证），开发者和编码 Agent 往往会用自己编写的代码决定本应交由 LLM 判断的事项。在添加用于判断的代码之前，应先考虑能否将该判断交给 LLM。
2. Agent = 模型 + Harness。同一模型的成果会因 Harness 而大幅变化。 Harness 是需要优先改进的一等变量。
3. 核心循环是 “收集上下文 → 行动 → 验证”。验证的设计决定质量上限。
4. 从尽可能简单的结构开始，只有在必要性得到验证后才增加复杂性。 最成功的实现并非使用复杂框架，而是采用简单、可组合的模式。
5. 上下文是有限资源，但不能靠丢失信息来节省。 要最大限度提高期望结果可能性的最小高信号 token 集合，不应靠删减内容来构建，而应区分哪些内容直接放入上下文，哪些内容可按需获取。放入上下文的范围应由用户请求的目的决定；范围内的内容不得截断，范围外的内容则应向模型说明其位置和获取方式，使其能够访问（即使看起来已足够，也要保留获取方式）。由模型决定还要读取哪些内容。开发者和编码 Agent 容易走向两个极端：返回与目的无关的全部内容，或按字符数、条目数的固定值静默截断。允许设置的上限只能是接收方实际具备的限制；超过限制时，不要截断，而应通过文件等方式提供完整内容。不可逆的压缩与摘要，应先确认不压缩也能保证质量，只有在上下文量成为显著问题后再引入。保留 reference，而非 payload；保留 decision，而非 transcript。
6. 指示是建议性的（advisory），代码与门控是确定性的保障（deterministic）。 绝不能把必须 100% 遵守的要求放在指示（提示词）中。代码负责检查封闭集合（ID、enum、schema、DB 行、权限、状态转换），保障安全、授权和不可逆副作用，并收集用于判断的事实。对于无法通过枚举穷尽的对象，例如自然语言措辞、意图、响应是否合理，不要用正则表达式、词语列表、例外分支或固定文本进行判断，而应交由 LLM 判断。
7. 安全依靠隔离，而非监控；但决定授权范围的是用户。 此处的用户是指将工作委托给 Agent 的人（在服务中是使用者；在使用 Claude Code / Codex 进行开发或 CI 时是相应的开发者）。开发者和编码 Agent 往往会因自身顾虑而削弱能力，并固定禁止项或审批要求。不要以风险为由拒绝提供能力，而应向用户说明风险并由其决定。先定义边界（sandbox、权限），只对越过边界的操作请求审批。fail-closed 仅用于授权信息缺失或无效（无法确认代理的是谁）、无法确认管理员限制，以及安全或不可逆副作用的保障。将 LLM 集成到服务中时，应使 Agent 能做的事情与其代理的人类能做的事情保持一致。上限应是被代理人自身的权限，并由代码保障（用户许可后，人类能够访问的信息都应可供 Agent 访问）。在上限范围内，服务应提供设置，让用户可按操作（或操作类型）选择“完全委托（allow）／审批后委托（ask）／禁止（deny）”，并由 Harness 以确定性方式执行。风险应通过未设置时的默认值和向用户披露来处理，不要以 fail-closed 为由禁止用户尚未设置的操作。
8. 停止条件、预算和升级机制是 Harness 的一等公民。 不要事后才添加。
9. 模型每次变得更聪明，都要精简 Harness。 “以前有必要”不代表“现在仍有必要”。更换默认模型时，应列出指示中的约束，以及验证和代码中的确定性判断，并说明添加它们的原因，然后移除可以删去的内容。
10. 从失败中总结出的规则必须保留其原因。 Harness 是由事件驱动、渐进强化的资产。但不要为每一次失败都添加一条规则，而应总结多个失败共同体现的原则。

适用优先级：已采用特定运行时的项目，应以该运行时的宪章（例如 Mastra 项目的 mastra-ai-architecture-rules）优先于本技能的一般规则。同样，如果仓库中存在由人维护的权威宪章或设计文档（例如 l-shift 的 agent/AGENTS.md 和 agent/docs/ 下的权威设计文档），则以该权威文档优先于本技能。本技能为没有宪章的领域提供决策依据，也为设计和修订宪章本身提供基础。如果发现本技能与项目权威文档存在冲突，不要默默遵循其中一方，而应将差异提请用户处理。

---

1. Harness 采购决策

Harness 不是“自建或不自建”的二元选择，而是从一系列抽象层级中选择：

原生 LLM API + 自建循环 → Agent SDK（Claude Agent SDK / OpenAI Agents SDK 等） → 无头使用现成 Harness（Claude Code / Codex CLI 等） → 托管服务

决策流程：

1. 如果已采用运行时，就遵循该运行时的宪章（Mastra 项目遵循 mastra-ai-architecture-rules）。复用优先于自建（reuse > build）。自建是最后手段。
2. 如果是新项目，请针对每种 workload 根据以下标准选择抽象层级：

判断标准	倾向低抽象（原生 API/自建）	倾向高抽象（SDK/现成 Harness）
Agent 是否需要计算机能力（文件、shell、代码执行）？	不需要（对话型、API 编排型）	需要（最能继承 coding agent 系的价值）
是否需要多租户授权、定制权限门控？	需要（自行掌控介入循环的切入点）	不需要或很简单
是否需要服务端常驻、暂停/恢复、持久执行？	需要（将 checkpoint 作为一等设计）	不需要（会话内完成）
上下文组装、缓存 prefix 的确定性控制是否决定成本？	是	否
Harness 本身是否是产品的差异化要素？	是	否（“不做差异化的 Harness，就购买现成的”）

3. 无论采用哪种采购方式，都不要放弃以下三项所有权：own your prompts / own your context window / own your control flow。现成循环的质量上限，主要受隐藏提示词、上下文和控制流的黑盒抽象影响。
4. 判断是否可以购买抽象层的测试：“发生故障时，能否一步定位到实际发送给模型的 token 序列？” 无法定位到该序列的抽象层不要购买。
5. 通过“重建次数”估算自建的实际成本。即使是前沿实现，也经历过多次重建。如果没有能够投入反复迭代的组织条件，自建就不可行。

详细的比较表与迁移触发条件：references/procurement.md

---

2. コアループ設計

エージェントループの実体は「プロンプト構築 → モデル呼び出し → ツール実行 → 履歴追加 → ツール呼び出しが止まったら終了」の while ループであり、これ以上複雑にしないことが既定である。

• モデル呼び出し層は「1回の推論のみ・ツールを実行しない・自己反復しない」。ループ制御・ツール実行はハーネス側の責務とし、この不変条件を契約テストで固定すること。SDK のコールバックにループ制御を紛れ込ませないこと。
• ツール実行の関門（Execution Gate）を一本化すること：解決 → 入力検証 → 認可 → 実行 → 結果正規化 が唯一の経路。バイパス経路を作らない。
• 幻覚ツール名・不正入力で run を落とさないこと。構造化エラーをモデルへ返し自己修正させる。エラーで自己修復させることは驚くほど機能する。ただし連続失敗（目安3回）で人間へエスカレーションし、エラースパイラルを防ぐこと。
• 停止条件を必ず持つこと：最大ステップ数、トークン/時間予算、明示的な final-output、doom loop 検出（同一ファイルへの微修正反復など）。
• 予算切れは raw エラーで終わらせず wrap-up turn で締めること：ツールなしの最後の1回で「達成・未完了・次の一手」を報告させる。wrap-up が失敗しても元エラーを上書きしないこと。
• プロンプトキャッシュ規律：静的コンテンツを prefix 先頭に、履歴は append-only、ツール定義は決定的順序。キャッシュヒット率は本番エージェントの最重要メトリクスであり、非決定的なシリアライズ1つで毎ターン全ミスになる。

---

3. コンテキスト工学

コンテキストには attention budget があり、長くなるほど劣化する（context rot）。劣化は崖ではなく勾配であり、エラーとしては現れず品質低下として静かに起きる。

• 情報を失わせないこと。 圧縮・要約・切り詰めで失われた情報は品質を静かに損ない、モデルは欠けていることを知らないまま判断する。生の検索結果・大きな表・文書であっても、不可逆な圧縮・省略・compaction は、まず圧縮せずに渡して品質を担保できることを確認し、コンテキスト量が課題として顕在化してから導入する（公理5。mastra-ai-architecture-rules §7 と同旨）。
• ただし、失わせないことと全量を載せることは別である。 その場に載せる範囲はユーザーの要求の目的から決め、データ源の形から決めない。範囲の中は切らず、範囲の外は「何が・どこに・どれだけあるか」（目次・件数・ID・パス）と取り方（続き読み・範囲指定の引数・ファイル）を示して到達可能にする。必要十分に見えるときも取り方は残し、何を追加で読むかはモデルに判断させる。事前注入・ツール応答・サブエージェントの返却のいずれにも同じ原則を適用する。
• 上限として置いてよいのは、受け手（モデル・ハーネス・クライアント）が実際に持つ限界だけである。 受け手ごとに確かめて決め、別の受け手の閾値や人間向け表示の文字数を写さない。限界を超えるときは切らずに全文をファイル等へ書き、受け手が自分のツールで部分的に読める形（行単位・冒頭の目次に行範囲）で参照を返す。
• 事前注入と Just-in-Time 取得のハイブリッドを既定とすること：毎回必要な静的方針は初回に前置し、本文・詳細はツールで実行時に取得させる。軽量識別子（パス・ID・リンク）を持たせ、必要時に読み込む。
• 環境は探索させず注入すること。エージェントが実行中にコンテキストで参照できないものは存在しないのと同じである。
• progressive disclosure：情報は「概要 → 本文 → 詳細参照」の階層で開示し、全量を事前投入しない。
• compaction 機構の導入自体は、コンテキスト逼迫が観測・実証されてからでよい（公理4）。導入する場合は非LLM圧縮を第一選択とするプログレッシブパイプラインにすること：古いツール結果のマスキング → 部分圧縮 → 構造化LLM要約。閾値駆動（目安70–90%）、ユーザー発話は省略禁止、暴走防止のサーキットブレーカーを持つ。
• 圧縮は必ず復元可能に設計すること：URL・ファイルパス・IDを残し、切り詰めた情報へ後から到達できるようにする。不可逆圧縮は「10ステップ後に必要になる情報」を失う。
• ファイルシステム（または外部ストア）を究極のメモリとすること。長時間タスクでは構造化メモ（計画・進捗・所見）を外部に書き出し、計画をコンテキスト末尾へ復唱（recitation）して目標ドリフトを防ぐ。
• 失敗はコンテキストに残すこと。エラー痕跡を見たモデルは同種アクションを避けるようになる。消毒された履歴は学習機会を奪う。
• 指示の層構造を持つ場合、グローバル層は per-run 指示でも無効化できないことを不変条件として固定すること。

必要十分な供給と取得経路の設計、コンテキスト失敗モード（poisoning / distraction / confusion / clash）と対策の詳細: references/context-engineering.md

---

4. ツール表面（ACI）設計

ツールはモデルに対するインターフェース（Agent-Computer Interface）であり、その質がモデルの実効能力を決める。ツール説明の精緻化だけで性能が大きく変わる。

• 外部APIを1:1でラップしないこと。エージェントのタスク単位に統合した少数のツールを設計する（例: list_contacts より search_contacts）。
• ツール数は絞ること。多すぎるツールは選択精度を下げる。減らして精度が上がった事例が繰り返し報告されている。
• 出力は呼び出しの目的に対して必要十分にすること：既定の応答には、そのツールが呼ばれる目的に要る事実を全て載せ、目的と無関係な全体情報を付けない。導出できる重複（他のフィールドから計算できる一覧、件数の2乗で増える相互参照）を返さない。意味のある識別子（名前・パス）を返し、無意味な UUID の羅列を避ける。
• 応答から外したものは、同じツールで取れるようにすること：範囲指定・絞り込み・詳細度・cursor の引数を、モデルが変えられる既定値として持たせる。省いた部分は空の値ではなく「省いた」と明示し、切った箇所には続きを返す呼び出しを名指しする。判断に使いうる内容の事前要約・間引きは、§3 に従い品質への影響を確認してから導入すること。
• エラーメッセージは修正指示として書くこと。エラーはモデルのコンテキストに入り、次の行動を決める。「何が悪いか」だけでなく「どう直すか」を返す。
• 実行途中でツールを動的に削除しないこと。定義の増減はキャッシュを壊し「消えたツールへの参照」を誘発する。制約はマスキング（そのターンで選ばせない）で行う。
• 大量のツールや大きな中間結果が必要な場合は、ツール群をコード API として提示し、コード実行で組み合わせさせるパターンを検討すること（モデルが見るのは明示的に返した値だけになり、トークンとプライバシーの両方を制御できる）。

ツール応答の組み立て・上限の決め方・限界を超えるときの受け渡しの詳細: references/context-engineering.md §5

---

5. ガードレールと認可

「エージェントが何をするかではなく、何ができるかを制御する」。

この節のうち、能力を人間と揃えること、段階の設定（allow / ask / deny）、未設定時の既定に関わる項は、サービスの利用者がエージェントに操作を代理させる場面を対象とする。開発者が Claude Code / Codex を開発作業や CI で使うときの権限の設定は agent-native-project-design を参照する（不安から能力を削らず、どこまで任せるかをユーザーが決めるという公理7の立場は、どちらの場面にも効く）。

• エージェントにできることを、代理する人間にできることと揃えること。上限は代理する人間自身の権限であり（下の Intersection）、人間がアクセスできる情報は、ユーザーが許可すれば全てアクセスできる。人間にできてエージェントにできない操作を作るなら、法令・契約・技術的制約などリスク以外の理由を設計メモに残す。リスクは提供しない理由にせず、次項の段階設定で扱う。
• どこまで任せるかはユーザーが決め、ハーネスが執行すること。ユーザーは操作ごと（または操作の種類ごと）に「完全に任せる（allow）／承認付きで任せる（ask）／禁止（deny）」を選ぶ。開発者は段階を決める側に立たない。組織で使う場合は、管理者が個人の選べる範囲を絞る設定を持ってよい（Claude Code の managed settings、Codex の requirements.toml と同じ構造）。sandbox などの封じ込めは残し、境界を広げるかどうかもユーザーが決める。
• 未設定時の既定はリスク格付けで決めること：状態を変えない操作は完全に任せる。不可逆な操作・外部への送信・金銭を伴う操作は承認付きにする。その間の取り消せる変更は、格付けに従っていずれかを既定にする。禁止は既定にしない。格付けと、その操作で起きうること（例: 非公開データの読み取り・信頼できない入力・外部への送信が揃うと流出経路になる）は、ユーザーが段階を選ぶときに示す。
• 環境層が第一防衛線：sandbox・filesystem 境界・network egress 制御を先に設計する。モデル層の防御（プロンプト・分類器）は補助である。モデルは prompt injection に高確率で従うことを前提とせよ。
• sandbox は filesystem と network の両方を隔離すること。片方だけでは exfiltration か脱出の経路が残る。ドメイン allowlist は信頼境界にならない（許可済みドメイン経由の流出事例がある）。
• 逐次承認はスケールしない。人間は権限プロンプトの大半を素通し承認する（approval fatigue）。境界を事前定義し、境界越えのみを承認に上げること。sandbox は承認疲れを減らすためにある。
• LLM に権限判断を委ねないこと。「プロンプトで秘匿を指示する」はアンチパターン。認可は決定的コード（行レベル認可・Repository 契約・Execution Gate）が第一防衛線であり、検索前に適用する（Auth Before Retrieval — 取得してからフィルタするのではない）。
• 有効権限は Intersection、絶対に Union にしないこと：agent baseline（ユーザーが設定した段階）∩ 呼び出し元 ∩ 会話参加者の実権限。エージェントは会話者を超える権限で副作用を起こさない。deny > ask > allow の合成で「Union を構造的に作れない」実装にする。baseline を開発者の判断で、代理する人間の権限より狭くしない。
• 認可情報の欠落・不正と、管理者の制限を確かめられないときは fail-closed で応じること：認可が未注入（誰の代理か分からない）なら deny-all、認可の設定不備は偽装せず明示エラー。管理者が個人の選べる範囲を絞る設定を読めないときは、承認を求めず、その呼び出しを実行しない（承認を求めると、制限されている本人の承認で管理者の制限を越えられてしまう）。「認可の仕組みが未設定なら通す」モードを作らない。ユーザーが段階を選んでいない操作は認可情報の欠落ではなく、未設定時の既定に従う。ユーザーの段階の設定を読めないときは、明示エラーにも既定にもせず、承認付き（ask）として扱う。
• 承認（HITL）フローの不変条件：hard-deny は承認でもバイパス不可 / 承認者へ権限昇格しない（実行者の権限で再解決する）/ 認可値を run に固定（pin）しない / 終端状態への重複承認は冪等 no-op。
• 自作のセキュリティ部品を信用しないこと。「最も弱い層は自分で作った層」。OS プリミティブ・実績ある機構を優先する。
• 不可逆または高リスクなアクションは、型付き schema と approval gate を持つ明示的なツールとして定義し、リスク格付け（read-only/write・可逆性・権限・金銭影響）から未設定時の既定の段階を決めること。ゲートはユーザーが変えられない固定にしない。ブロックは deny-and-continue（拒否理由を返し代替を探させる）とする。

能力の揃え方と段階設定・認可モデル・承認プロトコルの詳細: references/guardrails-authorization.md

---

6. 状態・耐久性・冪等性

• 耐久する正本（source of truth）は一つに決めること。会話ログと独立実行台帳の二重正本は整合維持コストを恒常的に生む。監査・分析は telemetry へ分離する。
• 実行状態（ステップ・リトライ・承認待ち）と業務状態を単一のイベント列に統合し、全状態をそこから導出可能にすること。エージェント=イベント列への stateless reducer と捉えると、checkpoint・resume・fork・デバッグが自明になる。
• state には reference / ID / summary のみを置くこと。大きな成果物はストレージに置き、参照だけ持つ。再計算可能なデータ・生のツール出力・チャット履歴のコピーを state に入れない。
• 副作用ツールには冪等性キーを供給すること（例: runId:toolCallId の決定論キー）。リトライ・再開・重複配信に対して「同一キー同一入力 → 同一結果、同一キー異入力 → 拒否」を契約として固定する。
• 失敗地点から再開できること。長時間エージェントの「ゼロから再実行」は設計欠陥である。checkpoint + backoff付きリトライ + 冪等性の3点セットで回復性を作る。
• 履歴の巻き戻し（rewind）を提供する場合は fork-first（非破壊）を既定とすること。

詳細: references/state-durability.md

---

7. 検証・評価・可観測性

検証ループがないエージェントは自走できない。 最頻の失敗モードは「自分の出力を読み返して良さそうと判断し、検証せず終了する」である。

• 実行可能なチェックを与えること：テスト・ビルド exit code・スキーマ検証・スクリーンショット比較。検証方法は判定対象で使い分ける。テスト結果・schema・DB の行のような閉じた集合はルールベースで、画面の見た目は視覚比較で、自然言語の言い回し・意図・応答の妥当性のように列挙で閉じない対象は LLM judge で判定する。自然言語の言い回し・意図・応答の妥当性を、正規表現・語句リスト・例外分岐・固定文言で判定しない。
• 証拠主義：「ツールを実行した」≠「結果を観察した」。成功の主張ではなく証拠（コマンドと出力・トレース）を要求すること。検証できないものはシップしない。
• 評価（eval）は実際の失敗から採った少数タスク（目安20件）で始めること。数百件を待たない。トレースの読解・分類（error analysis）が「どの eval を作るか」を決める最重要工程である。
• 経路ではなく成果を採点すること。最終状態（DB状態・テスト通過）を検証し、ツール呼び出し順序を厳密規定しない。エージェントは設計者が想定しない正当解を見つける。
• 信頼性は pass^k で測ること。pass@1 が高くても反復信頼性は指数的に減衰する。業務組み込みには一貫性指標が必須。
• capability eval（低い合格率から登る）と regression eval（常時ほぼ100%を維持）を分離運用すること。
• eval スコアを transcript を読まずに信じないこと。スコア低下の原因が eval 側のバグであることは珍しくない。transcript サンプリング読解を制度化する。
• 可観測性は「観測欠落ゼロ + テレメトリで run を殺さない」：全失敗経路でイベントを emit し（落ちた run こそ trace が要る）、テレメトリ自体の失敗は縮退させて run を守る。秘匿情報は sanitize してから記録する。
• 決定論検証と実モデル検証の2層を持つこと：fake/決定論モデルで契約・不変条件を高速に固定し、実モデルで指示追従など確率的挙動を検証する。契約テストの silent skip（偽緑）を検出する仕組みまで含めて設計する。

詳細: references/evals-observability.md

---

8. マルチエージェント判断

マルチエージェントは最終手段である。 既定は single-threaded なエージェント + コンテキスト管理。

• 書き込みを伴う並列マルチエージェントは原則禁止。行動には暗黙の決定が埋め込まれ、完全なトレースを共有しない並列作業は矛盾した成果物を生む。
• サブエージェントの正しい用途は「役割分担」ではなく、read 系探索のコンテキスト隔離と並列化である。子は大量トークンを自分の窓に閉じ込め、親へは蒸留した要約のみ返す圧縮装置として使う。
• マルチエージェントの性能向上の実体はトークン消費の並列化であり、コストはチャット比で十数倍に達すると報告されている。並列分解可能な高価値タスクに限定すること。
• 委譲時は objective・出力形式・ツール指針・境界・工数上限を明示すること。「調べて」だけの委譲は重複作業と過剰探索を生む。タスク複雑度に応じた工数ルールを明文化する。
• サブエージェントの出力もツール結果と同様に tainted として扱うこと。無条件に高信頼で扱うことは新しい injection ベクタになる。

委譲プロトコル・出力契約・効果とコストの報告値: references/context-engineering.md

---

9. アンチパターン → 是正

アンチパターン	なぜ失敗するか	是正
自己確認で検証を終える	「読み返して良さそう」は検証ではない	実行可能チェック（テスト・ビルド・比較）を与える
自然言語の応答を正規表現・語句リストで判定する	言い換えが無限にあるため例外が収束せず、正当な応答を落とす	LLM の判定に移すか、判定自体をやめる。同じ判定に例外対応を2回入れたら、3回目は足さずにどちらかを選ぶ
プロンプトで権限・秘匿を制御する	モデルは injection に従う	決定的な認可ゲート・sandbox に移す
認可を Union で合成する	権限昇格の穴が生まれる	Intersection + deny>ask>allow 合成
認可の設定漏れを通す既定	設定漏れが即事故になる	fail-closed（deny-all / 明示エラー）
人間にできる操作を開発者の判断でエージェントから外す、承認や禁止を固定する	エージェントの能力が人間を下回り、ユーザーがリスクを取る選択肢を失う	能力を人間と揃え、allow / ask / deny をユーザーが選ぶ。リスク格付けは既定と開示に使う
ツール全出力を state に保存する	state 肥大・snapshot 汚染	reference / summary のみ保持
目的と無関係な全体情報をツール応答に既定で付ける	コンテキストを浪費し、要求に要る事実が埋もれる	呼び出しの目的で範囲を決め、範囲の外は所在と取り方だけを示す
文字数・件数の定数で黙って切り詰める	モデルは欠けていることを知らないまま判断し、品質が静かに落ちる	範囲の中は切らない。受け手の実際の限界を超えるときはファイル等で全文を渡し、省いた箇所には取り方を示す
常時最大推論・無制限ループ	タイムアウト・コスト暴走で品質が下がる	停止条件・予算・doom loop 検出を一級で持つ
予算切れを raw エラーで返す	途中成果が失われる	wrap-up turn で達成・未完了・次の一手を報告させる
ツールを乱立させる	選択精度が下がる	タスク単位に統合し少数に絞る
実行途中の動的ツール削除	キャッシュ全滅・幻覚参照	マスキングで制約する
非決定的なプロンプト組み立て	キャッシュ全ミスでコスト増	静的 prefix・append-only・決定的順序
書き込み並列マルチエージェント	暗黙の決定が衝突する	single-thread + サブエージェントは read 系隔離のみ
モデル更新後もハーネスを凍結する	旧世代の補正が新モデルの上限になる	世代ごとに剪定棚卸し（「強いモデルに替えて性能が上がるか」で検査）
観測した失敗1件ごとに、プロンプトへルールを、検証へその失敗だけを検出する判定を足す	プロンプトが肥大してルール同士が干渉し、検証は言い換えのたびに例外が増える	プロンプトには複数の失敗に共通する原則を1つ書く。検証では失敗を eval タスクとして加え、判定は §7 の判定対象の使い分けに従う
ブラックボックス抽象への依存	品質天井・デバッグ不能	own your prompts / context / control flow
ハーネス条件を揃えないモデル比較	ハーネス差がモデル差を上回る	ハーネス固定で比較・条件を開示する
eval スコアだけ見て判断する	eval 側のバグ・想定外の正当解を見逃す	transcript 読解を制度化する
自作セキュリティ部品	最も弱い層になる	OS プリミティブ・実績ある機構を使う

---

10. 設計メモと最後の自己確認

非自明なハーネス実装・変更の前に、以下の見出しを持つ簡潔な設計メモを作成すること：

1. 調達判断: どの抽象度を選んだか、既存ランタイムの再利用をなぜ選ばなかったか
2. ループと停止条件: 最大ステップ・予算・doom loop 検出・wrap-up
3. 情報の供給: 事前注入 / JIT の切り分け、各ツール応答に載せる範囲と範囲外の取り方、受け手ごとの実際の限界、compaction 方針
4. ツール表面: ツール一覧と統合の根拠、エラー設計
5. 認可モデル: 人間と揃えた能力の一覧、ユーザーが段階を選ぶ単位と未設定時の既定、境界・Intersection 構成・fail-closed の適用範囲・承認ゲートの位置
6. 状態と耐久性: 正本の所在、state に置くもの/置かないもの、冪等性キー
7. 検証と評価: 実行可能チェック、eval タスクの出所、transcript 読解の運用
8. モデル能力向上時に削除できるもの: このハーネスのどの部分が「現行モデルの弱点補正」か

実装前に自問すること：

• この保証は本当にハーネスでなければ与えられないか。指示・ツール説明・schema の改善で済まないか
• このループ・ラッパー・ステップは、モデルの判断を模倣していないか
• 検証手段はあるか。ないならシップできる状態か
• モデルは、省かれた情報があることと、その取り方を知っているか。定数で黙って切っている箇所はないか
• 人間にできてエージェントにできない操作はないか。あるなら、それはユーザーが選んだ制限か、リスク以外の理由があるか
• 認可情報が欠けたときは fail-closed か。Union になっている箇所はないか
• 次のモデル世代で、この機構は削除候補になるか

迷ったら、より少ない機構で同じ保証を与える設計を選ぶこと。