AIエージェントは「デモでは動く、本番で壊れる」という呪いを抱えている。壊れる原因の多くはモデルの能力ではなく、その周囲を囲む実行環境——ハーネス——の設計にある。

Claude Codeによるエージェント設計の全体像は AIエージェントフレームワーク比較2026:LangGraph・CrewAI・AutoGen徹底解説 をご覧ください。

2026年5月、GitHubに登場したオープンソース agents-best-practices は、わずか1週間でスター数1000を超えた。Claude Code・Codex・その他のAgent Skill対応ランタイムで動く「プロバイダ中立のエージェントハーネス設計スキル」だ。

このリポジトリが示す核心は一文に凝縮される。

"The model proposes actions; the harness validates, authorizes, executes, records, and returns observations."

モデルは提案し、ハーネスが実行する。この分業の徹底こそが、本番品質のAIエージェントを作る唯一の方法だ。

この記事でわかること

  • agents-best-practicesの設計哲学と8つのコア原則
  • プロバイダ中立なエージェントループの実装(疑似コード付き)
  • ツールリスク分類14カテゴリと権限マトリクス
  • MVPハーネスブループリントの構成とLevel 0〜4の自律度
  • コンテキスト管理・オートコンパクション設計
  • セキュリティ・評価・可観測性の多層防御
  • Claude Code / Codexへのインストール手順

agents-best-practicesとは——1021スターのAgent Skill誕生の背景

2026年5月15日にリリースされた agents-best-practices は、エージェントハーネスの設計・生成・監査・説明を行うProvider-neutral Agent Skillだ。

リポジトリ基本情報(2026年5月24日時点)

  • スター: 1,021 / フォーク: 93
  • ライセンス: MIT
  • 言語: Markdown(実装依存なし)
  • トピック: agent-skill, agentic-workflows, claude, claude-code, codex, mcp, prompt-engineering

コーディングエージェントだけを対象にしていない点が特徴だ。リポジトリのREADMEは明示する:

“It applies beyond coding agents: research, support, operations, sales, finance, data analysis, procurement, legal workflows, healthcare workflows, education, and workflow automation agents all need the same core runtime discipline.”

研究・営業・財務・医療・教育——どのドメインのエージェントにも同じランタイム規律が必要だという設計思想がベースにある。

リポジトリ構造

agents-best-practices/
├── README.md                          # 概要・インストール手順
├── SKILL.md                           # スキルエントリーポイント・トリガー規則
├── icon.jpeg                          # スキルアイコン
└── references/
    ├── mvp-agent-blueprint.md         # MVPハーネスブループリント
    ├── architecture.md                # コンポーネントモデルとハーネス境界
    ├── agentic-loop.md                # ループ不変条件・リトライ・バジェット
    ├── tools-and-permissions.md       # ツール設計・リスク分類・承認
    ├── planning-and-goals.md          # 計画モード・長期実行ゴール
    ├── context-memory-compaction.md   # コンテキスト・メモリ・コンパクション
    ├── prompt-caching-and-cost.md     # 安定プレフィックスとコスト制御
    ├── skills-and-connectors.md       # Agent Skills・MCP・コネクター
    ├── system-prompts-instructions.md # 命令階層とテンプレート
    ├── provider-api-patterns.md       # OpenAI・Anthropic・互換API
    ├── security-evals-observability.md # ガードレール・トレーシング・評価
    ├── agent-legibility-feedback-loops.md # 正典アーティファクトとクリーンアップ
    ├── checklists.md                  # 実装・監査チェックリスト
    ├── coverage-audit.md              # トピックカバレッジ検証
    └── source-links.md                # 公式参照リンク集

SKILL.md をエントリーポイントとし、Claude Code・Codex・その他のAgent Skill対応ランタイムが会話コンテキストに応じて関連ファイルを選択的にロードする設計だ。

設計哲学——8つのコア原則

agents-best-practicesの根幹を成す8つの原則を解説する。これらはREADMEのPhilosophyセクションに記載され、全リファレンスファイルがこの原則に従って設計されている。

