agents-best-practices

Name: agents-best-practices
Author: denissergeevitch

github.com/denissergeevitchエージェントワークフロー2.4k1.0k 回インストール1 週間前に更新

リポジトリ

agents-best-practices について

Agents Best Practicesは、さまざまな分野のエージェントハーネスを設計、構築、デバッグ、評価する人向けのスキルです。MVPの設計図からトラブルシューティング、デプロイ時の検討事項まで、課題別の指針を提供します。

主な機能

01エージェントハーネスの設計指針
02ドメイン別エージェントのMVP設計モード
03ランタイムの重点的なトラブルシューティング
04音声および永続ランタイム向けモード
05ハードウェアと適応型ツールの指針

活用シーン

01安全な初期エージェントハーネスの設計
02停止または失敗した実行の診断
03ボードへのエージェント導入計画
04ツール、権限、ワークフローの評価

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/denissergeevitch/agents-best-practices --skill agents-best-practices

インストール後、Claude Code で/agents-best-practicesを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

LICENSE

.gitignore

README.md

references/

adaptive-agent-teams.md

agent-legibility-feedback-loops.md

architecture.md

agentic-loop.md

coding-agents.md

always-on-agents.md

checklists.md

coverage-audit.md

context-memory-compaction.md

realtime-voice-agents.md

planning-and-goals.md

provider-api-patterns.md

mvp-agent-blueprint.md

prompt-caching-and-cost.md

evals.md

environment-adaptive-tools.md

hardware-agents.md

security-observability.md

self-refining-recursive-harnesses.md

skills-and-connectors.md

speculative-tool-execution.md

system-prompts-instructions.md

tools-and-permissions.md

workflow-orchestration.md

source-links.md

詳細

エージェントのベストプラクティス

ユーザーから、エージェント型ハーネスの構築、改善、デバッグ、評価について尋ねられた場合は、このスキルを使用します。これは汎用的なエージェントアーキテクチャのスキルです。コーディングエージェントはその一分野にすぎません。研究、金融、法律、サポート、運用、営業、医療、教育、データ分析、調達、ワークフロー自動化のエージェントにも、同じ原則を適用してください。

基本方針

エージェントハーネスは、モデルを取り巻く制御プレーンです。モデルがアクションを提案し、ハーネスがそれを検証、認可、実行、記録、要約し、観測結果を返します。ループはシンプルに保ち、ランタイムは厳格に管理してください。

デフォルトのアーキテクチャ：

user/task
  -> instruction and context builder
  -> model call
  -> tool/action proposal
  -> schema validation
  -> permission decision
  -> execution or approval pause
  -> structured observation
  -> context update
  -> repeat within budget or finish

このスキルを有効にするタイミング

次のいずれかの意図を含むプロンプトには、このスキルを使用してください。

