agents-best-practices完全解説｜プロバイダ中立のエージェントハーネス設計8原則とMVP構築ガイド

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

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

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

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

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

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

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

コーディングエージェントだけを対象にしていない点が特徴だ。リポジトリの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だ。「プロンプトに同じことを何度も書いても解決しない。それはハーネスで実装すべき問題だ」という主張は、多くの開発者がプロンプトエンジニアリングで消耗した後に気づく真実を先取りしている。

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

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

ハーネス境界の原則

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

ハーネスが所有するもの

• ユーザー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カテゴリリスク分類

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

{
  "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段階の自律度モデル

ドメイン別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層ガードレール

承認記録の形式

{
  "approval_type": "external_send",
  "action": "send_email",
  "target": "[email protected]",
  "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などの実装フレームワークと競合しない。むしろ「どう設計するか」の指針を提供し、実装は既存フレームワークで行うという使い方が想定されている。

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

長期実行エージェントのコスト管理は見落とされがちだ。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 — GitHub — 本記事のベースとなる公式リポジトリ
• Agent Skills specification — agentskills.io — Agent Skillの仕様書
• Anthropic Agent and MCP Documentation — Claude Code・MCPの公式ドキュメント