8つのコア原則

  1. ハーネスが実行し、モデルは提案する — アプリケーションコードが検証・認可・実行・記録を担う
  2. 全ツール呼び出しには結果が必要 — 拒否・タイムアウト・不正引数・中断も観察結果として扱う
  3. リスクによってループが変わる — 読み取り・下書き・書き込み・外部通信・財務・破壊的操作は異なる権限パスを要する
  4. 下書きとコミットは別 — 高リスクな副作用にはプロンプト外に承認記録が必要
  5. コンテキストは構築するもの — 必要最小限を取得し、信頼境界を明示し、コンパクション後もアクティブ状態を保持する
  6. 長期実行作業にはバジェットが必要 — ステップ・時間・トークン・コスト・ツール呼び出し数のバジェットは製品機能の一部
  7. スキルとコネクターは段階的に開示する — まず名前と説明を開示し、詳細ワークフローは関連するときのみロード
  8. 繰り返す失敗はハーネス機能にする — バリデーター・ツール・ドキュメント・評価・ポリシーがプロンプトの繰り返し指示に勝る

特に重要なのは原則8だ。「プロンプトに同じことを何度も書いても解決しない。それはハーネスで実装すべき問題だ」という主張は、多くの開発者がプロンプトエンジニアリングで消耗した後に気づく真実を先取りしている。

エージェントハーネスのアーキテクチャ——15コンポーネントモデル

agents-best-practicesが定義するハーネスアーキテクチャは15のコンポーネントで構成される。

自律実行

承認必要

拒否

ユーザー/タスク

Instruction Manager

Context Builder

Model Adapter

Tool Registry

Permission Engine

承認判定

Execution Engine

Approval Manager

Denied Result

State Store

Memory and Retrieval Layer

Compactor

Planner and Goal Controller

Trace and Evaluation System

最終回答

ハーネス境界の原則

ハーネスが所有すべき要素と、サンドボックスや外部実行に委ねるべき要素は明確に分離される:

ハーネスが所有するもの

  • ユーザーIDとテナント境界
  • クレデンシャル管理
  • 承認記録
  • 監査ログ
  • 課金とレート制限
  • ツール認可
  • 外部システムへの最終コミット

サンドボックス/外部実行が所有するもの

  • 一時ファイル
  • 生成されたアーティファクト
  • スクリプト実行
  • 分離されたブラウザ・シェル作業
重要: シークレット・承認ロジック・認可決定をモデルプロンプトやモデルが変更できるサンドボックスの内部に置いてはならない。

権限階層

プロバイダ/システムポリシー
  └── 組織/開発者ポリシー
        └── ワークスペース/プロジェクトポリシー
              └── エージェントロールポリシー
                    └── タスク固有の指示
                          └── ユーザーリクエスト(最低権限)

上位階層のポリシーが下位を上書きする。ユーザーのリクエストは最低権限しか持たないことがハーネス設計の基本だ。

プロバイダ中立エージェントループ——不変条件と実装

references/agentic-loop.md が定義するループの正規形は以下の通りだ:

while not done:
  コンテキストを構築
  可視ツールでモデルを呼び出し
  最終回答またはツールリクエストを受信
  全ツールリクエストを検証
  権限と承認ポリシーをチェック
  各ツールリクエストを実行または拒否
  構造化ツール結果を追加
  必要ならコンテキストをコンパクト/取得
  完了またはバジェット超過で停止

このループには7つの不変条件がある:

  1. 全ツール呼び出しは対応する結果を正確に1つ受け取る
  2. ツール引数は実行前に解析・検証される
  3. 全副作用の前に権限決定が行われる
  4. ツール結果は有界・構造化・追跡可能
  5. ループはステップ数・時間・トークン数・コスト・ツール呼び出し数のハードバジェットを持つ
  6. 最終回答は観察結果に基づく(ツール成功の仮定ではない)
  7. エラー・拒否・キャンセル・タイムアウトは構造化された観察として扱われる

実装疑似コード