エージェント、エージェント型ワークフロー、AI ワーカー、自律型アシスタント、またはハーネスを構築する；
特定ドメイン向けの MVP エージェント設計、スターターハーネス、実装の設計図、または初期の本番環境対応版を作成する；
OpenAI、Anthropic、OpenAI 互換 API、直接的なツールループ、ホスト型ツール、または SDK のいずれかを選択する；
セッション内でモデルリクエストをルーティングする、指示やツール設定の変更を再生する、または有料のキャッシュウォーミングを評価する；
生成状態にテキスト以外の潜在位置が含まれ、テキストのトランスクリプトだけでは再構築できないバックエンドを統合または評価する；
ツール、権限、ガードレール、承認フロー、またはサンドボックス化を設計する；
エージェントがレンダリングするインターフェース、来歴の記録、累積的な業務上限、またはユーザーメモリのライフサイクルを設計する；
能力の発見、安全な探索、実行時バインディング、スキーマ検証、またはドリフトによる無効化を用いて、部分的にしか分かっていない環境や変化する環境向けのエージェントを設計する；
投機的実行、部分プログラム解析、フューチャー、厳密なクレームセマンティクス、または未使用処理のキャンセルによって、コードモードやプログラムによるツールのレイテンシを低減する；
計画モード、ワークフローオーケストレーション、目標モード、ToDo の追跡、または長時間実行されるタスクの振る舞いを作成する；
常時稼働のエージェントサービスや、入力受理レシート、タスクの所有権、アプリケーション状態、再起動からの復旧、再接続するオブザーバー、または定期的な情報源の収集と配信の記録管理を備えた永続的なセッションを構築する；
異なるアプローチ、共有される作業状況の把握、調査結果の交換、またはエビデンスに基づく再割り当てを行う、協調するエージェントチームを設計する；
コンテキストの圧縮、メモリ、検索、スコープ付き指示、またはプロンプト階層を追加する；
再帰的言語モデル（RLM）、プログラム可能なコンテキストランタイム、自己改良型または継続型のハーネス、タスクローカルなハーネス検索、保持される子エージェント、または実行可能なスキルを設計する；
ハードウェア／組み込みエージェントを構築またはインストールする、エージェントをボードにフラッシュする、更新中にデバイスの識別情報を保持する、またはリソースやウェイク動作をデバッグする；
音声エージェント、音声パイプライン、リアルタイムのターン交替、割り込み、再生、またはツール処理中の訂正を設計またはデバッグする；
Agent Skills、再利用可能なワークフロー、MCP サーバー、外部コネクター、またはツール検索を接続する；
公開ボードを介したエージェントの通信を、公開対象の明示的な開示、ユーザー承認、送信データ制御とともに設計する；
既存のエージェントの信頼性、コスト、プロンプトキャッシュヒット率、安全性、レイテンシ、または可観測性を監査する；
検証済みのベンチマーク代理指標、本番環境での受け入れ、回帰を防ぐ仕組みを用いて、測定されたハーネスまたはアプリケーションのパフォーマンスを改善する；
部分ストリーム、停止したターン、再起動とキャンセルの競合状態、重複アクション、コンテキスト計上の誤り、またはテレメトリの過負荷をトラブルシューティングする；
特定ドメイン向けエージェントのシステムプロンプトや開発者向け指示を作成する；
信頼できる情報源となる知識、検証シグナル、ログ、メトリクス、またはワークフロー状態を、エージェントが理解できるようにする。

ユーザーがこうしたタスクを実行するエージェントの設計について尋ねている場合を除き、通常の単一ターンの執筆、翻訳、または質疑応答にはこのスキルを使用しないでください。

このスキルの使い方

まず、ユーザーの設計上の課題を特定します。

ドメイン：エージェントが行う作業。
自律性のレベル：回答のみ、下書きのみ、承認を条件とするアクション、またはポリシーの範囲内での自律的なアクション。
リスクレベル：読み取り専用、内部への書き込み、外部への通信、金融、法律、医療、セキュリティ、破壊的、または特権的。
状態の継続期間：単一ターン、複数ターンのセッション、再開可能なワークフロー、または長期的な目標。
ツールの範囲：内部 API、ホスト型ツール、MCP／外部コネクター、ブラウザー、サンドボックス、ファイルシステム、データベース、通信、または計算。
検証：タスクが完了したことを証明するもの。

次に、関連性が最も高いリファレンスファイルを読み込みます。デフォルトですべてのファイルを読み込まないでください。ユーザーが特定ドメイン向けのエージェントの作成や構築を求めている場合は、デフォルトで MVP ビルダーモードを使用してください。

MVP ビルダーモード

ユーザーが特定の分野向けのエージェントを作成、構築、設計、ひな形作成、または仕様化するよう求めた場合は、助言だけでなく、その分野に特化した具体的な MVP ハーネスの設計図を提示します。主要な参考資料として mvp-agent-blueprint.md を使用し、必要に応じて他の参考資料も読み込みます。

デフォルトの動作：

ユーザーの分野と明示された制約から、妥当な初期バージョンを推定します。
詳細が不足していても作業を止めず、前提を簡潔に述べます。
有用な作業を実行できる、最小限かつ安全なハーネスを設計します。
エージェントの基本ループ、ツールレジストリ、権限マトリクス、コンテキスト／メモリ／圧縮、計画モード、目標に基づくループ条件、スキル／コネクター、プロンプトキャッシュ／コスト戦略、可観測性、評価、リリースまでの道筋を含めます。
高リスクな操作は、デフォルトでドラフトのみ、または承認必須とします。
ユーザーがより広範なアーキテクチャを明示的に求めない限り、信頼性を確保できる最小限の単一ループハーネスに MVP をとどめます。

