メインコンテンツにスキップ

パート2: コンテキストのエンジニアリング

コンテキストエンジニアリングは、高速なAIアウトプットと有用なAIアウトプットを分けるスキルです。パート1のルールファイルはその一部に過ぎません。このパートはより大きな規律について扱います。エージェントが何を見るか、そしていつ見るかを決定することです。

思考の転換は「どうすればモデルを騙して良いコードを書かせられるか？」から「新しいチームメンバーがうまく貢献するためには何を知る必要があり、どう効率的に伝えるか？」へのシフトです。

2つのバケツ：静的と動的​

すべてのコンテキストは2つのバケツのいずれかに入り、バケツを選ぶことは実際のコストを伴う実際のエンジニアリング上の意思決定です。

静的コンテキストはすべてのリクエストで常に読み込まれます：

  • システム指示
  • ルールファイル（CLAUDE.md など）
  • グローバルメモリとペルソナ

信頼性があります — エージェントが決して忘れることはありません — しかし、現在のタスクが必要とするかどうかにかかわらず、すべての呼び出しでそのすべてのトークン分を支払うため、高価です。

動的コンテキストは必要なときのみ読み込まれます：

  • 手元のタスクによってトリガーされるスキル
  • 実行中に取得されたツール結果
  • 検索インデックスから取得したドキュメント
  • 会話履歴の直近のスライス

効率的です — 情報が実際に関連している場合にのみ支払います。

両極端の落とし穴：静的コンテキストが多すぎるとコストが無駄になり、シグナルが薄まります（重要なルールがノイズに埋もれます）。少なすぎると、エージェントが必要だったものを忘れます。静的/動的の境界線を他のアーキテクチャ上の決定と同様に扱いましょう — 偶発的なものではなく、レビューされバージョン管理されるものとして。

コストの直感的な把握​

ルールファイルが2,000トークンで、セッション内で50リクエストを行うとします。それだけでルールファイルのトークンが100,000トークン、50回分支払うことになります。そのファイルの半分が1つのタスクにのみ関連する参考資料なら、49回のリクエストでお金を無駄にしています。その半分をオンデマンドで読み込まれるスキルに移せば、残りの49回のコストがなくなります。

これが「静的コンテキストを密度高く、シグナルを高く保つ」ことがスタイルの好みではなく、コスト項目である理由です。

スキル：動的コンテキストのパターン​

動的バケツを管理する最も効果的な方法はスキルです。タスクがそれに一致したときにのみエージェントが読み込む、自己完結した手続き的知識のパッケージです。

スキルはプログレッシブ・ディスクロージャーを通じて機能します — 遅延読み込みされる3つのレイヤー：

  1. 起動時に、エージェントは軽量なメタデータ（名前と1行の説明）のみを見る。
  2. タスクが一致したとき、完全な指示を読み込む。
  3. 深みが必要な場合にのみ、重い参考資料を取り込む。

結果：軽量なジェネラリストエージェントが、実際に使用しているものだけのトークンコストを支払いながら、何十もの専門的な能力を持てます。

最小限のスキルは次のようになります：

---
name: stripe-refunds
description: How to issue and reconcile refunds through our billing layer. Use when a task involves refunds, chargebacks, or payment reversals.
---

# Issuing a refund

1. Look up the charge via `billing.get_charge(charge_id)`.
2. Refunds over $500 require an `approved_by` field — never auto-approve.
3. Call `billing.refund(charge_id, amount, approved_by)`.
4. Write a `RefundRecord` to the ledger in the same transaction.
5. Emit a `refund.issued` event.

See `reference/refund-edge-cases.md` for partial refunds and currency conversion.

エージェントはタスクが実際に返金に言及したときにのみこれを読みます。それ以外の時間は、1行の説明のコスト以外はかかりません。

管理すべき6種類のコンテキスト​

何を提供するかを決める際には、6つのカテゴリにわたって考えてください。ほとんどのワークフローは中間の4つへの投資が不足しています。

  • 指示 — エージェントの役割、目標、境界（あなたのルールファイル）。
  • 知識 — ドキュメント、アーキテクチャ図、ドメインデータ。
  • メモリ — 直前に何が起きたか（セッション）、プロジェクトが何であるか（長期）。
  • 例 — インターネット上の一般的なものではなく、あなた自身のコードベースからの参照パターン。
  • ツール — エージェントが呼び出せるAPIとスクリプトの正確な定義。
  • ガードレール — ハードな制約と安全ルール。

「例」については特に言及する価値があります。実際のコードから引用した1つの例は、3段落の説明よりも速くエージェントにあなたのスタイルを教えます。

リポジトリ全体を貼り付けない​

よくある失敗は、「すべてを持つように」と100,000トークンのリポジトリ全体をプロンプトに貼り付けることです。これは高価で、かつ逆効果です — 関連するシグナルが埋もれてしまいます。現在のタスクに重要な数ファイルだけを取得し、エージェントにさらに求めさせましょう。コードベース全体の認識はツールの仕事（インデックス化、取得）であり、すべてのプロンプトで手作業でやることではありません。

自分のワークフローをセットアップする​

  • 現在の静的コンテキストにあるすべてのものを列挙する。各項目について問う：すべてのタスクがこれを必要とするか？
  • タスク固有の素材をルールファイルからスキルに移す。
  • 定期的に発生する専門的なタスク（返金フロー、マイグレーションパターン、レポート形式）のための最初のスキルを書く。
  • コードベースからの実際の例をいくつかルールファイルまたはスキルに追加する。
  • ファイル全体を貼り付けるのをやめ、取得によって関連するものを表面化させる。