AIエージェントのコンテキスト設計ガイド - 何を渡し、何を渡さないかを決める

AIエージェントの失敗を見ていると、モデルが弱いからではなく、渡したコンテキストが悪いだけのことが多いです。古い仕様、長すぎるログ、前回の失敗手順、関係ない社内ルール、必要以上の顧客情報を同じ context window に詰めると、エージェントは賢くなるどころか迷います。

この記事では、AIエージェントに「何を覚えさせるか」ではなく、1回の run に何を渡すかを扱います。tool の危険度分類は AIエージェント tool risk tier 設計ガイド、実行後の証跡は AIエージェント監査ログ設計ガイド、稼働中に止める観点は AIエージェント本番監視設計ガイド、agent 間の引き継ぎは AIエージェント引き継ぎ設計ガイド に分けます。

今回の論点は、作業開始時点の入力パケットをどう組むかです。

先に結論: context は多いほど良いわけではない

AIエージェントの context は、情報置き場ではありません。次の判断をよくするための、限られた作業面です。

私なら、1回の run に渡す context を次の7層に分けます。

層	渡すもの	渡さないもの
goal	今回の完了条件、対象範囲、非対象	過去の曖昧な希望
constraints	禁止事項、承認条件、変更してよい場所	強制できない長文ポリシー全文
current state	branch、dirty 状態、関連ファイル、直近エラー	古いログ全文
domain facts	今回必要な仕様、用語、判断基準	関係ない社内wiki
retrieved evidence	必要な一次情報、該当箇所の抜粋	検索結果の山
memory	再利用する短い学び	一時的な調査メモ、秘密情報
tool results	今回の run で得た検証結果	失敗した試行の全出力

この分解をしないと、「念のため全部渡す」運用になります。全部渡すと、エージェントは必要な情報を見失い、古い前提を正しいものとして扱い、危険な tool call の判断も雑になります。

既存記事との役割分担

コンテキスト設計は、近いテーマが多いです。重複を避けるため、責務を先に切ります。

近いテーマ	扱うこと	この記事で扱うこと
memory design	session をまたいで何を残すか	今回の run に何を読み込むか
handoff contract	agent 間で何を渡すか	run 開始時の入力をどう組むか
runtime monitoring	稼働中に何を検知して止めるか	監視しやすい context をどう作るか
tool risk tier	tool の危険度をどう分類するか	tool 判断に必要な背景だけをどう渡すか
prompt engineering	指示文をどう書くか	指示以外の状態、証拠、履歴をどう選ぶか

コンテキスト設計は、プロンプトの上手さだけではありません。system instruction、会話履歴、MCP から来る resources、retrieval の抜粋、tool result、memory、承認状態まで含めて、モデルに見える状態を整える仕事です。

run input packet を作る

私は、agent に作業を渡す前に run_input_packet を作るようにしています。実装は YAML でも JSON でもよく、重要なのは「何を渡したか」を後で説明できる形にすることです。

run_input_packet:
  run_id: 20260624-blog-context-01
  goal:
    outcome: "AIエージェントのコンテキスト設計記事を1本作り、PRを開く"
    done_when:
      - "記事が追加されている"
      - "keyword-plan と learnings が更新されている"
      - "build が成功している"
  scope:
    allowed_paths:
      - "src/content/blog/"
      - "data/seo/"
      - "public/llms*.txt"
    out_of_scope:
      - "既存記事の大規模リライト"
      - "main checkout の未コミット変更"
  constraints:
    approval:
      - "main に直接 commit しない"
      - "GitHub PR 作成は外部 write として記録する"
    content:
      - "既存記事と検索意図を分ける"
      - "内部リンクは2から4本"
  evidence:
    primary_sources:
      - "OpenAI Agents SDK context management"
      - "Claude Code memory docs"
      - "MCP specification"
  current_state:
    branch: "article/ai-agent-context-engineering-20260624"
    base: "origin/main"

この packet を最初に作ると、agent に渡す情報が自然に絞られます。逆に、packet に入らない情報は、今回の作業には不要かもしれません。

context に入れる順番を決める

同じ情報でも、順番が悪いと効きません。私は次の順で渡します。

1. 完了条件
2. 禁止事項と承認条件
3. 現在の状態
4. 対象ファイルや対象データ
5. 必要な仕様・一次情報
6. 過去の学びや memory
7. 直近の tool result

完了条件より先に背景説明を長く書くと、agent は「何を終えればよいか」を見失います。逆に、禁止事項を後ろに置くと、途中の計画や tool call で無視されやすくなります。

実務では、最初の200行くらいに本当に必要な判断材料を置く感覚が大事です。長い資料を渡すなら全文ではなく、該当箇所、版、いつ取得したか、今回の判断にどう関係するかを添えた方が安定します。

raw data ではなく、証拠として渡す

ログ、検索結果、仕様書、issue コメントをそのまま貼ると、context はすぐ汚れます。agent に必要なのは raw data ではなく、判断に使える証拠です。

悪い渡し方はこうです。

CI log 全文を貼る。関係ない warning、成功済み step、古い retry も含める。

よい渡し方はこうです。

evidence:
  source: "GitHub Actions run 12345"
  observed_at: "2026-06-24T06:20:00+09:00"
  relevant_lines:
    - "src/lib/foo.ts:42 Type 'null' is not assignable to type 'User'"
  ruled_out:
    - "install step succeeded"
    - "format step succeeded"
  implication: "型修正だけでよく、依存追加は不要"

