正本: anthropic-llm-agent-engineering-guide.md / 基準日: 2026-09-05 / 95見出し

Anthropic版 LLM・Agent Engineering Guide

基準日: 2026-09-05 対象: Claude API / Claude Platform、Claude Code、MCPを使ったLLMアプリケーションとCoding Agentの設計 正本: このMarkdown。iPhone向けHTMLはこの原稿から生成する。

この資料の立場

この資料は、Claudeの使い方を暗記するマニュアルではない。Prompt、Context、Tool、Host、Agent Loopを分解し、Claude CodeやMCPを「すでにあるAgent実装の一例」として読み解くための設計資料である。

章中のラベルは次の意味を持つ。

• 公式仕様: AnthropicまたはMCPの仕様・Docs本文に書かれている挙動。
• 公式推奨: 公式DocsやEngineering記事が推奨する方法。
• 実務上の解釈: 公式記述をシステム設計へ翻訳した説明。
• 一般化した原則: Claude以外のモデルやローカル実装にも移せる原則。
• 要再確認: モデル、SDK、beta、preview、deprecatedに依存する記述。

全体像

Claudeを呼ぶだけなら、入力を渡して出力を受け取る一回の生成でよい。Agentにするには、モデルが行動を提案し、Hostが実行し、結果を次の文脈へ戻し、検証して止める境界が必要になる。

最初に覚えるべきことは、Claude自身がファイルシステムやAPIを直接操作しているわけではない、という点である。モデルが出すのは「次にこのツールをこの引数で呼びたい」という構造化された提案であり、実行、認証、権限、失敗処理はHostの責任である。Anthropicが提供するServer toolsのようにAnthropic側で実行される機能もあるが、その場合も「どこで実行されるか」を仕様として区別する。

Part 1 — LLMの基本制御

1.1 PromptとContextを混同しない

Prompt は、モデルへ何をしてほしいかを記述・構造化する設計物である。Context は、あるサンプリング時点にモデルが見られるトークン全体であり、Prompt以外に会話履歴、ツール定義、ツール結果、取得文書、画像、思考ブロックなども含み得る。

したがって、長い指示文を上手に書くことだけでは長時間Agentを安定させられない。どのターンに、どの情報を、どの順序で、どの粒度で渡すかがContext Engineeringの問題になる。

1.2 SystemとUserの役割

Claude Messages APIでは、systemはアプリケーション側の恒常的な役割・制約・方針を置く場所、userはその会話での要求・入力・参照データを置く場所として使うのが自然である。これは「systemなら絶対に守られる」という意味ではない。モデルは最終的に入力された自然言語を解釈するので、Host側の権限・検証・実行境界を別に設計する。

実務では、次の分離が扱いやすい。

1.3 公式のPrompting推奨

現行のAnthropic Prompting best practicesでは、明確で直接的な指示、目的や動機を含む文脈、few-shot例、XMLタグによる構造化、長文データの構造化が推奨されている。

• 望む出力形式・制約を明示する。
• 手順の順序や完全性が重要なら番号付きの手順にする。
• なぜその制約が重要かを短く説明する。
• 例は実際のユースケースに近く、エッジケースを含み、例用のXMLで囲む。
• 複数文書は文書ごとに名前・メタデータ・本文を分ける。
• 長文の分析では、根拠となる引用を先に抽出させてから結論を求める。

例は単なる説明ではなく、モデルに出力の分布を示す制御信号である。公式Docsは、状況に合った3〜5個の例から始めることを案内している。ただし、例が少ないほど必ず悪いという法則ではない。例の品質と、評価データでの実測を優先する。

<instructions>
  契約書の条項を比較し、差分とリスクを出力する。
</instructions>
<documents>
  <document id="old">
    <source>旧版契約書</source>
    <content>...</content>
  </document>
  <document id="new">
    <source>新版契約書</source>
    <content>...</content>
  </document>
</documents>
<output_contract>
  JSONの配列で返す。各要素は article, change, risk, evidence を持つ。
</output_contract>

XMLはXMLを生成するという意味ではなく、指示、参照情報、入力、例の境界をモデルに見せるための区切りである。タグ名は一貫性と意味があればよく、タグだけで権限境界が生まれるわけではない。

1.4 Output format、Structured Output、Prefill

自由文が必要な場面では、見出しや箇条書きの契約を指示する。機械処理が必要な場面では、JSON Schemaに基づくStructured Outputsまたはツールの入力スキーマを使う。正規表現で出力を後処理するだけより、入力・出力の検証点が明確になる。

