Claude Code を使い込んでいくと、「ハーネス」という語がプロンプト術の延長のように聞こえることがあります。実際には、モデルそのもの、製品側のエージェントループ、利用者が足す CLAUDE.md や hooks までを含む実行まわりの仕組み全体を指すことが多いです。
📑目次
この記事で先に押さえること
本記事では、コミュニティで共有されている「モデル／内部ハーネス／外部ハーネス」の3層マップを入口に、Anthropic Engineering が示す長時間エージェントの失敗モードと対策を突き合わせます。目的は、設定を盛り続けることではなく、いま触っている層を名指しし、長時間タスクで足りない最小の検証とハンドオフだけを足す実務判断です。
一次根拠は Effective harnesses for long-running agents と Harness design for long-running apps です。
一次情報から読む
補助資料として Scaling Managed Agents と、デモ用リポジトリ cwc-long-running-agents も参照します。
実務で確認すること
用語マップとしては Speaker Deck のコミュニティ解説 も参照しますが、失敗モードや検証設計の断定は公式側に寄せます。
モデル・内部ハーネス・外部ハーネスの3層
結論から言うと、ハーネスは「上手いプロンプトの別名」ではありません。Claude Code 周辺の議論では、ツール提供からコンテキスト管理まで、モデルを安定して動かす仕組み全体を指します。コミュニティ解説では、これを次の3層に分けます。
3層を分けて考える
- モデル — Opus / Sonnet など推論エンジンそのもの
- 内部ハーネス — Claude Code のエージェントループ、ツール、サンドボックス、コンテキスト管理など製品側の実行機構
- 外部ハーネス — CLAUDE.md、skills、hooks、slash commands、MCP、subagents など利用者が設計できる層
同じモデルでも Cursor や Devin、Claude Code で挙動が違うと感じるのは、多くがこの内部ハーネス差です。Managed Agents の記事でも、Claude Code は excellent harness の例として位置づけられています。
| 層 | 例 | 誰が主に変えるか | 変更の速さ | 典型リスク |
|---|---|---|---|---|
| モデル | Opus / Sonnet など | プロバイダ選択 | リリース依存 | 能力差を設定で誤認する |
| 内部ハーネス | ループ・ツール・sandbox・compaction | 製品アップデート | 速い | 自作の外部機能が公式に吸収され陳腐化する |
| 外部ハーネス | CLAUDE.md・hooks・MCP・subagents | 利用者・チーム | 即時 | 厚くしすぎて切り分け不能になる |
表から判断する
出典：Speaker Deck（コミュニティ解説）、Scaling Managed Agents（2026年時点の記事内容）
読者アクションは単純です。いま触っている設定や不具合を、一文で「モデル／内部／外部のどれか」に名指ししてください。ここが曖昧なままだと、モデル更新後に不要になった hooks を増やす、あるいは内部ループの制限を外部設定で無理に覆おうとする、といった誤診断が起きやすくなります。
実務で確認すること
外部ハーネスの具体例としては、Claude Hooks の活用 や Skills の設計 が「どの層を触るか」を整理する材料になります。
公式が示す長時間エージェントの失敗モード
長時間・複数セッションの作業では、compaction（要約によるコンテキスト圧縮）だけでは足りないことがあります。Effective harnesses の記事は、典型的な失敗を次の2つに整理しています。
- 一発でやりすぎる — コンテキスト途中で止まり、次セッションが半完成の状態を推測する
- 途中で完了と宣言する — まだ途中なのにプロジェクト完了としてしまう
対策の骨格は、人間のシフト交代に近い二段構成です。
- Initializer agent — 初回セッションで環境を整える（
init.sh、進捗ログ、初期 git、失敗扱いの feature list など） - Coding agent — 以降は1機能ずつ増分し、クリーンな終了状態と構造化された更新を残す
ここでいう「クリーン」は、main にマージ可能な水準です。大きなバグがなく、ドキュメントが整い、次の開発者（または次セッションのエージェント）がすぐ新機能に入れる状態を指します。進捗ログと git 履歴があることで、新しいコンテキストが短時間で状態を把握できます。
読者アクション: 自分の長時間ランに「進捗ログ」「git」「feature list（または同等の未完了一覧）」があるかを Yes / No で点検してください。3つとも無い状態でセッションを跨ぐほど、半完成の推測と早期完了宣言が起きやすくなります。
generatorとevaluatorを分ける理由
作る側に自己採点させると、平凡な成果でも自信満々になりやすい、というのが公式側の観察です。Harness design for long-running apps では、generator（生成）と evaluator（評価）を分離し、評価者を懐疑的にチューニングする方が扱いやすいとされています。
あわせて重要なのが context anxiety です。コンテキスト上限が近いと感じると、モデルが早期に作業を切り上げることがあります。ここで混同しやすいのが次の2レバーです。
- compaction — 要約を同じ会話に残す
- context reset — 完全にクリアし、構造化ハンドオフで次エージェントへ渡す
Sonnet 4.5 系では reset が必要だった一方、Opus 4.5 では不要になった例が公式に再言及されています。つまり「今効いている対策」はモデル世代に依存します。
フロントエンド実験では、Design quality / Originality / Craft / Functionality のような採点基準を generator と evaluator で共有し、Playwright などで実ページを検証する流れが示されています。長時間アプリ開発では、planner + generator + evaluator への拡張も議論されています。
実務で確認すること
読者アクション: 「誰が done を判定するか」が、ビルド主体と同一か分離かを確認してください。同一のままだと、自己申告の甘い完了が残りやすくなります。
ハーネスはモデル進化で陳腐化する
ハーネスは「モデルがまだできないこと」への仮定の集合です。モデルが改善すると、かつての必須ゲートが死重になります。Managed Agents の設計は、この前提を前提にして session（永続ログ）／ harness（ループ）／ sandbox（実行） を分離し、それぞれ置換可能にします。
実務上の含意は次のとおりです。
- 脳と手の分離 — 資格情報を sandbox から到達不可にするなど、実行境界と意思決定を分ける
- pet ではなく cattle — 障害時に1コンテナを看護し続ける設計より、再プロビジョン可能な分離を好む
- 棚卸し — モデルや Claude Code の更新後に、効いていない hooks・冗長な reset・過剰な MCP を削る候補にする
「足すほど強い」ではなく、「観測された不足にだけ足し、前提が消えたら削る」が公式の方向性と整合します。
読者アクション: 直近のモデル更新後に、削れる外部設定を1つ候補に挙げてください。候補が無い場合は、外部ハーネスがまだ薄い可能性が高いです。
小さく試す品質ループの材料
厚い自作の前に、製品機能と公式デモ材料で十分かを試すのが安全です。Anthropic 公開の cwc-long-running-agents は turnkey 製品ではなく、Code with Claude 向けの例示材料です。それでも品質ループの3プリミティブは読みやすいです。
品質ループの3つの部品
- Default-FAIL contract — 各基準は最初 false。根拠を読むまで pass にできない
- Fresh-context evaluator — Write/Edit を持たない別エージェントが採点
- Agent-maintained handoff — 進捗ノートと git で次セッションへ引き継ぐ
まず試す順番
製品側では、Claude Code の /goal が generator / evaluator ループを内蔵する方向の入口になります。カスタム hooks は、プロジェクト固有の判定や監査が必要なときに限る、という切り分けが現実的です。hooks の詳細は Hooks 活用ガイド を参照してください。
注意: デモリポジトリはメンテ前提ではない、と README 側で位置づけられています。コピーしてそのまま運用するより、「どのプリミティブが不足しているか」を測る物差しとして使うのが適切です。
実務で確認すること
読者アクション: まず /goal または最小の handoff（進捗 + git）を試し、足りない基準だけ hooks 化してください。
今日から足す最小ハーネスチェックリスト
ここまでの論点を、今日中に1項目だけ実施できる形に落とします。
最小チェック項目
- 触っている層をモデル／内部／外部のいずれかで名指しする
- 長時間タスクなら progress ログ・git・feature list・init 相当の有無を確認する
- done 判定がビルド主体と分離されているか確認する（
/goalまたは別 evaluator） - 外部ハーネスは「観測された不足」だけ足す（小さく・ポータブルに）
- モデル／製品更新後に棚卸しし、死重の reset や hooks を削る
| 状況 | まず試す | まだ足りないとき |
|---|---|---|
| 短い対話開発 | 内部ハーネス素のまま + 最小 CLAUDE.md | スキル／スラッシュを1つ |
| 複数セッションの実装 | progress + git + feature list | initializer 相当の初回セットアップ |
| 品質の自己申告が甘い | /goal または独立 evaluator |
Default-FAIL hooks |
| 設定が肥大 | 棚卸しで削除 | Markdown 手順へ移植してポータブル化 |
出典: 上記 Anthropic Engineering 各記事および cwc-long-running-agents（2026年時点）
上表から1行選び、今日中に1項目だけ実施するのが次アクションです。全部を一度に足す必要はありません。
実務で確認すること
効率化の入り口として、Claude Code 効率化テクニック も外部設定を増やす前の見直し材料になります。実行境界やブラウザ操作の分離に関心がある場合は、Desktop の in-app ブラウザとサンドボックス もあわせて読むと、内部ハーネス側の境界が見えやすくなります。
よくある質問
実務で確認すること
まとめ — 層を分けて、最小から足す
- モデル／内部ハーネス／外部ハーネスを混同しない
- 長時間タスクは増分進捗とクリーンなハンドオフを先に置く
- done 判定はビルド主体から分離する
- 外部設定は不足が観測されてから足し、モデル更新後に削る
ハーネス設計の目的は、設定ファイルを増やすことではありません。失敗モードを減らす最小の実行機構を選び、モデル進化で前提が変わったら軽く保つことです。今日は層の名指しと、進捗ログ／git／feature list の Yes/No 点検から始めてください。
著者
krona23
IT業界20年以上の実務経験を持ち、日本国内有数のPVを誇る大規模Webサービスで事業部長・CTOを複数社で歴任。Windows/iOS/Android/Webと技術の変遷を経験し、現在はAIネイティブへの変革に注力。DevGENTでは、AIコードエディタ・自動化ツール・LLMの実践的な使い方を日英西3言語で発信中。
コメントを残す