この形にすると、agent は「何が事実で、何が推測で、何を除外済みか」を分けて扱えます。監査ログやレビューでも、なぜその判断になったかを追いやすくなります。

memory は読み込む前に選別する

永続 memory は便利ですが、毎回全部読むものではありません。Claude Code の docs でも、CLAUDE.md や auto memory は context として扱われ、強制設定ではないと説明されています。つまり、memory に書いてあるだけでは安全制御になりません。

run 開始時は、memory を次の3つに分けます。

種類	扱い
必ず読む	build command、禁止コマンド、repo 固有の公開手順
必要なら読む	過去の類似エラー、設計判断、記事クラスタの境界
読まない	古い暫定対応、個人の好み、今回と無関係な過去ログ

たとえば、ブログ記事作成で必要なのは「slug の規約」「SEO主戦場」「build command」「既存記事との役割分担」です。過去の全 PR コメントや CI log を読む必要はありません。

memory を選別しないと、agent は古い成功パターンを今回にも当てはめます。これは地味に危険です。以前は正しかった workaround が、今の main では壊れていることがあるからです。

MCP から来る context は信頼境界を付ける

MCP は、LLM アプリケーションへ context、tools、workflow を接続するための標準化された仕組みです。便利な一方で、MCP server から来る resources や tool result は、すべて同じ信頼度ではありません。

私は MCP 由来の context に、最低限このメタ情報を付けます。

mcp_context:
  server_id: github-mcp
  owner: platform-team
  trust_level: internal-approved
  resource: "pull_request_diff"
  freshness: "2026-06-24T06:25:00+09:00"
  sensitivity: "internal-code"
  allowed_use:
    - "summarize"
    - "identify risk"
  forbidden_use:
    - "copy into public article"
    - "send to external service"

MCP server を許可しただけでは不十分です。そこから来た情報を、どの用途に使ってよいかまで決める必要があります。特に社内文書、顧客データ、private repo の diff は、agent に読ませることと、出力へ混ぜることを分けて考えます。

compaction 前提で作業を分ける

長い run では、どこかで context が圧縮されます。圧縮が入ると、細かい失敗理由、途中で却下した案、古い tool result の区別が薄くなります。

そのため、長い作業を1つの巨大な会話で続けるより、節目で context を作り直した方が安定します。

私の基準は次です。

状況	対応
調査が長くなった	調査結果を evidence summary にして別 run へ渡す
2回同じ修正に失敗した	失敗した仮説を明記して context を作り直す
tool result が大量に出た	raw output ではなく relevant finding だけ残す
scope が変わった	旧 scope の context を捨て、新しい packet を作る
承認待ちで止まった	承認対象、代替案、期限だけ残す

これは作業を遅くするためではありません。むしろ、agent が汚れた履歴に引きずられないので速くなります。

secret と個人情報は context に入れない

当たり前ですが、API key、cookie、secret、個人情報、生ログは context に入れない方がよいです。必要なら、agent には参照用 ID、マスク済み値、権限付き tool の結果だけを渡します。

customer_context:
  customer_ref: "customer_8421"
  plan: "enterprise"
  region: "jp"
  do_not_include:
    - "email"
    - "access_token"
    - "raw support transcript"

agent に「注意して扱って」と書くより、最初から渡さない方が堅いです。どうしても必要な場合は、承認付き tool で必要最小限だけ取得し、監査ログに残します。

context lint を作る

組織で回すなら、context packet には lint をかけます。自然言語の品質を完全に検査する必要はありません。最初は危ないものを機械的に落とすだけで十分です。

context_lint:
  fail_if:
    - "secret pattern detected"
    - "raw customer transcript included"
    - "goal is empty"
    - "allowed_paths is empty for write task"
    - "source freshness is missing for external facts"
  warn_if:
    - "context exceeds 20000 tokens"
    - "more than 5 primary sources"
    - "unrelated memory files included"
    - "constraints contain should/maybe only"

この lint は、評価設計にもつながります。agent の回答を採点する前に、そもそも入力が悪くなかったかを見られるからです。

実務での設計手順

最初から完璧な context platform を作る必要はありません。小さく始めるなら、次の順で十分です。

1. run の完了条件を1画面に収める
2. allowed / forbidden scope を明示する
3. evidence は source、freshness、implication 付きで渡す
4. memory は今回読むものだけに絞る
5. MCP context には trust level と allowed use を付ける
6. raw log は要約してから渡す
7. context lint で secret と長すぎる入力を落とす

これだけでも、AIエージェントの失敗はかなり減ります。特に「失敗した作業をそのまま続けて、さらに悪化する」パターンを止めやすくなります。

参考にした一次情報

• OpenAI Agents SDK - Agents
• OpenAI Agents SDK - Context management
• OpenAI Prompt engineering
• Claude Code - How Claude remembers your project
• Anthropic - Effective context engineering for AI agents
• Model Context Protocol specification

まとめ

AIエージェントの品質は、モデル選定だけでは決まりません。何を渡し、何を渡さず、どの証拠をどの順番で見せるかで大きく変わります。

context は多ければよいものではありません。完了条件、制約、現在状態、証拠、memory、MCP context、tool result を分け、今回の run に必要なものだけを渡す。これができると、承認、監査、評価、監視の設計も揃いやすくなります。

AIエージェントを組織で使うなら、プロンプトを書く前に context packet を設計するべきです。そこが曖昧なまま tool や memory を増やしても、事故の入口が増えるだけです。