Prefillは、以前のClaude APIでassistantメッセージの続きを与え、形式を誘導する技法として使われた。現行のPrompting best practicesでは、Claude 4.6系以降で最後のassistant turnのprefillが非対応または移行対象とされ、構造化出力・明示的な指示・user turnへの継続文移動が案内されている。この記述はモデル世代に依存するため、実装時には必ず対象モデルのMigration guideを確認する。

1.5 Prompt injectionとinstruction conflict

Prompt injectionは、参照文書・Webページ・ツール結果などのデータに含まれる命令が、アプリケーションの目的を上書きしようとする問題である。XMLタグは境界を明示する助けにはなるが、セキュリティ機構ではない。

一般化した防御の骨格は次のとおり。

1. Instructionsとuntrusted dataを別フィールドまたは別タグへ分ける。
2. 外部データ内の「この指示に従え」を命令ではなくデータとして扱うよう指示する。
3. 重要な操作はモデルの文章だけで許可せず、Hostのallowlist、引数検証、ユーザー承認で止める。
4. ツール結果を最小化し、秘密情報や不要なHTMLをそのまま次のContextへ流さない。
5. 侵入例を評価データに入れ、単発の成功例ではなく失敗率を見る。

1.6 Prompt caching

Prompt cachingは、再利用されるPrompt prefixの処理を効率化するための仕組みである。キャッシュされたトークンもContext windowから消えるわけではない。キャッシュは費用・レイテンシーの最適化であり、長すぎるContextを安全にする機能ではない。動的なユーザー入力やツール結果を固定prefixに混ぜると、再利用率とデータ境界の両方を悪化させる。

Part 1 Sources

• Prompting best practices — Claude Platform Docs — 公式推奨、例、XML、長文、Prefill移行。
• Structured outputs — Claude Platform Docs — JSON Schema、strict tool use。
• Prompt caching — Claude Platform Docs — cache breakpointと利用量。

Part 2 — Context Engineering

2.1 Contextの定義

AnthropicのEngineering記事では、Contextを「LLMのサンプリング時に含まれるトークンの集合」と説明している。現行Context windows Docsでも、system prompt、messages、tool result、画像、文書、tool definitions、出力と思考などがContext windowに影響すると説明される。

用語を次のように固定する。

2.2 Context windowとContext rot

Context windowは大きさに上限があり、入力と出力の双方、場合によってはthinking tokenも消費する。長い履歴を全部残しても、モデルが全情報を同じ強さで使うわけではない。AnthropicのContext Engineering記事は、Contextが長くなるほど関連情報の想起や注意が難しくなる現象をcontext rotとして紹介し、モデルの能力を引き出すには毎ターンのContext選別が必要だとする。

従って「1M tokensあるから全部入れる」は設計方針にならない。長文を入れる場合も、目的、関連箇所、出典、優先順位、不要になった結果を決める。

2.3 取得とProgressive Disclosure

RAGはKnowledgeを検索し、必要な断片をContextへ追加する設計である。Progressive Disclosureは、最初から全詳細をロードせず、名前・概要・目次などの小さなメタデータだけを先に示し、必要になったときに本文・スクリプト・ツールをロードする考え方である。

この考え方はClaude CodeのSkillsやMCP tool searchにも現れる。Skillのdescriptionを先に発見し、使用時だけ本文をロードする。MCPも接続先のツール名や指示を扱うが、実際の利用まで完全なスキーマや結果を必要以上に抱え込まない設計を取れる。

2.4 Memory、CLAUDE.md、Session

Memoryは「過去のすべての会話」ではない。将来役に立つ情報を圧縮し、保存し、再注入する仕組みである。Claude Codeでは、ユーザーやプロジェクトが書くCLAUDE.mdと、Claudeが蓄積するauto memoryが別の仕組みとして説明される。どちらもContextであり、機械的に禁止を強制する設定ではない。

CLAUDE.mdは毎セッション必要なプロジェクト規約・コマンド・構造に向く。作業手順、APIリファレンス、頻繁には使わない知識はSkillやpath-scoped rulesへ分ける。大きな常時ロードファイルはトークンと注意を消費し、ルールの遵守率を下げる。

2.5 Compactionと何が失われるか

Compactionは古い履歴を要約・圧縮して長いAgent実行を継続する仕組みである。要約は現在の状態を保存するが、次を失う可能性がある。

• 失敗した試行の具体的なログと、なぜ採用しなかったか。
• 低頻度だが重要な制約。
• ファイルの行番号や細かい差分。
• Tool resultの原文、証拠、出典の粒度。
• 「ユーザーが言外に期待した」曖昧なニュアンス。

