モデルを入れ替えても機能するAgent Harness設計

概要

Coding Agentを選ぶときは、GPT、Claude、QwenなどのModelへ注目しがちです。しかし、実際の開発結果はModelだけでは決まりません。Repositoryの読み方、Toolの呼び方、権限、Context、Skill、Subagent、結果の確認方法をまとめて管理する実行環境も影響します。この記事では、この層をAgent Harnessと呼びます。

Harnessごとに専用の知識を作ると、製品を変えるたびにルールと手順を移植しなければなりません。反対に、長く残す知識をRepositoryへ置き、Harness固有の設定を薄く保てば、ModelとHarnessを別々に評価できます。

この記事は、特定製品の優劣を決めるものではありません。Agentic Codingの環境を段階的に育てながら、将来ローカルLLMも試せる構成を整理します。

結論

• Kev、SemIf、Laya、Tev1で判断のローカル実行を比較できますが、出力方式、校正、ライセンス、APIの対応範囲は別々に確認します。
• Modelは推論を担当し、HarnessはContext、Tool、権限、実行Loop、人間への確認を担当します。
• 共有したい知識と手順はRepositoryを正本にし、製品固有のMemoryや設定だけに閉じ込めません。
• AGENTS.mdは長い説明書ではなく、必要な文書や検証へ案内する軽量な入口にします。
• Docs、Skill、Script、CI、Memoryは役割が異なります。同じ内容をすべてへ複製しません。
• Harness間で共有できるのは主に知識の意味です。Skillの探索場所、Agent定義、認証、権限は薄いAdapterが必要になる場合があります。
• Model Routingは、先に役割を固定するのではなく、同じ課題で品質、時間、再試行、人間の修正量を測ってから広げます。
• 知識の自動蓄積は候補の生成までとし、Repositoryの正本へ入れる前に人間の確認と決定的な検証を挟みます。
• Skillや資料の選別は専用モデルへ分担できますが、必須規則、権限、正本の更新はHarnessとコード側で管理します。

Agent Harnessとは何か

LLMは、入力されたContextから次の文章やTool Callを提案します。それを開発作業として成立させるには、提案を実行し、結果を再びModelへ返すLoopが必要です。

Harnessが扱う範囲は製品ごとに異なりますが、主に次の要素を含みます。

• Repositoryや作業ディレクトリの読み書き
• Terminal、Browser、外部ServiceなどのTool
• Modelへ渡すInstructionとContext
• Tool実行、ファイル変更、Network接続の権限
• Taskの途中状態とContext圧縮
• Skillや再利用可能なWorkflow
• Subagentへの委譲と結果の統合
• Diff、Log、Test結果を人間へ提示するReview Surface

OpenAIはCodexのAgent Loopを、ModelとToolを結び付けて作業を進めるHarnessとして説明しています。また、OpenAI社内の運用では、Application、Log、MetricをAgentが直接確認できる形へ整えることと、Repository上の構造化されたKnowledgeを正本にすることをHarness Engineeringの要素として挙げています。

したがって「同じModelを使った」という情報だけでは、Agentの能力を比較できません。利用できるTool、Contextの構成、権限、再試行、終了条件まで揃えて初めて、Model側の差を比較しやすくなります。

4つの層を分ける

Agentic Coding環境は、次の4層に分けると変更の影響を整理しやすくなります。

この分離では、Harnessを変えてもRepository Contractと検証方法を残せます。Modelだけを変える場合も、同じHarnessと課題を使えば比較条件を近づけられます。

Model / Provider
       ↓
Agent Harness
       ↓
Repository Contract
       ↓
Test / CI / Human Review

下の層が上の層を完全に信用する構造にはしません。Modelが正しい形式のTool Callを生成しても、その操作が現在のTaskで許可されるとは限りません。Harnessの権限と、ScriptやCIの合否判定を別に持たせます。

Repositoryを正本にする

Repositoryの中心には、Modelへ毎回すべてを渡す巨大なInstructionではなく、必要な情報へ辿り着ける地図を置きます。

Repository
├─ AGENTS.md          # 最初に読む短い規則と参照先
├─ docs/              # 設計、判断、運用の正本
├─ .agents/skills/    # 必要時に読む再利用手順
├─ scripts/           # 繰り返し処理を決定的に実行
└─ tests / CI         # 完了条件を機械的に確認