def run_agent(task, session):
    session.add_user_message(task)

    for step in range(session.max_steps):
        context = context_builder.build(session)

        if budget.exceeded(session):
            return stop("budget_exceeded", session)

        if compactor.should_compact(context, session):
            session = compactor.compact(session)
            context = context_builder.build(session)

        output = model.generate(
            context=context,
            tools=tool_registry.visible_tools(session),
        )
        session.record_model_output(output)

        if output.final_answer:
            return finalize(output.final_answer, session)

        for call in scheduler.order(output.tool_calls):
            result = handle_tool_call(call, session)
            session.add_tool_result(call.id, result)

    return stop("step_limit_reached", session)

def handle_tool_call(call, session):
    tool = tool_registry.get(call.name)
    if tool is None:
        return error_result("unknown_tool", call.name)

    try:
        args = tool.validate(call.arguments)
    except ValidationError as exc:
        return error_result("invalid_arguments", str(exc))

    decision = permission_engine.evaluate(tool, args, session)

    if decision.type == "deny":
        return denied_result(decision.reason)

    if decision.type == "approval_required":
        return pause_for_approval(call, decision, session)

    return tool.execute(args)

全ての分岐が結果を返す点に注目してほしい。ツールが存在しない場合も、引数が無効な場合も、承認が必要な場合も、拒否された場合も——すべてが観察結果としてセッションに記録される。

ツール設計とリスク分類——14カテゴリの権限マトリクス

agents-best-practicesのツール設計で最も価値があるのが、14カテゴリのリスク分類体系だ。

ツール設計の原則

良いツールと悪いツールの対比:

悪いツール(広すぎる):
  execute_anything(command)
  call_api(url, method, body)
  update_database(sql)
  send_message(payload)

良いツール(ドメインセマンティクスを持つ):
  search_policy_docs(query, max_results)
  read_customer_account(account_id)
  draft_customer_email(case_id, tone)
  request_refund_approval(order_id, amount, reason)
  apply_approved_refund(approval_id)

広いツールはモデルに過剰な権限を与えるだけでなく、何が起きたかを追跡できなくする。ドメインセマンティクスを持つ狭いツールが正しいアプローチだ。

14カテゴリリスク分類

リスクカテゴリ 説明 デフォルト権限
read_only データの読み取りのみ 自律実行OK
search_only 検索クエリのみ 自律実行OK
compute_only ローカル計算のみ 自律実行OK
draft_only 下書き生成(コミットなし) 自律実行OK
write_local ローカルファイル書き込み スコープ付き自律実行
write_internal 内部システムへの書き込み 承認推奨
write_external 外部システムへの書き込み 承認必須
financial 財務トランザクション 承認必須
communication 外部通信(メール・Slack等) 承認必須
identity_access ID・アクセス変更 承認必須
security_sensitive セキュリティ設定変更 承認必須
process_execution プロセス・コマンド実行 サンドボックス必須
network_open_world 任意のネットワークアクセス 強い制限が必要
destructive 削除・不可逆操作 明示的承認必須
privileged_admin 管理者権限操作 最高レベル承認必須

ツールスキーマの設計ルール

{
  "type": "object",
  "properties": {
    "record_id": { "type": "string" },
    "new_status": {
      "type": "string",
      "enum": ["open", "pending", "resolved"]
    },
    "reason": { "type": "string" }
  },
  "required": ["record_id", "new_status", "reason"],
  "additionalProperties": false
}
  • 厳格なJSONスキーマを使用
  • 必須フィールドを明示
  • 未知のプロパティを拒否
  • 制約されたアクションにはenumを使用
  • 自由形式の指示ではなくIDと型付きフィールドを優先

MVPブループリント——Level 0〜4の自律度

references/mvp-agent-blueprint.md はエージェントのMVP設計手法を体系化している。最小の自律度から始めることが推奨される。

5段階の自律度モデル

Level 0: Answer-only(回答のみ) コンテキストを読んで回答する。取得と要約以外のアクションなし。

Level 1: Draft-only(下書きのみ) 推奨事項・メッセージ・レポート・計画・更新を下書き。変更は人間がすべてコミット。