したがって、Compaction前に決定事項、未解決事項、テスト結果、ファイルパス、禁止事項、出典を構造化した作業メモへ落とすとよい。ツール結果を古い順に無限に保持するのではなく、要約と再取得可能な参照を残す。

2.6 Context管理の実務ルール

Part 2 Sources

• Effective context engineering for AI agents — Contextの定義、Prompt Engineeringとの違い、Context rot。
• Context windows — token計算、Context window、compaction、context editing。
• Compaction — 圧縮後のusageと長時間会話。
• How Claude remembers your project — CLAUDE.md、auto memory、階層、ロード。
• Extend Claude Code — 機能ごとのcontext costとロード時期。

Part 3 — Tool Use

3.1 Toolは関数ではなく、境界を持つ実行契約

AnthropicのTool useは、開発者またはAnthropicが提供する関数をClaudeが呼べるようにする仕組みである。開発者が定義するToolでは、少なくとも名前、自然言語のdescription、JSON Schema形式のinput_schemaを定義する。

{
  "name": "get_weather",
  "description": "指定地点の現在の天気を取得する。読み取り専用。",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "都市名または郵便番号"
      }
    },
    "required": ["location"],
    "additionalProperties": false
  }
}

DescriptionはモデルにとってAPIドキュメントである。しかしdescriptionを信頼境界にしてはいけない。HostはJSON Schemaの検証、認可、対象リソースの再確認、レート制限、タイムアウトを自分で行う。

3.2 Client toolsとServer tools

現行Docsは、Client toolsとServer toolsを実行場所で区別する。

Web search、Web fetch、Code execution、Tool searchなど、利用できるServer toolと名前・パラメータはモデルやAPIのバージョンに依存する。Client toolのサンプルコードをServer toolのように扱わない。

3.3 Tool Use lifecycle

重要なライフサイクルは以下である。

1. Applicationがtools配列でTool契約を提示する。
2. Claudeが通常のテキストまたはtool_use content blockを返す。
3. Applicationがstop_reasonとtool_use_id、名前、引数を検査する。
4. 許可された場合だけ実際の関数・CLI・HTTP処理を実行する。
5. Applicationがassistantの応答とtool_resultを次のMessages requestへ追加する。
6. Claudeが結果を使って次のToolを選ぶか、最終テキストを返す。

モデルの出力に「実行した」と書かれていても、Hostが処理して結果を返すまでは副作用は発生しない。

3.4 Parallel、Sequential、tool_choice

独立した読み取りToolは同一ターンに複数出して並列実行できる。後続Toolが前の結果に依存するなら、結果を戻してから次のターンへ進むSequential flowにする。並列化では、書き込み競合、レート制限、順序依存、二重請求、同じ副作用の重複を検討する。

tool_choiceは、auto、特定Toolの指定、Toolを使わない選択、parallel tool useの制御など、モデルがToolをどう選ぶかを制御する。強制Toolは、入力検証と組み合わせないと誤った引数を必ず実行する危険がある。

3.5 エラー、Retry、Idempotency

Toolが失敗した場合、Tool errorを構造化してClaudeへ返すか、Hostで再試行してから返す。再試行する条件は、タイムアウト、429、接続切断などの一時障害に限定する。引数不正、権限拒否、対象不存在は同じ入力を繰り返しても直らない。

書き込みToolには、idempotency key、操作対象のversion、dry-run、取り消し、上限金額、approvalを設ける。delete、send、publish、rotate keyなどの破壊的操作は、Tool descriptionだけで安全にならない。

MAX_ITERATIONS = 8

messages = [{"role": "user", "content": user_text}]

for iteration in range(MAX_ITERATIONS):
    response = call_claude(messages=messages, tools=tool_definitions)
    messages.append({"role": "assistant", "content": response.content})

    calls = [block for block in response.content if block.type == "tool_use"]
    if not calls:
        return extract_text(response)

    results = []
    for call in calls:
        if not schema_is_valid(call.input, call.name):
            result = {"error": "invalid_arguments"}
        elif not policy_allows(call.name, call.input):
            result = {"error": "approval_required"}
        else:
            result = run_with_timeout_and_audit(call.name, call.input)
        results.append({
            "type": "tool_result",
            "tool_use_id": call.id,
            "content": to_bounded_json(result),
        })
    messages.append({"role": "user", "content": results})

raise RuntimeError("maximum iterations reached")

これは構造理解用の擬似コードで、APIキー、実サービス、認証を含まない。

3.6 Tool結果のサイズと安全性

Tool resultは次のContextへ入るため、全文を返すほど正確になるとは限らない。取得件数、文字数、フィールド、秘密情報、HTML/script、ユーザー入力の命令らしき部分を制限する。必要ならresultに要約と再取得用IDを返す。