OpenAIのHarness Engineering事例でも、大きなAGENTS.mdへ情報を集約すると、Taskに使えるContextを圧迫し、重要度が曖昧になり、内容が古くなりやすいと説明されています。同事例では、AGENTS.mdを目次として使い、詳細なKnowledgeをdocs/へ分けています。

この構成で重要なのは、Repositoryへ何でも保存することではありません。情報の性質に応じて置き場所を変えます。

Memoryは便利ですが、AgentやProfileに依存し、誤った情報や古い前提が残る可能性があります。複数人と複数Harnessで共有する判断はDocsやIssueへ移し、Memoryには正本への参照や小さな個人設定を残します。

共有できるものとAdapterが必要なもの

Repository中心にしても、すべてのHarnessが同じファイルを同じ方法で読めるわけではありません。

OpenCodeは、Project内の.agents/skills/<name>/SKILL.mdを探索し、Skill本文を必要時に読み込みます。AgentごとにModelとTool権限を設定でき、Local Modelを含む複数Providerを扱います。

Qwen CodeもProject SkillとSubagentを扱い、OpenAI互換APIを通じてOllama、vLLM、LM StudioなどのLocal Serverへ接続できます。一方、現在の公式配置はSkillが.qwen/skills/、Subagentが.qwen/agents/です。

Hermes AgentはAGENTS.mdをProject Contextとして読み、Skillを必要時に読み込みます。標準のSkill保存先はProfile側ですが、外部Directoryの読込みや、作成先をGit管理されたDirectoryへ変える設定もあります。MemoryとSkillの書込みを人間の承認待ちにする機能もありますが、いずれも標準では自由に書き込む設定です。

目標は「Adapterをゼロにすること」ではありません。共有する意味を一つにし、製品固有の接続部分を小さく保つことです。

製品ごとの重点を分けて見る

2026年9月3日時点では、各Harnessの用途を次のように整理できます。これは総合順位ではなく、公式に確認できる機能と導入目的の対応です。

OpenCodeは75以上のProviderとLocal Modelへの対応を案内しており、Agentごとにprovider/modelを選べます。既にAGENTS.mdや.agents/skills/をRepository管理している場合、第二のCoding Harnessとして比較を始めやすい候補です。

Qwen Codeは名前にQwenを含みますが、公式資料ではOpenAI、Anthropic、GeminiのProtocolとOpenAI互換のLocal Serverを設定できます。ただし、既存のSkillを移す場合は.qwen/skills/との同期方針を先に決めます。

Hermes Agentは、短いCoding Taskだけでなく、Memory、Skillの更新、Profile、長期稼働を含むAgent Platform寄りの機能を持ちます。自動でKnowledgeを書き換える前に、memory.write_approvalとskills.write_approvalを有効にし、作成候補をReviewする運用が安全です。また、公式資料はPermissionの拒否Ruleを誤操作へのGuardrailと位置付け、敵対的なProcessに対するSandboxではないと説明しています。必要に応じて隔離された実行環境を併用します。

Model Routingは実測から決める

HarnessからModelを交換できても、最初から「調査はLocal」「実装はCloud」のように固定すると、Taskの難しさと言語品質の差を見落とします。

まず同じRepository、同じTask契約、同じ完了条件で結果を記録します。

• 完了条件を満たした割合
• 人間が修正したDiffの量と重要度
• Rule、許可範囲、対象Fileを守れたか
• 再試行回数と中断理由
• 経過時間、Token量、推論料金
• Local実行時のMemory、GPU占有、他の作業への影響
• Reviewで見つかった欠陥

Perplexityは自社のLocal Knowledge Work Benchで、同じQwen 3.8 27BをPortable Computer、Pi、Hermesへ載せた結果に差が出たと報告しています。これは開発元が作成した非公開Benchmarkであり、一般的な優劣を証明するものではありませんが、Modelを固定してもHarnessが結果へ影響し得る事例です。

Model Routingは、次のように段階的に広げます。

1. 現在のHarnessとModelを基準に、境界が明確なTaskを数件記録する。
2. 第二のHarnessで同じTask種別を実行し、出力だけでなく権限とReview負荷を比べる。
3. 低Riskな文書整形、検索、定型検証からLocal Modelを試す。
4. 成功率が安定した役割だけ、標準のRouting候補へ昇格する。
5. ModelまたはHarnessのVersionが変わったら、同じ評価Taskで再確認する。