トラブルシューティングモード

ユーザーが実行失敗やランタイムの症状を提示した場合は、まずトラブルシューティングを参照し、必要に応じて関連する仕組みの担当資料を読み込みます。症状、最も早い段階での失敗境界、観測された証拠と仮説の区別、原因を絞り込む一つのプローブ、最小限の修正、回帰テストを提示します。不足している証拠は明示し、アーキテクチャ全体の設計図ではなく、対象を絞った診断の引き継ぎを行います。高度なコンポーネントの調査は、失敗したデプロイでそれらが使われている場合に限ります。

ハードウェアおよびボードへのデプロイモード

物理ボード上でエージェントを実行する、ファームウェア／アプリをインストールする、またはデバイスのランタイムをデバッグする場合は、このモードを使用します。インストーラーを選ぶ前に hardware-agents.md を読みます。ボード／ランタイムの識別情報、推論の実行場所、実際の起動／ランチャー／パーティション経路、リソースの余裕、保持される状態、復旧手段を確認します。ファイルシステム上のアプリであれば、ベースファームウェアの再書き込みが不要な場合があります。既存エージェントのインストールやデバッグでは、MVP 全体の設計図や無関係なワークフロー／サブエージェント／コネクターの設計ではなく、対象／インストール／保持／検証に絞った引き継ぎを行います。エージェントのアーキテクチャ自体を作成する場合は、設計図を使用します。

デプロイ権限は、ランタイムのツール権限や公開投稿の権限と分離します。デフォルトでは読み取り専用のサイクルを 1 回だけとし、継続的な自律動作やプログラム可能なツール／物理ツールは、要求がない限り MVP 後の対象とします。インストールの引き継ぎには、測定済みの対象、固定されたアーティファクト、書き込み境界、保持／ロールバック計画、実機でのコミッショニング証拠を明記します。アップロードの成功やホストに依存するエミュレーターを、デバイス単体の正常性と同一視してはいけません。

環境適応型ツールモード

有用なツールカタログ、スキーマ、バージョン、実装が、実行前に完全設定されているのではなく、実行時に決まる場合は、このモードを使用します。environment-adaptive-tools.md を、標準のツール、コネクター、セキュリティ、評価に関する参考資料とあわせて読みます。

小規模で信頼できるブートストラップインターフェース、ホストが管理する機能台帳、来歴ラベル付きの記述子、範囲を限定した読み取り専用または隔離されたプローブ、不透明なスコープ／バージョンのバインディング、呼び出し時の権限チェック、ドリフト時の無効化を必須とします。検出、生成されたコード、推定されたスキーマによって権限を付与してはいけません。変化する環境への適応が製品の主要な役割でない限り、これは MVP 後の対象とします。主要な役割である場合でも、まず固定された読み取り専用のベースラインを確立します。

リアルタイム音声エージェントモード

音声でのやり取りについては、ツールおよび評価の担当者とともにrealtime-voice-agents.mdを確認してください。新しい音声エージェントにはMVPビルダーモードと併用し、既存の音声障害にはトラブルシューティングモードと併用してください。音声機能自体をMVPにすることもできます。選択したアーキテクチャで必要とされない限り、バックエンドの独立したオーケストレーションや永続的な復旧は必須ではありません。

メディアのトポロジー、やり取りとターンのポリシー、実行場所、入力と再生の証拠、中断後の修復、訂正と結果の鮮度、音声とタスクそれぞれの受け入れ基準を提示してください。既存の権限とタスクの契約を再利用してください。音声による中断で作業がキャンセルされるとは限りません。また、音声機能があるからといって、推論の水準を下げてよいとは限りません。

常時稼働エージェントと永続的なランタイムモード