Level 2: Approval-gated action(承認ゲート付きアクション) エージェントがアクションを提案し、副作用の前に承認のために一時停止。ほとんどのビジネスエージェントの推奨デフォルト。

Level 3: Policy-bounded autonomous action(ポリシー制限付き自律アクション) エージェントが明示的なポリシー内の低リスクアクションを実行可能。強力なログ・評価・ロールバックパスが必要。

Level 4: Long-running autonomous objective(長期自律目標) エージェントがチェックポイントとバジェットをまたいで測定可能なゴールを追求。基本ハーネスが信頼できることを確認した後のみ使用。

ほとんどのMVPはLevel 1またはLevel 2から開始すること。Level 4はベースハーネスが本番証明された後にのみ検討する。

ドメイン別MVPの例:アカウント更新リスクエージェント

READMEには営業ドメインのMVP例が示されている:

コアループ:
  ユーザー/タスク -> コンテキストビルダー -> モデル呼び出し
  -> 型付きツール呼び出し -> スキーマ検証 -> 権限チェック
  -> 実行または一時停止 -> 構造化された観察 -> 次ステップまたは最終ブリーフ

最小ツールセット:
  - read_account_profile       (read_private_data)
  - list_support_tickets       (read_private_data)
  - fetch_usage_summary        (read_private_data)
  - draft_customer_email       (draft_external_message)
  - request_approval           (approval_gate)

ローンチゲート:
  - 過去20アカウントでのトレース確認
  - 未承認の外部送信ゼロ
  - 少なくとも80%の下書きアクションで人間が受け入れ

コンテキスト管理とオートコンパクション

長期実行エージェントでもっとも軽視されがちな設計がコンテキスト管理だ。references/context-memory-compaction.md はその体系的な設計手法を提供する。

コンテキストの黄金律

“The best context is not the largest context. It is the smallest context that lets the model choose the correct next action.”

最良のコンテキストは最大のコンテキストではない。モデルが次の正しいアクションを選択できる最小のコンテキストだ。

10層コンテキスト構造

1. プロバイダ/システムポリシー
2. 組織/開発者ポリシー
3. エージェントロールと運用契約
4. アクティブなユーザータスク
5. アクティブな計画またはゴール
6. スコープ付き指示とメモリ
7. 関連する取得データ
8. 可視スキルインデックス
9. 可視ツール仕様
10. 最近のツール観察

信頼された指示と信頼されていないデータを、ラベルなしで混在させてはならない。

メモリカテゴリの分離

ユーザー設定        -> フォーマットの調整は可
組織ポリシー        -> セキュリティポリシーの上書きは不可
プロジェクト規約    -> スコープ付き適用
アクティブセッション状態 -> コンパクション後に再水和
アーティファクト参照 -> プロンプト外に保存
長期サマリー        -> コンパクション後も保持
承認記録            -> プロンプト外に永続化

オートコンパクションの設計

コンパクション後に失われてはならないもの:

  • アクティブな計画とゴール
  • 承認記録と結果
  • TODOリストと完了済みチェックポイント
  • アーティファクト参照
  • アクティブなサンドボックスと接続

コンパクションはチャット履歴ではなくアクティブな状態を再水和する。この区別がハーネスの長期安定性を決定する。

セキュリティ・評価・可観測性——多層防御の設計

脅威モデル:16の脅威カテゴリ

エージェントの脅威は言語・ツール・外部データの組み合わせから生じる:

プロンプトインジェクション、悪意ある取得コンテンツ
ツール誤用、権限バイパス、シークレット漏洩
データ流出、安全でない外部通信
財務・破壊的副作用、コネクター悪用
悪意あるスキルパッケージ、暴走ループ
コスト枯渇、虚偽の成功主張
コンパクション状態損失、サブエージェント誤協調

