最終レビュー報告
基準日: 2026-09-05 対象: Anthropic版、OpenAI版、両社比較、iPhone向け静的HTML、更新・公開運用
作成した成果物
- anthropic-llm-agent-engineering-guide.md
- AnthropicのPart 1〜15を、Prompt、Context、Tool Use、MCP、Agentic Patterns、Claude Code、CLAUDE.md、Skills、Hooks、Subagents、権限、検証、自作Host、ローカル移植の順に整理。
- openai-llm-agent-engineering-guide.md
- OpenAIのPart 1〜15を、Instructions、Responses API、Conversation State、Compaction、Function Calling、Hosted Tools、MCP、Agents SDK、Handoff、Guardrails、Codex、AGENTS.md、Skills、Subagents、Evalsの順に整理。
- llm-agent-concepts-comparison.md
- 共通のAgent mental model、概念マップ、対応ラベル、ベンダー固有機能と一般原則の分離、ローカルAgent構成を整理。
- docs/source-ledger.md
- Anthropic、MCP、OpenAI、Codex、公開基盤の公式一次ソースをClaim単位の台帳として整理。URL、該当見出し、取得日、公開日または更新日、状態を記録。
- docs/maintenance.md
- Markdown正本からの再生成、検証、ローカル確認、Cloudflare Pages Direct Upload、定期更新の運用手順を記録。
- scripts/build_site.py / scripts/verify_site.py
- 外部MarkdownライブラリやAPIを使わない静的サイト生成・検証スクリプト。
- site/
- トップ、3資料、ソース台帳、最終レビュー、運用方法、404、サイト内検索JSON、レスポンシブCSS、Mermaid表示設定を含む生成物。
一次ソースと調査方針
一次ソースの全件は docs/source-ledger.md に記載した。主な確認先は次のとおり。
| 分野 | 主な公式資料 |
|---|---|
| Anthropic API | Prompting best practices、Tool use overview、Context windows、Compaction、Prompt caching、Structured outputs |
| Anthropic Agent設計 | Building Effective Agents、Effective context engineering for AI agents |
| Claude Code | Features overview、How Claude Code works、Memory、Skills、Hooks、Subagents、Permissions、Sandboxing、MCP |
| MCP | Architecture、Lifecycle、Tools、Resources、Prompts、Roots、Sampling、Authorization、Transports（2025-06-18仕様） |
| OpenAI API | Prompt engineering、Responses API移行、Conversation state、Streaming、Background mode、Compaction、Tools |
| OpenAI Agents | Agents SDK Quickstart、Agents overview、Orchestration、Guardrails and human review、Agent evals |
| OpenAI Tool | Function calling、Structured outputs、MCP and connectors、Skills |
| Codex | Agent configuration / AGENTS.md、Subagents、Permissions、公式Codexリポジトリ |
| 公開基盤 | Cloudflare Pages Static HTML / Direct Upload / Custom domains、Vercel Deployments / CLI、GCP Cloud Storage静的サイト |
検索結果のsnippetだけを根拠にはせず、公式ページ本文と見出しを確認した。公開日・更新日が明記されないページは「ページ上で未確認」とし、モデル名、上限値、Preview、deprecatedなど変化しやすい仕様は「Version-sensitive」とした。
除外・歴史的扱いにした仕様
- 2024年公開のAnthropic「Building Effective Agents」は、workflowとagentの設計原則を参照する歴史的資料として扱い、現行API仕様の代用にはしなかった。
- 旧URLから現行のAnthropic Platform Docsへ移動するページは、旧URLの記述をそのまま引用せず、現行URLを正本として採用した。
- OpenAIの旧Assistants API中心の設計は、現行のResponses API / Agents SDKと混同しないよう主資料の中心から外した。
- モデル固有のcontext window、価格、利用可能なtool、Preview機能の固定値は、資料全体の不変原則として断定しなかった。
- Claude CodeとCodexのCLI設定は、Anthropic APIやOpenAI APIの一般仕様ではなく、製品固有の章に分離した。
Fact Checkで確認・修正した重要点
- Anthropicのworkflowは事前に決めたコード経路、agentはモデルが動的に工程・tool利用を決めるものとして区別した。
- Anthropicのclient toolはアプリケーションが実行してtool resultを返し、server toolは提供者側が実行するという境界を図と擬似コードで分けた。
- MCPは単なるtool schemaではなく、Host、1対1のClient、Server、JSON-RPC、capability negotiation、resources / prompts / toolsを持つプロトコルとして整理した。
- Contextはsystem、messages、tool definitions、tool results、添付データ、出力上限など、モデルのサンプリングに実際に含まれる入力として扱った。Prompt cachingはcontextから情報を消す機能ではない。
- Claude CodeのCLAUDE.md、Skills、Hooks、Subagents、Permissions、Sandboxingは、ロード時期、判断主体、実行境界、セキュリティ境界が異なるため一つの「設定ファイル」としてまとめなかった。
- OpenAI Responses APIのFunction Callingは、現在のResponses item形式とChat Completionsのtool_calls形式を混同しないよう分けた。
- Agents SDKのHandoffは制御を専門Agentへ移し、Agents as toolsはmanagerが制御を保持する設計として対比した。
- Guardrailsは自動検証、Human reviewは副作用前の停止・承認として区別し、両者を同義語にしなかった。
- OpenAIのConversation state、Compaction、Background mode、Streamingは、Agent loopの状態管理・長時間処理・イベント伝達の別々の機能として整理した。
- Cloudflare PagesのDirect Uploadは、初回の公開候補としては適するが、後から同一プロジェクトをGit連携へ切り替えられないという運用上の注意をREADMEと運用メモに残した。
三段階Fact Checkの実施結果
| Pass | 実施内容 | 結果 |
|---|---|---|
| Pass 1 | 51件のClaim台帳を公式本文の該当見出し・取得日・仕様状態と照合し、各Part末尾へSourceリンクを配置 | 完了。検索snippet単独の根拠は不使用 |
| Pass 2 | Prompt、Context、Tool、MCP、Agent、Permission、Evalを複数の公式資料で横断照合 | 完了。client/server、Responses/Agents SDK、Handoff/Agents as toolsなどの境界を修正 |
| Pass 3 | 全体図と比較表を確認し、vendor固有仕様の一般化、無理な一対一対応、モデル依存の固定値を除外 | 完了。Equivalent / Similar / Different / No direct equivalentを明示 |
両社の重要な解釈差
| 観点 | Anthropic | OpenAI | 解釈 |
|---|---|---|---|
| Agent設計の説明 | workflow / agentの設計原則、Context engineering、Claude Codeのharness | Responses API、Agents SDKのRunner、Orchestration、Tracing / Evals | 共通のloopはあるが、公開資料が強調する抽象レイヤーが異なる |
| Tool境界 | client tool / server tool、MCPのHost境界 | function calling、hosted tools、remote MCP、tool search | 「モデルが提案する」と「実行主体」は分けて比較する必要がある |
| 委譲 | Subagentが隔離contextで専門作業 | HandoffまたはAgents as toolsで制御の移し方を選択 | 同じmulti-agentという語でも制御権が異なる |
| 指示の永続化 | CLAUDE.md、Skills、Hooks、Subagents | AGENTS.md、Skills、Codex permissions / sandbox | ファイル名やロード規則はvendor-specificで、移植対象は運用原則 |
| 安全性 | Permissions、Sandboxing、tool承認 | Guardrails、Human review、Sandbox / permissions | 自然言語指示、承認、OS / runtime隔離を別々の層として設計する |
一般化できる設計原則
- User goal、instructions、context、model、tool selection、host runtime、execution、observation、verification、human approvalを分離する。
- Agentの自由度を上げる前に、workflow、schema validation、timeout、retry、max iteration、idempotencyを固定する。
- Toolは名前と説明だけでなく、入力schema、権限、side effect、監査ログ、失敗時の契約を持つ実行境界にする。
- 長い履歴をそのまま蓄積せず、progressive disclosure、要約、compaction、retrieval、memoryの用途を分ける。
- Guardrailとpermissionは置換関係ではなく、モデル出力の検査と実行権限の検査を重ねる。
- Evalは最終回答だけでなく、tool選択、引数、handoff、guardrail、承認、実行結果を含むtrace単位で設計する。
- ベンダー固有のSDKや設定ファイルをローカルAgentへ移植するのではなく、Context Manager、Tool Registry、Dispatcher、Validation、Permission、Memory、Logging、Eval、HITLの境界を移植する。
ローカル実装で重要な章
最初に読むべき順序は、比較資料のUniversal Mental Model、Anthropic版Part 2〜5、OpenAI版Part 2〜5、両資料のPermissions / Security、Verification / Evals、最後に各vendor固有のCLI章である。最小構成では、1つのモデル、少数のschema付きtool、dispatcher、timeout / retry、ログ、deny-by-defaultの権限、fixtureによるevalから始める。
公開基盤の判断
採用候補はCloudflare Pages Direct Uploadである。ビルド済み静的アセットをそのまま公開でき、pages.dev、preview相当のbranch deploy、カスタムドメインへ拡張できる。サイトはJavaScriptからAPIを呼ばず、APIキーや認証情報をアセットに含めない。
ただし、非公開資料のアクセス制御、Cloudflareアカウント・Pagesプロジェクト、カスタムドメインのDNS、HTTPS、初回previewのiPhone Safari確認は外部状態に依存するため、今回のローカル実装では実行していない。公開手順と定期更新手順は README.md と docs/maintenance.md に残した。
更新時の確認対象
月次、またはAnthropic / OpenAI / MCP / Claude Code / Codexのリリース時に、まずソース台帳のURL、ページ見出し、deprecated / Preview表示、モデル・API状態を確認する。次に該当章、比較表、Mermaid図、コード例を更新し、python3 scripts/build_site.py と python3 scripts/verify_site.py を実行してからCloudflareのpreviewをiPhoneで確認する。
実行した検証
- python3 -m py_compile scripts/build_site.py scripts/verify_site.py: 成功。
- python3 scripts/build_site.py: 成功。検索エントリ233件を生成。
- python3 scripts/verify_site.py: 成功。必須8ページ、内部リンク、viewport、CSS、Mermaid、検索JSON、credential・添付除外を確認。
- Python例5ブロック: 関数ラッパー内で構文チェックに成功。例は構造理解用のため、実サービスを呼び出さない。
- node --check static/search.js: 成功。
- Python標準ライブラリのHTTPサーバーでトップ、3資料、台帳、検索JSON、404を取得: 7 URLすべてHTTP 200。
- 目視による実機iOS Safari、Cloudflare preview、本番公開、DNS・アクセス制御: 外部アカウントと実機が必要なため未実施。