ユーザーが常時稼働するサービス、復旧可能なセッション、作業中に受け付ける入力、永続的なタスクやアプリケーションの状態、または監視者の再接続を求める場合は、このモードを使用してください。ループ、ツール、コンテキスト、セキュリティ、評価の担当者とともにalways-on-agents.mdを確認してください。このモードはMVPの後に扱います。まず、より単純なリクエスト単位または再開可能なベースラインを測定してください。可用性、永続性、推論の実行、権限はそれぞれ別の選択肢です。通常の常時稼働に、再帰や自己改善は必要ありません。

受け入れとコミットの境界、入力と制御のレーン、所有するタスクのライフサイクル、ドキュメントのスコープとフォークのポリシー、監視と再接続の契約、常駐の所有権、復旧、集約された制限を提示してください。既存の目標、権限、コンパクション、子プロセスのプロトコルを再利用してください。永続的な送信レシートやアイドル状態での生成は、作業が完了した証拠にはなりません。

定期的な監視では、ソースごとの進捗、明示的なカバレッジの欠落、レシートに裏付けられた配信状態について、収集と配信の契約を使用してください。

高度な再帰型・継続型ハーネスモード

ユーザーがプログラム可能なコンテキスト、再帰的な実行、子エージェントの保持、継続的な改善、タスク単位のハーネス検索、または実行可能なスキルを明示的に求める場合に限り、このモードを使用してください。このモードはMVPの後に扱います。まず測定済みの単一ループのベースラインを確立してから、コンテキスト、ワークフロー、権限、セキュリティ、評価に関するリファレンスと併せてself-refining-recursive-harnesses.mdを確認してください。常駐稼働またはスケジュールに基づく再実行だけが必要な場合は、常時稼働エージェントと永続的なランタイムモードを使用してください。

コンテキストの表現、再帰単位、変更可能な状態、昇格のスコープ、ライフサイクル、予算、検証プローブ、ロールバック経路を明確にしてください。基本権限、権限の適用、認証情報、予算、評価ポリシーは、変更可能な領域の外に置いてください。

タスク単位のハーネス検索では、タスク単位の対照的な改善と、その評価を使用してください。これは、プログラム可能なコンテキストや再帰的な子エージェントがなくても実行できます。行動上の証拠と、検証済みの正しさ、より広い範囲への昇格とを区別してください。

適応型エージェントチームモード

ユーザーが、異なるアプローチを検討し、証拠の蓄積に応じて担当を変更するチームでの協業を求めた場合に、このモードを使用します。MVP 後の段階に限定してください。まず、単一エージェントと通常の並列ワーカーのベースラインを測定して確立し、その後、ワークフロー、再帰的なライフサイクル、目標、評価の各担当者とともに adaptive-agent-teams.md を読みます。

アプローチのポートフォリオ、作業の重複に関するポリシー、通信の依存関係、証拠に基づく移行、ホスト側の権限、合算予算、受け入れの証拠を提示してください。プロファイルの契約と既存の担当者を使用し、そのマニュアルを繰り返さないでください。これはアーキテクチャの組み合わせとして扱ってください。公開された規模や成果だけでは、モデルの変更や一般的な性能向上を示すことにはなりません。定型的な検索タスクには、引き続き単一ループの MVP を使用します。

実験的な投機的ツール実行モード

生成されたプログラムやアクションが完成する前にツール作業を開始してレイテンシを削減するようユーザーが明示的に求めた場合に限り、このモードを使用します。まず、逐次実行と通常の確定済み並列実行のベースラインを測定して確立し、その後、ループ、ツール、セキュリティ、評価の各リファレンスとともに speculative-tool-execution.md を読みます。

ホスト側が管理する適格性、実際のディスパッチ時点での権限確認、隔離された使い捨て状態、厳密にバージョン管理されたクレーム識別情報、確率的呼び出しへの出現単位での安全な対応、廃棄とコストの個別予算、キャンセルの確認に基づく計上、タスク同等性の評価を必須とします。モデル出力が部分的な状態では、権限は一切付与されません。また、リスクの高い副作用や承認を必要とする副作用を投機的に実行してはなりません。

リファレンスマップ

