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

Transcript

1. ハーネスエンジニアリング入門 AIエージェントの性能は モデルではなく "環境" で決まる hatyibei | 2026.05 1
2. 自己紹介 名前 hatyibei 仕事 Sier Tech Lead チーム 2 社会人歴 4年目 Zenn記事
3. アジェンダ 1. ハーネスエンジニアリングとは 2. なぜ注目されているのか 3. 主要フレームワーク 4. 実践のポイント 5. まとめ 3
4. アジェンダ 1. ハーネスエンジニアリングとは 2. なぜ注目されているのか 3. 主要フレームワーク 4. 実践のポイント 5. まとめ 4
5. Agent = Model + Harness ハーネスとは、モデル以外のすべて 設定ファイル、ツール、メモリ、フック、ルール モデルを取り囲む実行環境の総称 5
6. コンピュータに例えると ※ ハーネスの中核機能を説明するための比喩。ハーネス全体 = モデル以外のすべて。 Application（エージェントのロジック） OS（ハーネスの中核：起動・メモリ管理・ドライバ） RAM（コンテキストウィンドウ） CPU（AIモデル：Claude, GPT, Gemini…） モデルがどれだけ賢くても、 OSが貧弱だとアプリは動かない Phil Schmid（Hugging Face）のOSアナロジーより 6
7. 進化の系譜 2023-2024 Prompt Engineering 指示文の書き方を 工夫する → 2025 Context Engineering モデルに渡す 入力全体を設計する → 2026〜 Harness Engineering モデルを取り囲む 環境ごと設計する 7
8. ハーネスの 4つの役割 Constrain 制限する AIができることの 範囲を定める → Inform 文脈を与える 必要な情報を 適切に渡す → Verify 検証する 出力が正しいか 確認する → Correct 修正する 間違いを検知して 自動修正する 8
9. 3つの柱 Context Engineering AGENTS.mdなどの静的文脈 ＋ ログやCI状態の 動的文脈を設計する Architectural Constraints リンター・CI・構造テストで ルールを機械的に強制する Entropy Management AI生成コードは放置すると 劣化する。定期的な クリーンアップが必須 9
10. アジェンダ 1. ハーネスエンジニアリングとは 2. なぜ注目されているのか 3. 主要フレームワーク 4. 実践のポイント 5. まとめ 10
11. 同じモデルで 10倍の性能差が出る 変えたのはハーネスだけ 11
12. TerminalBench 2.0 の結果 AIコーディングエージェント用ベンチマーク。 89個の実際のターミナルタスクを解かせて正答率を測定 6.7% → 68.3% Grok Code Fast 1 TerminalBench 2.0（89タスク） モデルは一切変更していない 変えたのは編集ツールのフォーマットだけ モデル変更 ⇒ +1ポイント ハーネス変更 ⇒ +22ポイント ※ SWE-bench（GitHub Issue解決ベンチマーク）での正答率ポイント差。 Morpho社の計測。 12
13. LangChainの事例 ハーネスの改善だけで ベンチマーク Top 30 ⇒ Top 5 に躍進 モデルは固定。追加したのは 4つのミドルウェア： Self-verificationループ（テスト実行 ⇒ フィードバック） 起動時のディレクトリ構造マッピング ループ検出（同じファイルをN回編集したら再考を促す） Reasoning sandwich（計画・検証に高推論、実装に中推論） ※ AGENTS.mdに手書きではなく、ミドルウェア（コード）として自動実装されている 13
14. なぜ今、注目されているのか モデルの性能差は縮まりつつある トップモデル同士のベンチマーク差は数 % しかし同じモデルでも ハーネスの違いで22点差がつく モデル選定よりハーネス設計が 性能の支配的要因になった 14
15. アジェンダ 1. ハーネスエンジニアリングとは 2. なぜ注目されているのか 3. 主要フレームワーク 4. 実践のポイント 5. まとめ 15
16. ① Anthropic公式パターン Initializer Agent + Coding Agent 長時間タスクで発生する 2大問題を解決： 「全部一気にやろうとする」「途中で完了宣言する」 16
17. Initializer Agent（初回だけ） 「段取り屋」が引継ぎ書を作る init.sh 開発サーバの起動スクリプト feature_list.json 全機能一覧（passes: false フラグ付き） progress.txt セッション横断の進捗ログ 17
18. Coding Agent（毎セッション） 毎回の「起動儀式」： 1 git log で現状把握 2 progress.txt を読み込む 3 init.sh で環境復元 4 未完了の機能 1つだけに着手 5 テスト → commit → 進捗更新 鍵：「1セッション1機能、必ずcommitして終了」 18
19. ② Everything Claude Code（ECC） GitHub 78K+ Stars 10ヶ月以上の実運用から生まれた 実戦投入型ハーネス最適化システム 19
20. ECCの7コンポーネント Skills オンデマンドのワークフロー定義（ 65種） Instincts 自動学習された行動パターン（信頼度スコア付き） Memory AGENTS.md + MEMORY.md でセッション横断の文脈永続化 Hooks ツール実行前後・セッション開始 /終了時に自動実行されるスクリプト Rules 言語・タスク別に分類された常時適用のコーディング規約 Agents 16種の専門サブエージェント（ planner, code-reviewer 等） Commands 40+のスラッシュコマンド（ /tdd, /plan, /security-scan 等） 4ツール対応：Claude Code / Cursor / Codex / OpenCode 20
21. Hooks — いつ何が自動実行されるか Gitのpre-commitフックと同じ発想。エージェントのライフサイクルの各段階で処理を差し込める。 PreToolUse ツール実行の前 例: bashコマンド実行前にセキュリティチェック PostToolUse ツール実行の後 例: ファイル編集後に自動リント・型チェック SessionStart セッション開始時 例: 前回の進捗ファイルを読み込む Stop エージェント停止時 例: セッション要約を保存する 21
22. ③ 12-Factor Agents（HumanLayer） 元：12-Factor Apps（Heroku, 2012年） 「良いWebアプリの12の設計原則」として広く普及 例：設定は環境変数で管理、プロセスはステートレスに ログはイベントストリームとして扱う等 この考え方をAIエージェントに応用したのが 12-Factor Agents 22
23. 12-Factor Agents — 全12要素 1 自然言語 → ツールコール変換 2 プロンプトを自分で所有する 3 コンテキストウィンドウを自分で所有する 4 ツールは構造化出力に過ぎない 5 実行状態とビジネス状態を統合する 6 起動/一時停止/再開をシンプルなAPIで 7 人間への連絡もツールコールで 8 制御フローを自分で所有する 9 エラーをコンテキストウィンドウに圧縮する 10 小さく集中したエージェント 11 どこからでもトリガー可能 12 エージェントをステートレスリデューサーに ▪ = 特に重要な4つ 23
24. 特に重要な 4つのFactor 3 コンテキストを自分で管理する 利用率40%超で性能劣化 7 人間への連絡もツールコールで Human-in-the-loopをファーストクラスに 8 制御フローを自分で所有する フレームワーク任せにしない 10 小さく集中したエージェント 1エージェント 3-10ステップが上限 24
25. ④ AI-DLC（AWS提唱） 「AIが提案し、人間が承認する」 AIネイティブな開発ライフサイクル 25
26. AI-DLCの3フェーズ Inception 構想 AIがIntentを 要件・Unitに分解 → Construction 構築 Unit単位で AIがコード生成 → 人間が承認 → Operation 運用 蓄積コンテキストで IaC・デプロイ管理 Construction = ハーネスエンジニアリングの実践の場 26
27. ⑤ Superpowers（Prime Radiant） GitHub 72.6K Stars “Skills”で開発ワークフロー全体を自動制御 サブエージェント駆動開発 + TDD強制のオーケストレーション 27
28. Superpowers — コアコンセプト ECC = ハーネス全体の最適化　｜　Superpowers = 開発ワークフローのオーケストレーション ① brainstorming 対話で設計を引き出す 「何を作るか」を確定 ② writing-plans 2〜5分単位のタスクに分解 ファイルパス・コード明記 ③ subagent-driven development タスクごとにサブAgentを ディスパッチ ④ 2段階レビュー 仕様準拠 → コード品質 鍵：サブエージェント駆動開発 タスクごとに独立のサブ Agentを起動し、完了後に仕様準拠 →コード品質の2段階でレビュー。 人間の介入なしで数時間自律的に開発を継続できるのが最大の特徴。 TDD、git worktree、コードレビューも Skillsとして自動発動。 28
29. 5つのフレームワーク比較 Anthropic ECC 12-Factor AI-DLC Superpowers 思想 漸進的進捗 包括的最適化 Agent=SW AI提案→人間承認 ワークフロー制御 メモリ progress.txt + git AGENTS.md + MEMORY.md イベント ストリーム ステアリング ファイル SKILL.md + git worktree サブAgent Initializer + Coding 16専門Agent マイクロ (3-10step) Agent Teams サブAgent 駆動開発 セキュリティ パーミッション AgentShield 3段階 Human-in- the-loop ゲート付き承認 2段階レビュー 対応ツール Claude Code 4ツール対応 非依存 Amazon Q/Kiro 4ツール対応 最適場面 長時間タスク 日常コーディング カスタムAgent 大規模チーム 自律開発 28
30. 結局、どう使い分けるのか？ 答えは「人間の目が届くかどうか」で決まる 30
31. HITL開発 vs 並列エージェント開発 HITL（1セッション） 人間が毎回レビューする ミスはその場で捕捉できる ガードレールは最低限で OK → フレームワーク 1つで十分 並列エージェント（複数セッション） 人間の目が全部に届かない ミスが気づかれず蓄積する ガードレールが薄いと負債が爆発 → 多層防御が必須 31
32. 並列開発で何が起きるか 単一フレームワークだと捕捉できない問題 設計の不整合 Agent Aが作ったAPIとAgent Bが呼ぶAPIの型が合わない。 brainstormingなしで実装に入る と発生 品質のバラつき あるAgentはTDD、別のAgentはテストなし。レビュー基準が統一されていないとマージ後に 崩壊 サイレントな負債蓄積 各Agentが「動く」コードを出すが、設計原則やコード規約が徐々に崩れる。気づいたときに は手遅れ → 並列開発では「被り」は冗長ではなく、防御の多層化 32
33. 全部乗せ = 多層防御 Superpowers　設計・計画・サブ Agentオーケストレーション ECC　品質・セキュリティ・ルール強制 AI-DLC　ライフサイクル管理・承認フロー 実践ステップ 1. 全部インストール 2. ADRで重複箇所の優先順位を明文化 3. 運用しながら不要な層を削る 「被り」を恐れるのではなく、「被り」を意図的に設計する。 並列エージェント時代のハーネスエンジニアリングは、多層防御の設計そのもの。 33
34. アジェンダ 1. ハーネスエンジニアリングとは 2. なぜ注目されているのか 3. 主要フレームワーク 4. 実践のポイント 5. まとめ 28
35. AGENTS.md — ハーネスの設定ファイル コンパクション後も生き残る唯一のコンテキスト 60行以下が理想 システムプロンプトだけで指示枠の1/3を消費済み 多くても200行。それ以上は遵守率が急落する ポインタ設計 詳細は .eslintrc / tsconfig / docs/ に委任 AGENTS.mdは参照リンク集。複数FW併用時はADRで優先順位を管理 5階層で分散配置 ユーザー → root → サブディレクトリ 加算的に適用タスク別にRulesで分離もできる 29
36. トークン最適化 入力前に 50-70Kトークンが消費済み（ 200Kの25-35%） 設定 デフォルト 推奨 効果 model opus sonnet コスト約60%削減 MAX_THINKING_TOKENS 31,999 10,000 思考コスト約70%削減 AUTOCOMPACT_PCT 95 50 品質劣化前にコンパクション SUBAGENT_MODEL （継承） haiku 探索・テスト約80%安く 30
37. 導入ロードマップ Level 1 1-2時間 基本 AGENTS.md作成 / pre-commitフック / テスト整備 Level 2 1-2日 チーム AGENTS.md整備 / CI制約 / 共有テンプレート Level 3 1-2週間 本番 複数FW併用 / ADR整備 / オブザーバビリティ / GCエージェント 31
38. アジェンダ 1. ハーネスエンジニアリングとは 2. なぜ注目されているのか 3. 主要フレームワーク 4. 実践のポイント 5. まとめ 32
39. 今日のまとめ 1 ハーネス = モデル以外のすべて（設定・ツール・メモリ・フック） 2 同じモデルでもハーネスで10倍の性能差が出る 3 5つのフレームワークが確立されつつある 4 まずは AGENTS.md を60行以内で書くところから 並列開発なら全部乗せ + ADRで多層防御を設計 33 5
40. Build to Delete. 削除前提で構築する モデルが進化すれば、ハーネスの一部は不要になる だからこそ、軽量で交換可能に設計する エージェントがミスをするたびに、 二度と同じミスをしないよう工学的に解決する — Mitchell Hashimoto（HashiCorp 共同創業者） Next Action：全部入れて、運用しながら削ろう 34
41. 参考 Anthropic Effective harnesses for long-running agents anthropic.com/engineering/effective-harnesses-for-long-running-agents Anthropic Building agents with the Claude Agent SDK anthropic.com/engineering/building-agents-with-the-claude-agent-sdk Vivek Trivedy The Anatomy of an Agent Harness blog.langchain.com/the-anatomy-of-an-agent-harness/ LangChain Improving Deep Agents with harness engineering blog.langchain.com/improving-deep-agents-with-harness-engineering/ Phil Schmid The importance of Agent Harness in 2026 philschmid.de/agent-harness-2026 HumanLayer 12 Factor Agents humanlayer.dev/blog/12-factor-agents HumanLayer Skill Issue: Harness Engineering for Coding Agents humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents affaan-m / obra Everything Claude Code / Superpowers (GitHub) github.com/affaan-m/everything-claude-code | github.com/obra/superpowers AWS AI-Driven Development Life Cycle aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/ OpenAI Harness engineering: leveraging Codex openai.com/index/harness-engineering/ Martin Fowler Harness Engineering martinfowler.com/articles/exploring-gen-ai/harness-engineering.html Can Bölük I Improved 15 LLMs — Only the Harness Changed blog.can.ac/2026/02/12/the-harness-problem/ Anthropic Best Practices for Claude Code code.claude.com/docs/en/best-practices NxCode Harness Engineering: The Complete Guide nxcode.io/resources/news/harness-engineering-complete-guide-ai-agent-codex-2026 35