7層ガードレール

  1. 入力ガードレール: 安全でないユーザーリクエストを拒否またはルーティング
  2. コンテキストガードレール: 信頼されていないコンテンツをラベル付けしシークレットを削除
  3. スキーマガードレール: 構造化されたツール引数と出力を強制
  4. ツールガードレール: 実行前後に引数と結果を検証
  5. 権限ガードレール: アクションを承認・拒否・一時停止
  6. 出力ガードレール: ユーザー可視出力の前に最終回答をチェック
  7. トレースガードレール: 実行後にツール呼び出しと決定を採点

承認記録の形式

{
  "approval_type": "external_send",
  "action": "send_email",
  "target": "customer@example.com",
  "risk": "external_communication",
  "preview_ref": "artifact://drafts/email_123",
  "expected_result": "顧客が更新リマインダーを受け取る",
  "rollback": "送信取り消し不可。フォローアップ修正は可能",
  "scope": "single_send_only"
}

承認記録はプロンプトの外部に永続化する。プロンプトに入れると、コンパクション時に失われる危険がある。

プロンプトインジェクション対策

外部コンテンツは指示ではなくデータとして扱う:

  • 外部コンテンツがツールを直接選択しないようにする
  • シークレットをコンテキストにコピーしない
  • 任意のテキストに影響されるアクションには承認を要求
  • ツール呼び出しに使用されたデータのソースをログに記録

スキルとコネクター——MCPとAgent Skillsの統合

スキルの段階的開示原則

スキルとコネクターの管理で最重要なのは「段階的開示」だ:

  1. まず名前と説明だけを開示(コンテキスト負荷を最小化)
  2. ユーザーのリクエストが関連ドメインに触れたときのみ詳細ワークフローをロード
  3. 使用後はスキルコンテキストをアンロード

これにより、多数のスキルを登録してもコンテキストウィンドウを圧迫しない。

MCPサーバーガバナンス

MCPサーバーの統合には信頼評価が必要だ:

評価項目:
  - ソースの信頼性(公式・コミュニティ・未知)
  - スコープ(必要最小限のツールのみ)
  - 認証方式(APIキー・OAuth・なし)
  - データ保持ポリシー
  - レート制限と課金影響

MCP(Model Context Protocol)サーバー構築ガイド を参照すると、MCPサーバーの設計原則をより深く理解できる。

インストールと実際の使い方

インストール方法

方法A: skills CLIを使う(最も簡単)

npx skills add DenisSergeevitch/agents-best-practices -g

-g フラグでユーザーレベルにグローバルインストールし、全プロジェクトから参照可能になる。

方法B: 手動インストール

# Claude Code(ユーザーレベル)
mkdir -p "$HOME/.claude/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  "$HOME/.claude/skills/agents-best-practices"

# Codex
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  "${CODEX_HOME:-$HOME/.codex}/skills/agents-best-practices"

# プロジェクトレベル(Claude Code)
mkdir -p .claude/skills
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  .claude/skills/agents-best-practices

3つの主要ユースケース

ユースケース1: MVPエージェントブループリントの生成

あなた > 顧客更新リスクエージェントを作りたい。CRM・
         サポートチケット・利用データを読んで更新アクションを下書きしたい。

エージェント > Level 2ハーネス(承認ゲート付き)から開始します。
              最小ツールセット...
              ローンチゲート...

references/mvp-agent-blueprint.md が詳細な生成手順を提供する。

ユースケース2: 既存ハーネスの監査

「エージェントが無限ループに陥る」「コンパクション後に判断の根拠を忘れる」といった問題をハーネスレベルで分析し、修正優先順位を提示する。

ユースケース3: ツール・権限・コネクターの設計

Slack・Linear・Google Drive・内部APIなどへのアクセスを、リスク分類に基づいて適切な権限レベルで設計する。

既存フレームワークとの比較

agents-best-practicesは既存のエージェントフレームワークとは異なる位置づけだ。