ユーザーから新しいドメイン特化型エージェントまたはMVPハーネスの作成を依頼された場合は、まず mvp-agent-blueprint.md を読んでください。
依頼されたエージェントがソフトウェアリポジトリに対して読み取り、編集、テスト、レビュー、移行、変更のオープンを行う場合は、測定に基づくMVP後のアクションインターフェース選択も含めて、coding-agents.md を読んでください。
組み込み環境での実行場所、ランチャーとファームウェアのどちらにインストールするか、リソース制約のあるトランスポート、リセットに安全な状態、ウェイク動作、ロールバック、物理的なコミッショニングについては、hardware-agents.md を読んでください。
メディア／ターン／再生のライフサイクル、中断からの復旧、継続的な入力の証拠、音声／実行ブリッジ、訂正情報の鮮度、音声固有の受け入れ基準については、realtime-voice-agents.md を読んでください。
ハーネスの完全なモデル、コンポーネントの境界、信頼されたランタイム指示／ツール設定イベントについては、architecture.md を読んでください。
MVP後のサービス可用性と永続性の境界、ローカルでのアトミックな公開、受け入れる入力／制御レーン、所有するタスク、アプリケーション文書／フォーク、オブザーバーの収束、常駐プロセスの所有権、復旧、定期的な収集／配信の記録については、always-on-agents.md を読んでください。
信頼できる情報源となるナレッジベース、エージェントが理解しやすい環境、検証ループ、機械的な不変条件、定期的なクリーンアップについては、agent-legibility-feedback-loops.md を読んでください。
プロバイダーに依存しないループ、ステップ予算、再試行、ループのバリエーション、MVP後のリクエストごとのモデルルーティングについては、agentic-loop.md を読んでください。
高度なコードモードまたはプログラマティックツールのハーネスで、生成中に対象となる作業を先行起動しつつ、完了したプログラムの権限と出現箇所を考慮した要求管理を維持する場合は、speculative-tool-execution.md を読んでください。
ツールの契約、記録の来歴、提示の受領記録、結果状態の制限、承認ロジック、構造化された結果、サンドボックス化については、tools-and-permissions.md を読んでください。
ツール環境が部分的にしか判明していない、または実行時に変化し、初期探索、スキーマ検証、安全なプロービング、厳密なバインド、ドリフトへの対処が必要な場合は、environment-adaptive-tools.md を読んでください。
コンテキストの組み立て、ユーザーメモリのライフサイクルとソースの適格性、階層的な検索、要約前の段階的な省略、過去の出力を任意で想起する方法、引き継ぎの保持については、context-memory-compaction.md を読んでください。
安定したプレフィックスの設計、キャッシュを考慮したコンテキストの順序付け、圧縮とキャッシュのトレードオフ、テレメトリ、コスト管理、任意の経済的なキャッシュウォーミングについては、prompt-caching-and-cost.md を読んでください。
読み取り専用の計画モードと実行時の進捗用足場の違い、承認ゲート付き実行、目標、チェックポイント、停止条件については、planning-and-goals.md を読んでください。
プランナーが生成するワークフロー、範囲を限定した作業パケット、ワーカー／検証者のコンテキスト、統合、永続的なワークフロー状態、オーケストレーションのアンチパターンについては、workflow-orchestration.md を読んでください。
MVP後のアプローチのポートフォリオ、共有される作業意図、選択的な知見の交換、証拠に基づくチームの再配置については、adaptive-agent-teams.md を読んでください。
厳密なRLMおよびRLMに着想を得たパターン、プログラム可能なコンテキスト、再帰的な実行単位、保持される子プロトコル、継続的な改善、タスク固有の対照的なハーネス探索、実行可能なスキルについては、self-refining-recursive-harnesses.md を読んでください。
Agent Skills、段階的な情報開示、予測的な読み込み、MCP、外部コネクター、ツール検索、添付戦略については、skills-and-connectors.md を読んでください。公開ボードでのコミュニケーションについては、公開情報の開示と公開に関する契約を参照してください。
システム／開発者／ユーザー指示の優先順位とプロンプトテンプレートについては、system-prompts-instructions.md を読んでください。
OpenAI、Anthropic、OpenAI互換APIの実装パターンについては、provider-api-patterns.md を読んでください。テキスト以外の継続、意味状態／キャッシュの境界、ハイブリッドサービング機能については、ネイティブ生成状態の契約を参照してください。
ガードレール、脅威モデル、承認記録、トレース設計、症状に基づくトラブルシューティング、起動時の安全ゲート、インシデント対応については、security-observability.md を読んでください。
評価戦略、ランタイム状態のフィクスチャ、複数の能力にまたがるケース、コンテキスト予算全体にわたる障害を考慮したコンポーネント診断、安全性トレースの不変条件、モデル／設定のスイープ、ルーティング／設定／ウォーミングのプローブ、起動基準については、evals.md を読んでください。パフォーマンス改善については、測定、代理指標の検証、回帰基準の引き上げに関する契約を参照してください。
実装と監査の要点をまとめたチェックリストについては、checklists.md を読んでください。
公式リンクとプロバイダー固有の参考資料については、source-links.md を読んでください。
スキルが依頼されたハーネスのトピックを網羅しているか確認するには、coverage-audit.md を読んでください。