一般化したTool契約の必須項目は、入力Schema、成功結果Schema、エラーSchema、timeout、retry、side effect、permission、audit、idempotencyである。

Part 3 Sources

• Tool use with Claude — Toolの定義、Client/Server実行、tool_use/tool_result、parallel。
• Structured outputs — JSON Schemaとstrict tool use。

Part 4 — Model Context Protocol (MCP)

4.1 MCPの目的

MCPは、モデルそのもののAPI Tool Callingではない。外部のTool、Resource、PromptなどのContextとCapabilityを、Hostが発見・接続・管理しやすくするためのプロトコルである。MCP仕様はJSON-RPCを基礎にしたstatefulなClient–Server protocolで、Hostが複数Clientを管理する構成を定義する。

4.2 Host、Client、Server

MCP Serverは会話全体を読む主体ではない。仕様の設計原則では、Serverへ必要なContextだけを渡し、他Serverや全履歴を見せず、Hostが横断的な境界を維持する。

4.3 三つのServer primitive

• Tools: モデルが外部システムを操作・照会するための機能。MCP仕様はToolの発見と呼び出し、Schema、listChanged通知を定義するが、UIや最終的な実行許可の形はHostの責任である。
• Resources: URIで識別されるデータ。ファイル、DB schema、アプリケーション情報などを提供し、HostがUI選択、検索、自動Context inclusionなどへ組み込む。
• Prompts: ServerからClientへ提供する構造化されたPrompt template。仕様上はuser-controlledで、UIのslash command等から明示的に選ぶ用途を想定する。

この違いは「誰が選ぶか」で考えると整理しやすい。Toolはモデルが必要と判断して呼び出し得る。ResourceはアプリがContextへどう入れるかを決める。Promptはユーザーが選択して使う意図を持つ。実装は自由なので、この区分をUIの絶対ルールと誤解しない。

4.4 Lifecycle、Capability、Notification

MCP LifecycleはInitialization、Operation、Shutdownの三段階である。最初のやりとりはClientが送るinitialize requestで、Protocol version、Client capabilities、implementation infoを伝え、Serverが対応version、capabilities、server infoを返す。正常化後、Clientはinitialized notificationを送る。

Capability negotiationにより、Tools、Resources、Prompts、Sampling、Roots、Loggingなどの機能が実装されているかを明示する。listChangedやResource subscriptionがある場合、Serverは変更通知を送り、Clientが再取得できる。

要再確認: MCP仕様版はURLのversion segmentを含む。新仕様が出たら、2025-06-18の例をそのまま現行と断定せず、Transport、Authorization、Tool annotations、Elicitation等の追加・変更を比較する。

4.5 TransportとAuthorization

ローカルではstdio、リモートではStreamable HTTPなど、TransportはMCP messageを運ぶ境界である。Transportを変えてもHost–Client–Serverの責任分担は変わらないが、プロセス起動、URL、認証、再接続、Origin検証、監視の設計が変わる。

リモート接続は「URLを知っている」だけでは安全でない。OAuthやアクセストークン、scope、redirect、Serverの信頼、送信するデータ、監査を設計する。MCP Authorization仕様はOAuthベースの認証・認可の相互運用を定めるが、業務アプリの認可判断をHostから取り除くものではない。

4.6 API Tool UseとMCP

「Tool Use = MCP」ではない。MCP Serverを接続したHostが、Serverから得たTool定義をモデル向けTool契約へ変換することはあるが、両者の仕様上の責務は別である。

Part 4 Sources

• MCP Architecture — Host / Client / Server、境界、Context集約。
• MCP Lifecycle — initialize、能力交渉、shutdown。
• MCP Tools — model-controlled Tool、human denial、tools/list。
• MCP Resources — URI、application-driven Resource、subscription。
• MCP Prompts — user-controlled Prompt、prompts/list。
• MCP Transports — stdio、Streamable HTTP。
• MCP Authorization — OAuthと認可。

Part 5 — Agent

5.1 WorkflowとAgent

Anthropicの公式Engineering記事は、agentic systemsの中で次の区別を置く。

• Workflow: LLMとToolを事前定義されたコード経路でオーケストレーションするシステム。
• Agent: LLMが自分のプロセスとTool利用を動的に指揮し、目的達成方法を選ぶシステム。

記事は、単純な一回のLLM callにRetrievalやin-context examplesを足すだけで十分なケースも多く、複雑なAgentを最初から採用しないよう助言している。2024-12-19公開の記事自身が、Tooling landscapeは変化したため現行Managed Agents Docsも参照するよう注記している。従って、この章では定義とパターンの背景として使い、現行製品仕様の根拠には現在のDocsを優先する。

