ハーネス設計入門 〜 基礎知識の整理から実務へのステップアップ 〜

Findy様主催のWebセミナー（2026/9/24）での登壇資料です。
https://findy.connpass.com/event/405902/

Transcript

1. H AR N ESS ENG IN EERIN G ・ SEMINA R ハーネス設計入門 〜 基礎知識の整理から実務へのステップアップ 〜 木下 雄一朗（Kinopee）｜ 株式会社キー・プランニング 代表取締役
2. A B OU T M E ／ 自 己 紹 介 AI開発に没頭して、コードや記事・書籍を書いています。 氏名 木下 雄一朗（Kinopee） 所属 株式会社キー・プランニング 代表取締役 書籍 「AIを開発チームに採用する技術」（9月1日発売） 「AIエディタCursor完全ガイド」ほか多数 連載 Software Design 「プログラミング×AIの最前線」 アンバサダー Devin Ambassador SpaceXAI Ambassador Regional Leader (East Asia) X https://x.com/kinopee_ai 02 / 30
3. P AR T 1 · HI S TO R Y & S C H OO L S 第1部 ハーネスエンジニアリングの系譜 — 5つの流派と、定義の違い — その後の収束と標準化、そして実証 03 / 30
4. O V E R V IE W ハーネスエンジニアリングとは エージェントが同じ失敗を繰り返さないよう、モデルの外側（環境）を設計すること AGENT = MODEL + HARNESS 指示ファイル・ツール・検証・ガードレール・ループなど、モデル以外のすべてがハーネス。 PROMPT ENG. 2022– → CONTEXT ENG. 2024– → HARNESS ENG. 2026– 2026.02.05 Mitchell Hashimotoが命名。「失敗したら、二度と起きないよう環境を直す」 2026.02.11 OpenAIが実践例を公開。3人で100万行、95%をAIが生成 以降 各社・論者が追随。ただし定義は論者ごとに違った（次頁で5つに整理） 04 / 30
5. 5つの流派 同じ「ハーネス」でも、論者が手本にした実装によって意味の範囲が違う 1 2 3 4 5 Chase派 Hashimoto派 Fowler派 Chawla派 Codex派 広義・分類論 運用哲学 制御理論 同心円モデル スケール駆動 代表者 代表者 代表者 代表者 代表者 Harrison Chase (LangChain) Mitchell Hashimoto Birgitta Böckeler (Thoughtworks) Avi Chawla (教育系) Ryan Lopopolo (OpenAI Codex) 中核主 張 中核主 張 中核主 張 中核主 張 中核主 張 モデル以外の すべてがハーネス 失敗したら環境を 再設計せよ コンテキスト設計の 特殊形として定義 LLMのOS層 三重の入れ子 スケールで壊れる 問題の答え 05 / 30
6. 対立の構造 どちらが外側かが、流派によって逆になる Chase派 / Chawla派 ハーネス ⊃ コンテキスト Fowler派 コンテキスト ⊃ ハーネス ハーネス (外層) コンテキスト設計 (外層) コンテキスト ハーネス (特殊形) プロンプト 総合フレーム設計の視点 ⇄ guides + sensors 制御理論 (feedforward / feedback) の視点 2026年前半は、この違いが議論の中心だった。その後、言葉は収束していく（次頁） 06 / 30
7. A F T E R M AT H ・ C ON V E R G E N C E その後：語彙の収束と標準化 語 彙 の 収 束 （ 2 0 26 年 3 〜 7 月 ） 03.10 LangChain「The Anatomy of an Agent Harness」で 構成要素を整理 04.19 Addy Osmani「ハーネスはモデル同士より互いに似て きている」 06 Build 2026 で Agent Harness 安定版／Pydantic v2.0 がハーネス中心に再設計 2026 Linux Foundation が Agentic AI Foundation を設立 （MCP・AGENTS.md・Goose） Agent Plugins 1.0（2026.08.06）：標準化の現在地 Skills・MCPサーバーを1つのフォルダ形式（plugin.json＋skills/＋ mcp.json）に。Vercel発案、Amazon・Cursor・GitHub・Microsoft・ OpenAIが策定し、Googleも参加。 実装が出た ChatGPT・Codex・Cursor・GitHub Copilot・Kiro・ VS Code が対応。一度作れば、複数のクライアントで使えるように なった。 ただし互換性は一部にとどまる ・Claude Code は独自形式のままで未対応 ・Skills か MCP の片方だけ対応のクライアントもある。対応表の確 認が必要 ・hooks・コマンド・rules は対象外で、クライアントごとに異なる 5つの流派の言葉づかいは、約5か月でほぼ一つにまとまった。 言葉はまとまり、形式の標準化も始まった。ただし互換性はまだ一部 07 / 30
8. EVIDENCE 実証：ハーネスで結果が変わる モデルを変えずに、ハーネスだけで成績や品質が変わった3つの例 ベン チマーク 順位 設定 による差 品質 低下の原 因調査 30位→トップ5 ±5pt 以上 3件中3件 モデルはそのまま、ハーネスの変更 だけで Terminal Bench 2.0 の順位が 上がった（LangChain） ハーネスの設定だけで、スコアがこ れだけ動く（Anthropic 2026 Agentic Coding Trends Report） Claude Code の品質低下の原因は、 すべてハーネス側の変更だった （2026年4月） 第2部では、このハーネスをどう設計するかを扱います 08 / 30
9. PART 2 · PRACTI CE 第2部 ハーネス設計の実践 — AIエージェントを自走させるための設計 — ハーネス・ガードレール・ループ、柵の外側にある「境界」
10. A GE ND A 第2部の流れとゴール ゴール エージェントが自分で失敗に気づき、自分で直して完走する。その仕組みの設計方法を持ち帰る。 1 2 3 ハーネスを作る ガードレールを張る ループを閉じる 「どう走ってほしいか」をエージェン トに伝える層。AGENTS.md・Skills・ サブエージェントで構成する。 逸脱を機械的に見つける層。lint・型 チェック・テストを導入し、「1コマン ドの門」に束ねる。 検証器とゴールを渡し、エージェント が自分で直して完走する。 進め方 概念 → 道具 → 柵 → 境界の順に進みます。 ハーネス設計入門 10 / 30
11. PR EMI SE ・ PR OB A B I LIST IC 前提：生成AIは確率で動く 同じ指示でも、出力は毎回同じとは限りません。これが動作原理です（図中の数字は説明用のイメージ）。 ① 1トークンごとに、確率で選ぶ ② 小さな揺らぎ × 数千トークン 「テストを ___ 」の次に来る語の分布： 動くコード A 書く 54% 実行する 28% スキップする 11% （その他） 7% 低確率の「悪い一手」も、ゼロではない 従来のプログラム：同じ入力 → 同じ出力（決定的） 同じ指示 動くコード B（別解） 逸脱（危険な一手） どの経路になるかは、実行のたびに変わる 生成AI：同じ入力 → 分布からのサンプル（確率的） 指示だけに頼らず、環境と検証で受け止める（次頁） ハーネス設計入門 11 / 30
12. FOU N DA TIO N ハーネスとガードレール：役割の違う2つの仕組み 第1部のハーネス（モデル以外のすべて）を、指示で伝える部分と機械的に判定する部分に分けます。 H AR N ES S GU A RD RA IL S ハーネス ＝ 馬具 ガードレール ＝ 柵 走り出す前に「どう走ってほしいか」を伝える、事前設 計の層。 走った後に「逸脱していないか」を機械的に検証する、 事後検証の層。 • ルール（カスタムインストラクション / AGENTS.md） • Skills（再利用可能な手順書） • サブエージェント（役割分担と委任） • 静的解析（lint・フォーマット・型チェック） • ビルド • テスト（ユニット / 結合 / E2E） • Hooks（危険な実行を事前に止める） ハーネスは確率的、ガードレールは機械的。 機械的な判定が強いほど、エージェントにハンドルを預けられる。 ハーネス設計入門 12 / 30
13. H AR N ES S I N DE TA IL ハーネス：走り出す前に伝える、事前設計の層 役割 走り出す前に「どう走ってほしいか」を伝える。プロジェクトの前提・規 約・手順・禁止事項を、エージェントが参照できる形で明文化しておく。 性質 内容は人間の判断で決める「主観」の層。書いた分だけ効くが、書きすぎ るとコンテキストを圧迫する。何を書くかを選ぶのが設計。 馬具（bridle & reins）：手綱で進路を伝える ハーネス設計入門 ハーネスは自然言語で伝える「意図」。モデルは確率で動くため、効き 目は絶対ではない。だから柵（機械的な判定）と組み合わせる。 13 / 30
14. GU A RD RA IL S IN D ETA IL ガードレール：道から外れていないかを検証する層 役割 走った後に「道から外れていないか」を機械的に検証する。lint・型・ビル ド・テストで Yes / No を判定する。 性質 誰が実行しても結果が同じ「客観」の層。判定が機械的であるほど、エー ジェントは自分で失敗に気づき、自分で直せる。 防護柵（guardrails）：道の両脇で逸脱を止める ガードレールの判定は機械的なので、何度実行しても同じ結果になる。確率で動 くモデルを、決まった判定で支える。 ハーネス設計入門 14 / 30
15. FE E DB AC K LOO P フィードバック・ループ：検証器とゴールを渡す 1 実装する エージェントが タスクを進める 2 検証する check を自分で実行し、 結果を読む 3 自分で直す ↻ 自分で繰り返す 失敗の出力をもとに 修正・再実行 人が用意するもの 検証器＝門 ゴール＝check がすべて通る AGENTS.md に書く → check の1コマンド → タスク固有はプロンプトで → 実行コマンドと共通の条件 タスク固有の条件もテストにして check に入れれば、「check がすべて通る」で完了を判定できる。 検証器とゴールを渡せば、エージェントは自分でループを閉じる。 ハーネス設計入門 15 / 30
16. H AR N ES S TO OLB OX ハーネスの道具箱：適用範囲で使い分ける 同じ「事前に伝える」でも、効く範囲と深さが違う3つの道具。左から右へ、適用範囲が狭く・深くなります。 ルール 適用: 常時 Skills 適用: 必要なとき サブエージェント 適用: 役割単位 AGENTS.md。主要ツールが読む、事実上 の共通形式。毎回のセッションに自動で入 り、薄く広く効く。 特定作業の手順書。必要な場面でだけ読み 込まれるため、常時のコンテキストを圧迫 しない。 専用のプロンプトを与えられた専門家。調 査・実装・レビューなど役割ごとに委任し、 独立した文脈で動く。 規約・コマンド・禁止事項 定型作業の再現性 並列化と文脈の分離 第一歩はルール（AGENTS.md）。 常時効く土台をまず固め、Skills・サブエージェントはその上に積む。 ハーネス設計入門 16 / 30
17. W RI TIN G RU LE S AGENTS.md：何を書き、何を書かないか ルールは毎回コンテキストに読み込まれるので、1行ごとに「家賃」がかかります。何を書くかを選ぶのが設計です。 補足：Claude Code は CLAUDE.md があればそちらを優先し、なければ AGENTS.md を読む（v2.1.277以降） ◎ 書くこと ✕ 書かないこと • プロジェクト概要（1段落で） • 一般常識・言語の一般的な作法 何のための何か。目的がわかると判断が揃う モデルはすでに知っている。書くだけ無駄 • コマンド（ビルド・テスト・lint） • コードを読めばわかること エージェントが自分で検証できるようになる 実装と二重管理になり、すぐ食い違う • プロジェクト固有の規約・構成 • 長大な設計書の貼り付け 命名・ディレクトリ・エラー処理の流儀 常時読むには重い。Skills や参照リンクへ • してはいけないこと • 守れているか検証できない精神論 触ってはいけないファイル、変更禁止のAPI 「きれいに書く」は、機械的に判定できる形にする 目安 最初は最小限に。全行が実際の失敗や規約に対応していることが基準。足りない分は、逸脱が出たら1行足して育てる。 ハーネス設計入門 17 / 30
18. S KI LLS Skills：必要なときだけ読む手順書 ルールに全部書くとコンテキストが溢れる。定型作業は Skill に切り出し、必要な場面でだけ読ませます。 SKILL.md の基本形 # エンドポイント追加 ## 使いどころ REST APIに新しいルートを足すとき ## 手順 1. routes/ にルート定義を追加 2. handlers/ に処理を実装 3. バリデーションを schemas/ に定義 4. テストを __tests__/ に追加 5. docs/api.md を更新 ## 模範例 routes/health.ts を参照 判断基準 毎回必要なら → ルール 特定作業でだけ必要なら → Skill 迷ったら Skill に逃がす /create-skill で対話的に生成できる。この形になっていればOK ハーネス設計入門 18 / 30
19. S UB A GE NTS サブエージェント：2つの呼び出し方 親の文脈を汚さず、役割を分けて委任する仕組み。「その場で作る」と「定義して呼ぶ」の2系統を使い分けます。 A. オンデマンド生成 B. 事前定義して呼び出す 親エージェントが、必要になった瞬間に子を起こして仕 事を振る。使い捨ての委任。 役割・観点・出力形式をファイルに定義しておき、名前 で呼ぶ。育てて共有する委任。 向く場面 向く場面 大量の調査・比較の並列化 ／ コンテキストを大きく消費す る探索 ／ 結果の要約だけ持ち帰りたいとき 毎回同じ観点で行う作業（レビュー、セキュリティ監査、テ ストなど）。チームで観点を共有したいとき 「3つのライブラリを、それぞれ別のサブエージェントで並列 に調査して要点だけ報告して」 レビュー専門エージェント：「差分を 規約・セキュリティ・ テスト網羅 の3観点で指摘」 並列のメリットと注意点 非同期で並行に走らせると、待ち時間は大きく減る。ただし同時に走る数だけ、時間当たりのトークン 消費は増える。数と深さは費用対効果で決める。 共通するのは「文脈の分離」。 子にも子のハーネスが効く。定義ファイルは、サブエージェント用の AGENTS.md にあたる。 ハーネス設計入門 19 / 30
20. GU A RD RA IL S TOOLB OX ガードレールの階層：右へ行くほど判定が強い どれも機械的に Yes / No を判定する仕組み。検証する対象が、表記 → 整合性 → 振る舞い へと深くなります。 フォーマッタ リンター 型チェック ビルド テスト 表記の統一 作法の検査 整合性の検証 成立の確認 振る舞いの保証 Prettier / gofmt など。議 論の余地なく自動修正 ESLint / Clippy など。バ グの芽と規約違反を静的 に検出 tsc / mypy など。データ の流れの矛盾を実行前に 検出 成果物として成り立つか の最低ライン 仕様どおり動くかを確認 機械的な判定の強さ・検証の深さ 門 5つを check の1コマンドに束ね、人もAIも同じ門をくぐる。共通の完了条件は、check がすべて通ること。 原則 ガードレールが強いほど、エージェントは自分の失敗に気づける。その分、任せられる範囲が広がる。 ハーネス設計入門 20 / 30
21. G UA R D R A IL S ・ R A IL S 柵を走らせるレール：いつ・どこで判定するか 柵（前頁の5つ）は判定する道具。レールは柵を自動で走らせる仕組みで、3本ある。外側ほど強制力が強い。 ク ラ イ ア ント 内 リポジトリ リモート エージェントの Hooks Git hooks CI 編集・実行の瞬間 コミット・push 時など PR 作成・更新時など 例 afterFileEdit で lint／ beforeShellExecution で rm を 止める 例 Husky・lefthook など。precommit／pre-push で check を 実行 例 同じ check をパイプラインで実 行。ブランチ保護で失敗時は マージ不可 役割 最速で柵を走らせる。「行動へ の柵」も兼ねる 役割 人もAIも、コミットや push の前 に同じ門をくぐる 役割 手元ですり抜けても、ここで必 ず捕まえる 強制力 クライアントの設定で無効にで きる 強制力 --no-verify で抜けられる。強制 力は中 強制力 抜けられない。強制力は最大 近い・速い・弱い 遠い・遅い・強い 内側で速く気づき、外側で確実に止める。レールもハーネスの一部 ハーネス設計入門 21 / 30
22. TW O KI ND S OF GU AR DR A ILS 柵は2種類ある：成果物への柵と、行動への柵 ここまでの柵はすべて「書いたもの」を検証する柵。もう1種類、「これからやること」を止める柵があります。 成果物への柵 行動への柵 書いたものを、事後に検証する 危険な実行を、事前にブロックする • lint・型チェック・ビルド・テスト 判定の対象はコード。npm run check に束ねた • 問うこと：「正しく作れたか」 失敗はループの入力になる（フィードバックループ） 作り込みの中心はこちら • Hooks・許可リスト（判定する柵） /create-hook で作成。beforeShellExecution で rm や外部送信を止 める など • 問うこと：「実行してよいか」 判定の対象は行為。起きる前に止めるしかない事故に使う → 判定しない「境界」は次頁で説明 共通の原理 どちらも、人の注意力に頼らず機械的に止める。テストが落ちたコードをマージできないのも、危険なコマンドを実 行できないのも、同じ仕組み。 ハーネス設計入門 22 / 30
23. T H R E E L A Y E RS 馬具・柵、その外側にある境界：3層で見るハーネス設計 方向を与える馬具、道から外れていないかを検証する柵、触れる範囲を決める境界。 1 6 馬具：方向 走る前に「どう走るか」を与える。AGENTS.md・Skills 2 道から外れていないかを機械的に検証する。lint・型・テス ト・Hooks。結果はエージェントが読んで直す 4 3 1 柵：判定 5 境界：可動域 触れる範囲を決める。外へ通じる道がない。隔離・遮断・最 小権限 4 完了 check がすべて通ったら終わり 2 5 開始 境界の内側で走り始める 3 6 到達不能な資産 本番・DB・機密・個人情報。壁の外にあり、道がない 柵は道の端で逸脱を検知する。境界は、戻れない場所への道を最初から作らない ハーネス設計入門 23 / 30
24. T H R E E L A Y E RS ・ R OL E S 3層の役割：方向・判定・可動域 馬具と柵は既出。新しいのは境界。柵は漏れることがあり、漏れると取り返しのつかない事故もあるため。 ここが新しい層 ハーネス イン フラ境界 馬具 境界 可動域を決める 方向を与える 問い 本番 DB 機密 × × × 触れられるか 可動域（壁の内側） 性質 ガードレール 柵 道具 道から外れていないかを検証する 強度 の階段 指示する 確率的 守備 構造・事前。判定せず、到達自体を無くす コンテナ／サンドボックス・通信遮断・最小権限 馬具と柵は、この中で働く 外には道がない 不可逆な事故 → 柵で止める 機械的 → 境界で不可能にする 構造的 可逆な逸脱は柵で拾ってループに戻す。不可逆な逸脱は境界で、試行そのものを無くす。 ハーネス設計入門 24 / 30
25. SEC U R ITY ハーネスとセキュリティ：任せるほど、守りが要る 自律性を上げるほど、エージェント自体が攻撃の入口になる。 1 間接プロンプトインジェクション 2 機密・個人情報の漏洩 外部コンテンツに紛れた指示に従ってしまう 認証情報や顧客データを読ませない 3 4 破壊的操作 rm や force push を、実行できなくする サプライチェーン 提案された依存パッケージは、人が確認する 危険が最大化する条件 機密データへのアクセス × 不審コンテンツの読み取り × 外部への送信。この3つを同時に許さ ない（lethal trifecta）。 守りも仕組みで作る：行動への柵 × 隔離（サンドボックス）× 信頼境界（審査済みSkill・Pluginのみ） ハーネス設計入門 出典: Simo n Wi llison “The lethal trifecta for AI agents” (2025.06.16) simonwilli son.net/2 025/Jun/16/the-lethal-trifecta/ 25 / 30
26. C OS T ・ E FF IC I E NC Y 自走時間は目的ではない：短く・少なく・安く 自走は手段。短く・少なく・安く終えることが目標になった。 Uberのコスト方程式（6つの項の掛け算） ユーザー数 × セッション /ユーザー × ターン /セッション × Uberの結果（2026年2月→8月） リクエスト /ターン × トークン /リクエスト × 利用の広がり（増えてよい） 単価 /トークン モデル選択 エージェントのオーバーヘッド：ハーネスで減らせる ↑ 増えてよい項は増えた 利用者 7倍、リクエスト 9.4倍 → それでも総コストは横ばい 4月以降、ほぼ一定 ↓ 中央の3項を減らすのは、ハーネスの仕事 ターン 計画を速くし、不要なターンやエラーを減らす リクエスト 根拠づけ（社内情報のグラフ）で、無駄な探索を減らす トークン 常駐コンテキストを削る（MCPのCLI化、キャッシュ） 中央の3項が下がった 1,000リクエストあたり −34% 1セッションあたり −52% （コスト。ピーク比、モデル固定） いちばん効いた手 サブエージェントを安いモデルに（方程式の右 端「単価」） 長く走ったことは、成果ではない ハーネス設計入門 出典: uber.com/us/en/blog/efficient-software-factory (2026.08.27) ／ 解説: note.com/fladdict/n/nd62972dd23bb 26 / 30
27. H ID D E N T E C H NI C A L DE B T ハーネスは、隠れた技術的負債 作り込んだハーネスにも寿命がある。 「良いチームほど多くのハーネスを作る。その多くは次世代モデルで不要になる」 （Han Lee, 2026） 現行モデル世代 回避策 作り込み 次世代モデル 弱点を補う注意書き。例：「省略せずに全部出力し て」「全部読んでから直して」 細かく刻んだ手順、独自のリトライ処理 回避策 モデル更新 溶けて消える （モデルに吸収） 作り込み → 中核 テスト（check）、権限と境界、プロジェクト固有の 規約 MODEL 中核 残る：柵・境界・ 固有の規約 MODEL（賢く・大きく） ある時点の形に固執せず、薄く軽く保ち、定期的に棚卸しする。 ハーネス設計入門 27 / 30
28. O RD E R OF W O RK ハーネスエンジニアリング：手順 何から手をつけるか。逆順にやると、効かないルールと使われない道具が積み上がります。 1 2 3 4 5 6 境界を引く：安全な作業環境を用意する サンドボックスかクラウドエージェントで作業し、本番の認証情報は渡さない。 ルールを書く（AGENTS.md） 最小限から。全行が実際の失敗や規約に対応。AIに草案を書かせ、人間が削る。 柵を立て、「1コマンドの門」に束ねる lint・型・テストを check に。人もAIも同じ門をくぐる。 ループを閉じる 検証器とゴール（check がすべて通る）を渡し、エージェント自身に回させる。 繰り返しが見えたら、道具を増やす 繰り返す手順はSkillsへ、観点はサブエージェントへ。 運用で育て、定期的に棚卸しする 逸脱が出たら1行追記。数か月に一度は全削除し、要るものだけ戻す棚卸しを (Git管理で安全に試せる)。 境界を先に引く。ルールより先に道具を増やさない。 ハーネス設計入門 28 / 30
29. C ON CLU S ION まとめ：ハーネスエンジニアリング 4原則 1. 戻れない場所に道 を作らない 本番・機密・個人情報・不 可逆な操作は、到達できな いようにする。隔離環境・ 通信遮断・最小権限で、境 界を先に引く。 ハーネス設計入門 2. 進路はハーネスで 示す 3. 逸脱はガードレー ルで検知 4. ループを閉じて自 走させる 規約・コマンド・禁止事項 を明文化し、逸脱が出るた びに1行足す。書いたあと lint・型・テスト・Hooks を「1コマンドの門」に束 ね、人もAIも同じ門をくぐ 検証器とゴールを渡せば、 エージェントが自分で直し て完走する。任せられる範 の運用が大事。 る。判定は機械的に。 囲が広がる。 29 / 30
30. C LOSIN G ご清聴ありがとうございました 質問・感想、お待ちしています。 X 書籍・連載 コミュニティ @kinopee_ai （https://x.com/kinopee_ai） 「AIを開発チームに採用する技術」9月1日発売 → Software Design「プログラミング×AIの最前線」連載 AIAU（AIエージェントユーザー会） 木下 雄一朗（Kinopee）｜ 株式会社キー・プランニング 30 / 30