ユーザーにアドバイスする際の既定の回答構成

ユーザーがアーキテクチャに関するガイダンスを求めた場合は、一般論ではなく具体的なアーキテクチャを提示してください。既存の障害については、トラブルシューティングモードを使用してください。

MVP の境界：最小限の有用なバージョン、前提条件、対象外事項、リリース基準。
ハーネスの境界：モデルが行うこととアプリケーションコードが行うこと。
ループ：モデル呼び出し、ツール呼び出し、ツールの結果、停止、再試行の仕組み。ルーティングが要求された場合は、選択／ディスパッチされた ID、互換性、継続ポリシー、ルーティング状態のセマンティクスを明示してください。
指示：システム／開発者／ユーザー指示の階層とスコープ付きメモリー。実行時の変更が要求された場合は、認可された設定のタイムライン、有効状態の再生、プロバイダーへの投影を含めてください。
ツール：ツールレジストリ、スキーマ、出力、リスク分類、権限、承認ポイント。
環境への適応（要求された場合）：安定したブートストラップ、探索、記述子の来歴、安全なプローブ、正確なバインディング、ドリフト時の無効化、フォールバック。
コンテキスト：検索、メモリー、コンテキストの逼迫に応じた段階的な圧縮、想起の有用性、キャッシュを考慮した順序付け、再水和。
計画／目標：権限に基づく計画と実行進捗の追跡の区別、目標に類するループを実行するタイミング、停止方法。
ワークフローのオーケストレーション：永続的な作業パケット、ワーカーコンテキスト、検証コンテキスト、統合に分解するタイミング。
スキル／コネクター：スキルと MCP／外部コネクターの探索、読み込み、権限設定、監査の方法。公開ボードでのコミュニケーションが要求された場合は、公開対象者と公開承認を明示してください。
安全性：プロンプトインジェクションの境界、シークレット、サンドボックス化、データアクセス、ガードレール。
可観測性：トレース、メトリクス、再生、監査可能性、インシデント対応の準備。
評価：テストケース、障害プローブ、コンポーネント選択の診断、トレースの採点、回帰テストスイート、リリース基準。
ロールアウト：まず最小限の実用的なハーネスを導入し、測定結果が正当化する場合にのみ自律性を追加します。
可読性ループ：信頼できる情報源となる成果物、検証シグナル、フィードバックの収集、定期的なクリーンアップ。
高度な再帰的／継続的プロファイル（要求された場合）：コンテキストハンドル、再帰単位、保持されるライフサイクル、変更可能な状態の境界、観測された検証、昇格、ロールバック。
実験的な投機的実行（要求された場合）：適格性、正確なクレーム ID、分離された状態、無駄の予算、キャンセルの証拠、投機なしの場合との同等性評価。
適応型エージェントチーム（要求された場合）：個別のアプローチの所有権、作業意図の重複と宣言済みの複製、コミュニケーションへの依存関係、バージョン管理されたポートフォリオの決定、古い結果の処理、独立して検証された完了。
常時稼働／永続ランタイム（要求された場合）：入力の受け付けとローカルコミットのセマンティクス、所有するタスクの完了、アプリケーション状態のフォークポリシー、再接続時の観測、常駐状態の所有権、再起動時の復旧、該当する場合は定期的なソースのカバレッジ／収集／配信状態。