限定的な判断を専用モデルへ分担する

Skillや参照資料の候補が決まっている場合、その選別だけを別のModelへ分担する構成も評価できます。TypeSafeのJevは、与えられたstateに対する選択・評価を返すモデルです。公式の設計方針は、狭い判断をモデルへ渡し、制御フロー、確定的な規則、実際の操作はコードへ残すものです。

これらの型付きの質問は同じstateに対して独立に評価されます。前の回答を次の質問へ渡す逐次推論ではありません。Jevは文章やコードを生成する担当ではなく、状況の取得、資料の検索、説明や実装は周辺コードと生成LLMが担当します。

具体例として、TypeSafeのSkill提案実験は、全候補を順位付けし、上位3件を詳しく再評価する2回のAPI呼び出しで、最大1件のSkillをAgentへ提案しています。元のSkill一覧とAgent自身の判断は残した構成です。

これはJev 1.12、Claude Haiku 4.5、Hermes由来の182種類のSkillと488依頼による提供元実験です。依頼には生成されたものが含まれ、測定対象はAgentの最初の応答でのSkill読み込みです。Jev 1.13、日本語、Copilotで同じ改善を示すものでも、作業全体の品質やトークン削減を証明するものでもありません。公式TypeSafe SkillもAPIを使った設計・実装を支援する手順であり、インストールだけで既存AgentのSkill選択を置き換える機能とは区別します。

評価時は、候補の選択、Agentによる実際の読み込み、指示への追従、最終成果物を分けて測ります。単一候補の提案だけでなく、該当なし、情報不足、複数Skillが必要な依頼を含め、既存の選択方法と総時間・費用・見落とし率を比較します。必須の規則や権限確認は、候補として選ばれた場合だけ読む設計にしません。

confidenceはChoiceやScoreの確率分布から算出される指標で、正解率として扱いません。閾値は自分のデータで調整し、モデルと質問文を記録します。モデル仕様で確認した提供経路はクラウドAPIです。2026年9月19日時点のモデルIDはjev-1.13.0で、英語以外の精度には差があるとされています。ローカルLLM構成へ追加する場合も、送信するstateは外部へ出ます。顧客データの学習不使用と、保存・保持なしは別の条件です。

複数質問の公式仕様では、同じstateで独立に判定できる質問はまとめられます。一方、先の結果から取得資料や次の候補を決める場合は別リクエストが必要です。上記の「全候補→上位3件」の再評価は段階間に依存があり、そのまま1回へ統合できるとは扱いません。

ローカル判断モデルは出力方式と実行環境を分けて比較する

2026年9月29日確認。Jevで説明した判断の分担は、ローカルでも検証候補が増えています。以下はTypeSafe公式Jevのローカル版ではなく、独立した実装です。

KevのMLX対応は確認時点で実装済みです。通常のチャット用GGUFを読み込む構成とは区別します。APIの形式が似ていても、質問数、候補数、Context制限、精度、confidenceの意味までJevと同一とは限りません。切替時は自分の入力とエラー処理で契約を検証します。

SemIfの作者測定では、同じQwen3.5-4B、同じstateと21個の二値質問をRTX 3090で処理したとき、直接logitを読む方式は1.023秒、JSON配列の生成は5.332秒でした（各3回の中央値）。ただし回答の一致は18/21件で、意味的に等価な処理を高速化した証明ではありません。速度と判断品質を別々に測ります。

Laya multilingualのモデルカードは、未校正で過信傾向があることと、typed-decisionsのzero-shot評価が0.342（ランダム0.318、最多クラス0.461）だったことを開示しています。多言語対応だけで日本語のSkill選択や資料評価が十分とは判断せず、用途に合わせた評価・追加学習・校正を検討します。Tev1も多言語、Prompt Injection、校正、分布外入力の包括的評価は未実施で、確認時点では重みのライセンスを確定中としています。ベースモデルのライセンスを派生Weightの配布条件として代用しません。