5.2 Agent Loop

一般化したAgent Loopは次である。

Agentと呼ばれるかどうかは、LLMを使った回数ではなく、次の行動をモデルが選ぶ範囲、実行境界、終了条件、検証の有無で決まる。長く動くAgentほど、max iterations、token budget、timeout、approval、stop conditionをHostで持つ。

5.3 Augmented LLM

Anthropic記事の出発点は、モデルへ適切なRetrieval、Tool、Memory、System instructionを加えたaugmented LLMである。Toolを増やすほど能力が上がるとは限らない。Tool名の重複、似た入力、巨大なSchema、複数Serverからの無関係な結果は、モデルの選択負荷とContext noiseを増やす。

Part 5 Sources

• Building effective agents — WorkflowとAgentの定義、複雑性を増やす判断。
• How Claude Code works — モデルとToolがAgent harnessを構成する説明。

Part 6 — Agentic Patterns

6.1 Prompt chaining

一つの大きなPromptを、検証可能な複数段階へ分ける。例は「抽出 → 分類 → 生成」。中間結果をSchema検証できるため、長い一発生成より失敗箇所が分かる。

• 向く: 固定された順序、各段階の出力形式が違う処理。
• 避ける: 各段階に同じ全文を渡し、Contextだけが増える設計。
• Failure mode: 中間誤りが後段へ伝播、段階ごとのLatency増加。

6.2 Routing

入力を分類し、専門Prompt・Model・Toolへ分岐する。

• 向く: 料金・権限・専門性が入力タイプで大きく変わる処理。
• 避ける: ルーターが曖昧で、すべてのケースを一つの分類へ押し込む場合。
• Failure mode: ルーティング誤り、分類自体の評価不足、機密データの誤った行先。

6.3 Parallelization

独立した調査・変換・検証を並列に走らせ、最後に統合する。Toolのparallel callや複数Subagentは同じ抽象パターンに見えるが、実行境界とContext継承は別に確認する。

• 向く: 互いに副作用がなく、独立して評価できる読み取り処理。
• 避ける: 同じファイルやレコードを同時に書く場合。
• Failure mode: rate limit、結果の不整合、統合Promptの肥大化。

6.4 Orchestrator-worker

親Agentがタスクを分解し、Workerへ渡し、結果を統合する。Workerへ渡すのは目標、対象、制約、出力契約、必要なContextに限定する。

• 向く: 分解可能な大規模探索、専門性の異なる作業。
• 避ける: 親が毎回Workerを作るコストの方が大きい単純作業。
• Failure mode: delegation messageが不十分、親がWorker結果を検証せず採用。

6.5 Evaluator-optimizer

生成Agentと評価Agentを分け、基準を満たすまで改善する。

• 向く: 明示可能な品質基準、テスト、Schema、引用完全性。
• 避ける: 評価基準が主観的で、評価Agentの好みを正解にしてしまう場合。
• Failure mode: 評価Agentが同じ誤りを共有、無限改善、コスト爆発。

6.6 Agent loop

Agent loopはパターンというより制御構造である。モデルに自由度を与えるほど、終了条件、権限、観測可能性、回復戦略を強くする。一般化した原則: 自由度を上げたら、境界と評価も同じ設計単位で追加する。

Part 6 Sources

• Building effective agents — Prompt chaining、Routing、Parallelization、Orchestrator-worker、Evaluator-optimizer、Agentの背景。
• Tool use with Claude — parallel tool useとtool choice。

Part 7 — Claude Code Architecture

7.1 Claude CodeはAgent harness

Claude Codeはターミナル上で動くagentic assistantであり、モデルにfilesystem、検索、編集、コマンド実行、Web、外部サービスなどのToolを組み合わせる。公式Docsは、Claude Codeが「文脈を集める、行動する、結果を検証する」の三相を繰り返すと説明する。

「Claudeがコードを理解して書き換える」という一文を、次の部品に分解する。

7.2 Filesystemとterminal

filesystemへのread、write、terminal commandは、モデルの文章能力とは別の副作用である。Claude CodeはToolを介して操作し、ユーザーや設定のpermission modeとsandboxが実行可否を決める。

Terminalを許可すると、Git、package manager、test runner、外部CLIなど多くの能力が一つの入口から見える。コマンドallowlistだけでなく、working directory、環境変数、ネットワーク、秘密ファイル、破壊的な引数を考える。

7.3 Planning、Implementation、Verification