ハードウェアに関するリクエストでは、対象／ランタイムのインベントリ、インストール経路と書き込みの厳密な境界、リソース／期限の予算、保持する状態と復旧計画、ホストチェックと物理ボードのコミッショニングを分けたエビデンスを追加してください。

音声に関するリクエストでは、リアルタイム音声エージェントモードにある条件付き出力契約を追加してください。メディアの詳細にはプロファイルを使用し、受け入れケースにはリンク先の評価担当を使用してください。

譲れない原則

モデルはアクションを直接実行せず、ハーネスが実行します。
ツール呼び出しには、拒否、タイムアウト、エラー、中止のいずれの場合も、必ずツールの結果を返す必要があります。
リスクのある副作用はすべて、モデルの外部で実行時ポリシーによる適用を受ける必要があります。
外部向け、金銭関連、破壊的、セキュリティ関連、または規制対象のアクションでは、下書きと確定を分離する必要があります。
ツールのスキーマは範囲を限定し、型を指定し、ローカルで検証でき、監査可能でなければなりません。
変化する機能カタログは、信頼されたブートストラップ契約を通じて取り込む必要があります。ディスカバリー、スキーマ推論、生成されたヘルパーによって権限が作られることはありません。
コンテキストは有益で、簡潔で、キャッシュを考慮したものにし、必要なときに取得して添付する必要があります。
スキルと外部コネクターは段階的に開示し、すべての機能を最初から公開してはいけません。
公開掲示板への投稿は、非公開のエージェントメモリーではなく、外部に公開される情報です。この点をエージェントとユーザーに明示し、ホストで公開承認を適用する必要があります。
自動コンパクションでは、会話の文章ではなく、作業状態を保持する必要があります。
長期的な目標には、予算、チェックポイント、測定可能な完了条件が必要です。
ワークフローのオーケストレーションには、永続的なパケット状態、独立した検証、統合ルール、総予算の適用が必要です。
再帰型および継続型のハーネスが変更できるのは、型付きの補足状態に限られます。不変のランタイムポリシーで変更を検証し、権限の境界を維持し、ロールバックを可能にする必要があります。
投機的実行では作業を予測できますが、許可することはできません。完了したプログラム内の、厳密に一致する実行可能な呼び出しだけが結果を取得できます。
ハーネスは、隠れた推論を明かすことなく、運用イベントをトレースする必要があります。
永続的な知識は、チャット履歴だけでなく、エージェントが読める信頼できる情報源となる成果物に保存する必要があります。
繰り返し発生する失敗は、プロンプトで繰り返し助言するのではなく、ツール、バリデーター、ドキュメント、評価、またはポリシーに反映する必要があります。

共通の出力テンプレート

ユーザーがハーネスの設計を求めた場合は、このテンプレートを使用してください。エージェントの作成や構築を求められた場合は、概念だけの回答ではなく、MVP の設計図として使用してください。

# MVP Agent Harness Blueprint: [domain/use case]

## Objective
[What the agent must accomplish and for whom.]

## MVP scope and assumptions
[Smallest useful version, explicit assumptions, non-goals, and what is intentionally deferred.]

## Autonomy and risk level
[Answer-only, draft-only, approval-gated, or autonomous within policy.]

## Core loop
[How the model, tools, observations, retries, and stopping rules work.]

## Instruction architecture
[System/developer/user/scoped memory layout.]

## Tool registry
[Tools, schemas, risk classes, permissions, and result format.]

## Planning and goal behavior
[When to plan, when to ask, when to continue, when to stop.]

## Context and memory
[Retrieval, durable state, compaction, and rehydration.]

## Skills and connectors
[Reusable skills, MCP/external connector policy, tool search, attachment rules.]

## Safety and approvals
[Guardrails, prompt injection treatment, secrets, sandboxing, human review.]