mlx-serve v26.9.6はLaya Checkpointを扱うPOST /v1/decisionsを追加し、同時要求をまとめる処理を案内しています。このAPIとJevの/v1/systemoneを同じものとは扱いません。サーバーへ接続できることと、Skill選択やゲーム判断に使える品質であることも別です。ゲームでの小規模実測と合わせ、待ち時間を含む応答、誤判定、既存処理へのFallbackを比較します。

Qwen3-VL-4Bを用いた個人の実装例では、1トークンの出力と選択肢のlogprobから画像への判断を返しています。これはJev自体の画像対応ではなく、複数質問を複数回のモデル呼び出しで処理する別実装です。初回処理とキャッシュ利用時を分け、モデル、量子化、Runtime、入力の再利用条件を記録します。全候補の確率を取得できているかも確認し、top_logprobsから漏れた候補を確率ゼロとみなしません。画像からの資料分類やSkill提案は未検証の応用案です。

代替モデルは、形式の妥当性（パース、候補範囲、確率の合計）、人手の正解に対する判断品質、確率の校正、再試行込みの時間・費用を分けて評価します。Nova MicroとJevの個人比較も出力検証とモデル間の一致率を区別しており、一致率は正解率ではありません。生成された確率値、トークン確率、専用判断モデルの確率を同じ性質として交換しません。Nova Microはクラウド候補であり、ローカル代替とは別枠です。

実装経験をKnowledgeへ戻す

AgentがTask中に再利用できそうな知識を見つけても、その場で正本を書き換える必要はありません。次のLoopへ分けます。

実装・調査
   ↓
Knowledge候補を記録
   ↓
事実、判断、手順、一時情報へ分類
   ↓
Docs / Skill / Scriptの候補を作る
   ↓
Test・ValidationとHuman Review
   ↓
Repositoryの正本へ反映

同じ説明を繰り返すならDocs、同じ複数Stepを繰り返すならSkill、同じ合否判定を繰り返すならScriptやCIが候補です。一度限りの出来事や未検証の推測は、無理にKnowledgeへ昇格させません。

この境界を設けると、Agentによる発見速度を活かしながら、誤った一般化、重複、古いKnowledgeの蓄積を抑えられます。

蓄積した知識を選んで再利用する

保存したノートを再利用するときは、検索、意味の評価、本文の取得、説明の生成を分けます。TypeSafeの文書選別の公式例では、検索済みの文書について関連性、回答に使える根拠、質問の前提との矛盾などを評価し、コードが回答用の資料を振り分けています。矛盾する情報も別枠で生成LLMへ渡す構成です。

Repositoryのノートへ応用するなら、次のように設計できます。これは構成案であり、funesなどの会話履歴検索とJevをつなぐ完成済みの公式連携や、本記事で実測したシステムではありません。

現在の問題と作業状態
   ↓
ノートの候補検索
   ↓
Jevで関連性・根拠・矛盾を個別に評価
   ↓
コードで資料を選び、本文・出典・状態を取得
   ↓
生成LLMが説明し、現在の実装への適用を調査

ノートにはID、対象機能・リビジョン、問題、原因、採用した対応、失敗した案、検証結果、採用済み・廃止・後継ありなどの状態、IssueやPRへの出典を持たせます。既存の欄を取り出す処理はコードで実行でき、複数資料を読み合わせた説明は生成LLMへ渡せます。Jevによる選別だけで、履歴が永続記憶へ保存されたり、正本が更新されたりする構成にはしません。

過去に成功した対応は、現在の正解とは限りません。現行仕様と対象リビジョンを併記し、失敗例や矛盾を単に関連度の低い資料として捨てないようにします。明示された廃止状態や日付比較はコードで処理します。検索で候補が見つからない場合は、会話履歴の検索や元のコードの確認へ戻れる経路を用意します。

Jev 1.13の既知の制約には、数値・日時、多段階の判断、無関係な情報の多いstate、入力内の誘導的な文章への弱さがあります。文書選別は、資料の正しさやPrompt Injectionへの安全性を保証する検証ではありません。日本語の実データで重要資料の見落としや矛盾の保持を測り、既存検索・再順位付けに対する追加効果と総費用を確認してから採用範囲を広げます。

判定位置と誤遮断を評価する