大きな変更では、いきなり編集せず、まずRepositoryを探索し、対象ファイル、依存、テスト、制約を把握する。計画は自然言語の約束に過ぎないので、Implementation後にdiffとテストで裏付ける。Claude Codeの「検証」は自己申告ではなく、実行されたテスト・lint・型検査・手動確認の観測結果として扱う。

Git integrationは、Gitコマンドを使えることと、mainへpushしてよいことを分離する。Branch、commit、PR、merge、pushは副作用と承認の別境界である。

Part 7 Sources

• How Claude Code works — Agentic loop、Tool、ユーザーの介入。
• Extend Claude Code — CLAUDE.md、Skills、MCP、Subagents、Hooksの境界。
• Configure permissions — Permission modes、allow/deny。
• Configure the sandboxed Bash tool — sandbox filesystem/network。

Part 8 — CLAUDE.md

8.1 何を入れるか

CLAUDE.mdは、Claudeが毎回知っているべきプロジェクト指示を書くMarkdownである。build/test command、project layout、命名、生成物、常に守る規約など、「毎回説明している事実」を置く。

公式Docsの実務的な目安は、一つのCLAUDE.mdを200行未満に保つこと。これは仕様上の絶対上限ではなく、Context costと遵守率を管理する目安である。

8.2 Hierarchyとloading

現行Claude Code Docsに記載されている代表的なscopeは次のとおり。

上位から下位へ内容を連結し、より近い場所の指示が後に読まれる。これは設定のhard overrideではなく、矛盾する自然言語が同じContextに入るということなので、矛盾を作らない。

Claude CodeはCLAUDE.mdを読み、AGENTS.mdを自動的に同一視するわけではない。既存のAGENTS.mdを共有したい場合、CLAUDE.mdからimportするか、両方のツールに対応する形を明示的に設定する。

8.3 Good / Bad

# Good: 毎セッション必要で検証可能
- パッケージ管理は pnpm を使う。
- JavaScriptを変更したら pnpm test と pnpm lint を実行する。
- API handlerは src/api/handlers/ に置く。
- .env と secrets/ は読まず、必要なら人間へ確認する。
- 本番デプロイは明示的な承認なしに実行しない。

# Bad: 巨大・曖昧・Hard securityを自然言語だけに依存
- このプロジェクトのすべてを完全に理解してから作業する。
- 絶対に安全に、常に最高品質で実装する。
- 全API仕様、全ログ、全チケットをここへ貼り付ける。
- rm -rf や本番変更を絶対に行わない（実行ポリシーを別途設定しない）。

「絶対に編集しない」は、CLAUDE.mdのお願いであって、強制ではない。Tool hook、managed settings、sandbox、permission denyなど、機械的に止める層を使う。

Part 8 Sources

• How Claude remembers your project — scope、load order、import、AGENTS.md、200行目安。
• Extend Claude Code — CLAUDE.mdとSkillの比較。

Part 9 — Skills

9.1 Skillの正体

Claude CodeのSkillは、知識、指示、再利用可能なWorkflowをまとめたMarkdown中心の拡張単位である。最小構成はSkill directoryのSKILL.mdで、YAML frontmatterが名前・description・起動条件を示し、本文が手順や知識を示す。追加のreference、script、templateを含められる。

Skillは次のどれか一つに完全一致するものではない。

9.2 Discovery、loading、portability

Skillはpersonal、project、pluginなどのscopeに置ける。descriptionはモデルが関連性を判断する手掛かりで、ユーザーが明示的にslash commandで呼ぶこともできる。通常はdescriptionが先に見え、完全な本文は必要時にロードされる。このProgressive Disclosureが、CLAUDE.mdへ全手順を書くよりContextを節約する。

副作用のあるSkillは自動起動を抑え、ユーザー起動に限定する設計が安全である。Skill内のscriptが安全になるわけではないため、実行環境、引数検証、permission、ログを別途持つ。

9.3 CLAUDE.md / Skill / Hook / Subagent / MCP

Part 9 Sources

• Extend Claude with skills — SKILL.md、frontmatter、scope、discovery。
• Extend Claude Code — CLAUDE.md / Skill / Hook / MCP / Subagentの比較。

Part 10 — Hooks

10.1 Hookは自然言語のお願いではない

HookはClaude Codeのlifecycle eventに対して、command、HTTP request、MCP tool、prompt、subagentなどを起動する拡張である。PreToolUse、PostToolUse、SessionStart、UserPromptSubmitなどのeventを使い、毎回同じ検査・整形・記録を実行する。

自然言語で「必ずlintして」と書くと、モデルが忘れる・順序を変える・結果を成功と誤認する可能性がある。Hookなら、formatter、test、禁止コマンド検出、監査ログなどのdeterministic処理を外へ置ける。