比較項目 agents-best-practices LangGraph AutoGen CrewAI
形式 Agent Skill(Markdown) Pythonフレームワーク Pythonフレームワーク Pythonフレームワーク
プロバイダ依存 なし(中立) LLM非依存 OpenAI優先 OpenAI優先
インストール git clone / npx pip install pip install pip install
対象 設計・監査・生成 実装 実装 実装
マルチエージェント 設計ガイド提供 ネイティブ対応 ネイティブ対応 ネイティブ対応
スコープ コーディング以外も含む 汎用 汎用 タスク委譲
ライセンス MIT MIT MIT MIT

補完的な関係:agents-best-practicesはLangGraph・AutoGen・CrewAIなどの実装フレームワークと競合しない。むしろ「どう設計するか」の指針を提供し、実装は既存フレームワークで行うという使い方が想定されている。

プロンプトキャッシュとコスト最適化

長期実行エージェントのコスト管理は見落とされがちだ。references/prompt-caching-and-cost.md は以下の原則を提供する:

安定プレフィックスの設計

最も安定(キャッシュされやすい)→ 最も変動する順に並べる:
  1. システムポリシーと基本指示
  2. エージェントロールと運用契約
  3. ドメイン知識とFAQ
  4. ツール仕様
  5. メモリと取得データ
  6. アクティブコンテキスト(頻繁に変化)

Anthropic APIのプロンプトキャッシュでは、上位の安定コンテンツがキャッシュヒットし、変動部分のみを毎回送信することでコストを最大90%削減できる。

バジェット管理のコード例

class AgentBudget:
    def __init__(self, max_steps=50, max_tokens=100000,
                 max_cost_usd=5.0, max_duration_sec=300):
        self.max_steps = max_steps
        self.max_tokens = max_tokens
        self.max_cost_usd = max_cost_usd
        self.max_duration_sec = max_duration_sec
        self.start_time = time.time()

    def exceeded(self, session) -> bool:
        return (
            session.step_count >= self.max_steps or
            session.total_tokens >= self.max_tokens or
            session.estimated_cost >= self.max_cost_usd or
            (time.time() - self.start_time) >= self.max_duration_sec
        )

    def remaining(self, session) -> dict:
        return {
            "steps": self.max_steps - session.step_count,
            "tokens": self.max_tokens - session.total_tokens,
            "cost_usd": self.max_cost_usd - session.estimated_cost,
        }

ローンチチェックリストと本番移行基準

agents-best-practicesのreferences/checklists.mdは実装チェックリストと監査チェックリストを提供する。

ローンチゲートの基準例

Level 2エージェントのローンチゲート:
  □ 過去N件の代表的タスクでトレース確認
  □ 承認フローが機能することを確認
  □ 外部送信がゼロ(承認なし)
  □ バジェット超過時の停止動作を確認
  □ コンパクション後のアクティブ状態再水和を確認
  □ 意図しない副作用の記録がない
  □ 人間による80%以上の下書き受け入れ率

Level 3以上の追加要件:
  □ ロールバックパスのテスト
  □ 評価スイートでのインジェクション耐性確認
  □ コスト・トークン telemetry のダッシュボード整備
  □ インシデント対応手順書の作成

agents-best-practicesが変える設計の視点

このリポジトリが示す最も重要なメッセージは、エージェント開発における責任の明確化だ。

従来のアプローチでは「モデルに賢くなってもらう」ためにプロンプトを磨き続けた。agents-best-practicesは「ハーネスを正しく設計する」ことへの転換を求める。

モデルへの過度な期待から、ハーネスへの適切な設計投資へ——この視点の転換こそが、AIエージェントを本番品質に引き上げる鍵だ。

2026年のエージェント設計の「教科書」として、agents-best-practicesは間違いなく参照すべきリソースになるだろう。

まとめ: agents-best-practicesの核心

  • プロバイダ中立なAgent Skillとして設計され、Claude Code・Codex両方で動作
  • 8つのコア原則がハーネス設計の哲学を定義
  • 14カテゴリのリスク分類と権限マトリクスでツール設計を体系化
  • Level 0〜4の自律度モデルでMVPの出発点を明確化
  • 7層ガードレールとプロンプトインジェクション対策で多層防御を実現
  • コンテキスト管理・コンパクション設計が長期実行の安定性を保証

参照ソース