検索前の判定は「この検索先が扱う依頼か」、検索後・生成前の判定は「取得資料で回答を支えられるか」を扱います。前者には対象範囲と必要な会話履歴を渡し、不明なら検索継続や確認へ進めます。後者で根拠が不足したら検索拡張や原典・コード確認へ戻します。今回取得した資料に根拠がないことは、Repository全体に答えが存在しないことを意味しません。矛盾する資料は調査・説明へ回し、採用する根拠がゼロという理由だけで終了しません。

Jev 1.13を使った個人のRAG検証では、架空の400チャンク・120問による回答可否判定の正解率は99.2%でしたが、回答可能な質問の誤遮断も1.7%ありました。CompanyのSkill選択や日本語の実資料で同じ精度を保証する結果ではありません。回答可能な依頼の見落としを、処理削減の成果に数えない評価が必要です。

後続処理の単価を一定と仮定すれば、費用削減の簡易条件は「判定費用 < 正当に省略できた割合 × 後続処理費用」です。実際には検索拡張・再試行・検証の追加費用も含めて比較します。処理を継続する依頼には判定時間が加わるため、回答した依頼と正当に省略した依頼を分けて待ち時間を記録します。

最初に導入するなら何を試すか

既存の開発環境を置き換えず、第二のHarnessを比較対象として追加します。既にRepositoryへAGENTS.mdとSkillを置いている場合は、OpenCodeを最初の候補にすると、共有資産とProvider切替を同時に確認できます。

最初の検証範囲は、次の程度に留めます。

• 専用BranchまたはWorktreeを使い、同じFileを別Harnessから同時に編集しない。
• 最初は読み取り、調査、文書の小変更など、戻しやすいTaskを使う。
• Gitへの書込み、Network、認証情報の扱いを明示的に制限する。
• 既存Harnessの結果を基準にし、完了率と人間の修正量を比較する。
• Harnessの比較とLocal Modelの比較を同時に行わず、最初は片方を固定する。

長期Memoryや自動的なSkill候補の生成が必要になった段階で、Hermes Agentを別の比較対象にします。Local Qwenを優先して試す場合は、OpenCodeまたはQwen CodeからOpenAI互換のLocal Serverへ接続できます。採用判断は名前ではなく、同じ評価Taskの結果で行います。

確認項目

Agent Harnessを追加する前に、次を確認します。

• Repositoryの正本と、Harness固有設定を区別できている。
• Secret、Token、個人用MemoryをGit管理対象から除外している。
• Agentが読める範囲と、書ける範囲を別々に定義している。
• 自動生成されたSkillとMemoryを、人間が確認するまで有効にしない。
• Test、Lint、Buildなど、決定的に判定できる処理をPromptだけへ任せていない。
• 並列Agentが同じFileを同時に所有しない仕組みがある。
• Harness、Model、Version、推論量、結果を比較できる記録がある。
• 失敗時に変更を破棄し、認証情報や外部状態を復旧できる。

注意点

• Harness、Skill形式、設定項目は更新されます。導入時は公式資料と対象Versionを再確認します。
• SKILL.mdの形式が似ていても、探索場所、Frontmatter、Tool、権限の意味まで同一とは限りません。
• Local実行は、無条件にPrivate、安価、高速という意味ではありません。外部Tool、Telemetry、Update確認、Hardware費用を含めて評価します。
• Memoryと自動学習は誤りも再利用します。承認、出典、更新条件、削除方法を先に用意します。
• Permissionの確認Dialogや拒否Ruleだけを、OS Levelの隔離と同じ安全境界として扱いません。
• Multi-Agentは並列化できるTaskでのみ有効です。指示、結果確認、競合解決の負担も測ります。
• VendorのBenchmarkは、そのModel、Harness、Hardware、Task Setでの開発元評価です。自分のRepositoryで同じ結果が出るとは限りません。

関連資料

• OpenAI: Harness engineering
• OpenAI: Unrolling the Codex agent loop
• OpenCode: Agents
• OpenCode: Agent Skills
• OpenCode: Providers
• Qwen Code: Model Providers
• Qwen Code: Skills
• Qwen Code: Subagents
• Hermes Agent: Context Files
• Hermes Agent: Skills System
• Hermes Agent: Persistent Memory
• Hermes Agent: Security
• Perplexity: A Local-First Agent for Private Knowledge Work
• 2026年時点の主要なローカルLLM
• GitHub Projects、Issue、PRで複数Agentの作業を調整する