10.2 event設計

Hookは何でも外部化すればよいわけではない。毎回のlintが重すぎるとAgent loopが遅くなるため、変更ファイル単位、PostToolUse、最終検証などに分ける。

10.3 代表例

PreToolUse:
  - .env、秘密鍵、認証ファイルへのwriteを拒否
  - rm、drop、publish、sendなどのside effectをapprovalへ回す
  - shellのworking directoryをproject内に固定

PostToolUse:
  - formatterを変更ファイルだけに実行
  - TypeScriptの型検査またはテストを条件付きで実行
  - 実行結果とexit statusを監査ログへ記録

一般化した原則: LLMが考えるべき判断はPrompt・Agentへ、同じ条件なら同じ結果にすべき処理はHook・Policy・CIへ置く。

Part 10 Sources

• Hooks reference — Hook lifecycle、event、handler、exit code。
• Configure permissions — permissionとHookを組み合わせる境界。

Part 11 — Subagents

11.1 Context isolation

Subagentは親のAgentが委譲する別のAgent loopで、役割、Tool、権限、必要なContextを限定し、結果の要約を親へ返す。Claude Code Docsは、通常のSubagentは新しいisolated contextを開始し、親が読んだ全ファイルや会話履歴を自動的には見ないと説明する。

これは「賢い人を増やす」だけでなく、Context pollutionを抑える設計である。大量ログ、探索の迷走、テスト出力を親の判断Contextへ全部混ぜず、必要な結論・証拠・未解決点だけ戻す。

11.2 Parallelismとworktree

read-heavyな探索、テスト、triageは並列化しやすい。write-heavyな複数Agentの同時編集は競合と統合コストが増える。独立branchやworktree isolationを使う場合も、最終的なmerge、テスト、ownerの判断は親または人間が行う。

Subagentには、目的、対象、利用可能なTool、禁止事項、返す形式、完了条件を明示する。単に「調べて」では親に再利用できる結果にならない。

11.3 Multi-agentとの違い

Subagentは、親が必要なときに作る一時的または専門的な委譲単位である。Multi-agent systemは、複数のAgentが継続的に協調し、通信・状態・所有権・失敗回復を持つアーキテクチャ全体を指す。Subagentを3つ起動しただけで、信頼できるMulti-agent systemになるわけではない。

Part 11 Sources

• Create custom subagents — fresh context、delegation、isolation、Tool制御。
• How Claude Code works — Agent loopへのTool結果の戻り。

Part 12 — Permissions / Security

12.1 三つの境界

Agent securityはPromptの問題だけではない。少なくとも次の三層を分ける。

1. Model guidance: system、CLAUDE.md、Skillで望ましい行動を伝える。
2. Runtime policy: permission、allow/deny、approval、Tool Schema、引数検証。
3. Execution isolation: sandbox、filesystem、network、process、secret access。

第一層が侵入や誤判断を完全に防ぐことを期待しない。重要な禁止事項は第二・第三層で強制し、操作は監査可能にする。

12.2 Prompt injection

外部文書、issue、Web、MCP Resource、Tool resultに命令らしい文が混ざる。モデルはそれをデータと命令の両方として解釈する可能性がある。防御は、信頼できるInstructionを別に保持し、外部データをuntrustedとしてラベル付けし、side effectの直前に再認可すること。

12.3 Permission matrix

read repository       -> allow within project
write source          -> allow with diff visibility
write secrets         -> deny
run tests              -> allow in sandbox
network request        -> explicit host allowlist
git commit             -> policy / user decision
push or deploy         -> separate explicit approval
delete or publish      -> approval + idempotency + audit
MCP tool call          -> server trust + data review + approval policy

Claude Codeのsandboxed Bashはfilesystem access、network、allowWrite、denyRead/denyWriteなどの実行境界を設定する。sandboxがあるから全コマンドが安全になるのではなく、境界内でのデータ破壊、外部サービスへの正当な権限、漏えいを引き続き評価する。

12.4 Secret handling

API keyや個人情報をPrompt、Tool result、static HTML、ログへ入れない。環境変数やsecret managerを使い、AgentのToolには必要最小限の操作だけを露出する。静的サイトの生成物は公開URLに載り得るため、build前にsecret scanを行う。

Part 12 Sources

• Configure permissions — allow/deny、permission mode。
• Configure the sandboxed Bash tool — filesystem、network、sandbox policy。
• MCP Tools — humanがTool invocationをdenyできる設計。
• MCP Authorization — OAuth、認可境界。

Part 13 — Verification / Evals

13.1 完了宣言と正しさ

Agentが「完了」と言ったことは、正しさの証拠ではない。正しさを、実行された外部検証の結果で定義する。