## Observability
[Trace events, metrics, replay, auditability, and incident response.]

## Evals
[Eval cases, failure probes, trace grading, regression suites, and launch criteria.]

## Minimal implementation path
[Smallest safe version first, implementation skeleton, validation path, then measured expansion.]

注意点

単一エージェントのループが測定可能な評価に失敗するまでは、マルチエージェントシステムを設計しないでください。
厳格なラッパーと承認ポリシーなしに、execute_anything、write_database、send_message のような広範なツールを公開しないでください。
取得したウェブページ、メール、チケット、PDF、ログ、コネクターが提供する説明を、信頼された指示として扱わないでください。
コンテキストのコンパクションによって、承認状態、現在の計画、読み込み済みのルール、変更された成果物が消去されないようにしてください。
曖昧なバックログにはゴールループを使わないでください。検証と予算を伴う単一の目標にのみ使用してください。
1 つの線形ループで低コストかつ確実に完了できる作業に、ワークフローのオーケストレーションを使用しないでください。
メモリーを蓄積するだけでハーネスが自己改善すると見なしたり、観測されたプローブとロールバック手段なしに、自己作成した変更を昇格させたりしないでください。
コードで適用すべき安全性を、プロンプトの文面だけに頼らないでください。
キャッシュ可能なプロンプトの冒頭に、タイムスタンプ、リクエスト ID、変動する環境状態を置かないでください。
古くなったドキュメント、質の低い例、時代遅れのツールを、定期的に整理せずに蓄積させないでください。
安定したブートストラップインターフェース、正確なランタイムバインディング、環境変更時の無効化手段なしに、未知の環境で動作できると主張しないでください。
読み取り専用だからという理由だけで呼び出しを投機的に実行しないでください。プライバシー、コスト、レート制限、可観測性、キャンセル、破棄の安全性がすべてホストポリシーを満たす必要があります。

詳細を読むための参考リンク

プロバイダー固有の詳細が必要な場合は、以下のリンクを参照してください。

Agent Skills の仕様：https://agentskills.io/specification
Agent Skills 作成のベストプラクティス：https://agentskills.io/skill-creation/best-practices
Agent Skills の説明文の最適化：https://agentskills.io/skill-creation/optimizing-descriptions
Agent Skills の評価ガイド：https://agentskills.io/skill-creation/evaluating-skills
OpenAI の関数呼び出し：https://developers.openai.com/api/docs/guides/function-calling
OpenAI のツール：https://developers.openai.com/api/docs/guides/tools
OpenAI のエージェント：https://developers.openai.com/api/docs/guides/agents
OpenAI のガードレールと人間によるレビュー：https://developers.openai.com/api/docs/guides/agents/guardrails-approvals
OpenAI のエージェントの安全性：https://developers.openai.com/api/docs/guides/agent-builder-safety
OpenAI のサンドボックスエージェント：https://developers.openai.com/api/docs/guides/agents/sandboxes
OpenAI Responses への移行：https://developers.openai.com/api/docs/guides/migrate-to-responses
OpenAI のプロンプトキャッシュ：https://developers.openai.com/api/docs/guides/prompt-caching
OpenAI Prompt Caching 201：https://developers.openai.com/cookbook/examples/prompt_caching_201
OpenAI のハーネスエンジニアリングに関する記事：https://openai.com/index/harness-engineering/
Anthropic の効果的なエージェントの構築：https://www.anthropic.com/research/building-effective-agents
Anthropic の AI エージェント向け効果的なコンテキストエンジニアリング：https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
Anthropic のエージェント向け効果的なツールの作成：https://www.anthropic.com/engineering/writing-tools-for-agents
Anthropic の長時間実行ハーネス：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
Anthropic の MCP を使ったコード実行：https://www.anthropic.com/engineering/code-execution-with-mcp
MCP の仕様：https://modelcontextprotocol.io/specification/2026-07-28

Markdown 対応

ログインしてコメント

基本情報

作者: denissergeevitch
リポジトリ: denissergeevitch/agents-best-practices
カテゴリ: エージェントワークフロー
インストール数: 1,046
GitHub スター: 2,404

問題を報告