13.2 Verification loop

評価データには、成功例だけでなく、曖昧な要求、境界値、Tool error、権限拒否、Prompt injection、長いContext、途中中断、重複実行を含める。評価は最終文だけでなく、Tool選択、引数、順序、停止、Side effect、検証結果も見る。

Part 13 Sources

• Prompting best practices — examplesと自分のevalsでの再確認。
• Tool use with Claude — Tool結果を次の推論へ返す流れ。
• Building effective agents — Agentの複雑性と信頼性のトレードオフ。

Part 14 — Claude APIでAgentを自作する場合

14.1 Host/Applicationを自分で持つ

Claude APIで自作Agentを作る場合、Claude Codeのfilesystem、terminal、permission UIが自動で付くわけではない。自分のApplicationが、会話状態、Tool registry、実行、認証、Policy、ユーザー承認、retry、timeout、ログ、評価を実装する。

14.2 Control points

14.3 最小Agent loop

def run_agent(user_text, max_iterations=6):
    messages = [{"role": "user", "content": user_text}]

    for _ in range(max_iterations):
        response = anthropic_messages_create(
            system=SYSTEM_INSTRUCTIONS,
            messages=messages,
            tools=TOOLS,
        )
        messages.append({"role": "assistant", "content": response.content})

        tool_uses = get_tool_uses(response)
        if not tool_uses:
            return get_final_text(response)

        tool_results = []
        for call in tool_uses:
            decision = authorize(call.name, call.input)
            if decision == "deny":
                value = {"error": "denied_by_policy"}
            elif decision == "approval_required":
                value = request_human_approval(call)
            else:
                value = execute_tool(call.name, call.input, timeout_seconds=20)
            tool_results.append(make_tool_result(call.id, value))

        messages.append({"role": "user", "content": tool_results})

    return {"status": "incomplete", "reason": "max_iterations"}

このloopでは、モデルが「自動でツール実行する」と表現しない。Applicationがtool_useを解釈し、認可し、実行し、tool_resultを返している。

Part 14 Sources

• Tool use with Claude — Client toolのround trip。
• Claude Agent SDK overview — Claude CodeのAgent harnessを自作アプリへ組み込む入口。
• Context windows — Context、token、compaction。

Part 15 — Local LLMへ移植する際の考え方

15.1 移植できるもの

Claude固有のAPIフィールドをコピーするのではなく、責任の分離を移植する。

15.2 そのまま移植できないもの

Claudeのtool_use content block、モデル固有のthinking、Prompt caching、Claude Codeの設定探索、Anthropic Server tools、MCP connectorの実装、特定モデルのContext windowは、ローカルモデルの能力やRuntimeに依存する。名前を同じにしても互換性は生まれない。

Local LLMがJSON Schemaを常に守るとは限らないため、パーサ、修復、再試行、拒否、Tool実行前検証を設ける。Tool callingをモデルがネイティブに出せない場合も、構造化出力でAction objectを出させ、同じHost loopで処理できる。

15.3 最小ローカル構成

15.4 移植の順序

1. まず一回のModel callと、検証可能な出力Schemaを作る。
2. 読み取り専用Toolを一つ追加し、Tool call round tripをテストする。
3. max iterations、timeout、エラー、ログ、Schema validationを入れる。
4. 書き込みToolとapprovalを追加する。
5. RetrievalとContext compactionを追加する。
6. 必要になったときだけSkill loader、MCP、Subagent、Hookを追加する。
7. 評価データとregression testを固定し、モデルを交換しても境界の契約を保つ。

一般化した結論: Agentの価値はモデル単体の賢さだけでなく、Context選択、Tool境界、Permission、Verificationを含むHost設計で決まる。

Part 15 Sources

• Building effective agents — 単純でComposableな構成から始める考え方。
• Effective context engineering for AI agents — 状態全体を選別するContext設計。
• MCP Architecture — Host、Client、Serverの責任分離。

付録 — Anthropic版の更新チェック

次回更新では、まず次の順に確認する。

1. Claude models と対象モデルのPrompting guide。
2. Tool use、Structured Outputs、Thinking、Context windows。
3. Claude Code What's new、Memory、Skills、Hooks、Subagents、Permissions。
4. MCP specification のversion、Authorization、Transport。
5. 本文のdeprecated / beta / preview表示、サンプルのSDK import、limit、料金。

古い公式記事は歴史的な判断材料として残すが、現行仕様を説明する箇所には使わない。特に2024年のBuilding effective agentsは、記事自身がTooling landscapeの変化を注記しているため、定義とパターンの根拠に限定した。