概要
コンテキストエンジニアリングとは、AIコーディングエージェントが何を読むかを設計することです。セッションの各時点でどの情報がコンテキストウィンドウを占めているのか、そして何を意図的に載せないのかを決めます。 プロンプトエンジニアリングとは扱う範囲が違います。プロンプトエンジニアリングが工夫するのは1回の依頼そのもので、言い回しや構造、添える例といった依頼文の中身が対象です。コンテキストエンジニアリングが扱うのはセッション全体です。人が何か入力する前から読み込まれている指示ファイルやツールの定義、エージェントが開いたファイル、実行したコマンドの出力、やり取りのなかで積み上がる会話履歴まで含みます。 この区別が大事なのは、エージェントが読むものの大半を人間が書いていないからです。1回の依頼をどれだけ丁寧に書いても、それはウィンドウに載る情報のごく一部にすぎません。残りは指示ファイルや読み込んだファイル、コマンドの出力、会話履歴で埋まっています。つまりプロンプトの工夫だけでは手が届かない範囲があり、そこを設計するのがコンテキストエンジニアリングです。 ページ全体を通じた目標は1つです。作業に必要な情報を必要な量だけ渡し、それ以上は渡さないことです。多すぎても少なすぎても困ります。足りなければエージェントは推測で埋めますし、多すぎれば肝心な情報が埋もれます。 本ページでは、コンテキストが膨らむと精度が落ちる理由、コンテキストを占めているものの内訳、セッションをまたいで残る部分の設計、そして必要な情報だけを手元に残すためのセッションの運用を解説します。なぜコンテキストで精度が落ちるのか
コンテキストウィンドウとは、モデルが一度に考慮できるテキストの総量です。セッション中にエージェントが読んだもの、つまり指示・ファイル・コマンドの出力・エージェント自身の過去の応答は、すべてその一部を占めます。そして上限は固定です。 この上限があるために、性質の異なる2つの問題が起きます。 容量の問題。 コンテキスト量がウィンドウを超えると、古い情報から破棄または要約されます。長いセッションでは、冒頭で伝えた制約が途中でコンテキストから消え、エージェントがそれに違反するコードを書いてしまうことがあります。 注意の問題。 上限に達するはるか手前から、情報量が増えるほど品質は落ちます。モデルはウィンドウ内のすべてのトークンを考慮するため、余計な情報が混ざるほど、肝心な情報に注意が向きにくくなります。無関係なコード1000行に囲まれた的確な指示は、数ある手がかりの1つに紛れてしまいます。 無関係な履歴は、ただ場所を取るだけでなく出力そのものを歪めます。失敗した試行、途中で捨てた方針、訂正済みの誤りは、モデルから見える状態で残り続け、生成される内容に影響します。同じセッションで修正指示を重ねるほど効きが悪くなるのはこのためです。修正するたびに、直した内容と一緒に失敗した試行もコンテキストに積み上がっていきます。コンテキストウィンドウが大きくなれば容量の上限は上がりますが、注意の問題は解消されません。リポジトリ全体を読み込めるからといって、読み込んでよいわけではありません。
コンテキストに載るもの
ウィンドウに載る情報は、2通りの経路のどちらかで入ってきます。設計の方法がそれぞれ違うため、この2つを分けて考えることが以降の話の土台になります。常設コンテキスト
カスタム指示ファイル、システムプロンプト、使えるツールやSkillの定義。毎回のセッション開始時に読み込まれるので、あらかじめファイルを編集して設計します。
動的コンテキスト
エージェントが開いたファイル、実行したコマンドやツールの出力、会話履歴。作業を進めるなかで入ってくるので、タスクの絞り方とセッションの運用で設計します。
常設コンテキストを設計する
常設コンテキストの中心にあるのはカスタム指示ファイルです。リポジトリにコミットしておき、エージェントが毎回のセッション開始時に読み込むファイルを指します。ファイル名はツールによって違いますが（AGENTS.md・CLAUDE.md・.cursorrulesなど）、考えるべきことはどれも同じです。毎回のセッションに載せる価値があるのは何か、という一点に尽きます。
常設コンテキストの残り2つのうち、システムプロンプトは利用者が書き換えられないことがほとんどです。ツールやSkillの定義をどこまで接続するかはMCPで扱うため、本章では指示ファイルを設計対象にします。
ファイルに書くこと
判断基準は2つあります。伝えなければエージェントが間違えるか。そして、それが大半のタスクで問題になるか。両方を満たすものだけをファイルに入れます。- コマンド。 ビルド・型チェック・リント、そして単一ファイルのテストの実行方法。どの呼び出し方を使っているかは、エージェントには推測できません。
- デフォルトと異なる規約。 世間の慣習と違うために、伝えなければエージェントが破ってしまうルール。ブランチの命名やコミットメッセージの形式といったリポジトリの慣習も含みます。
- アーキテクチャ上の制約。 どのレイヤーを経由すべきか、どのライブラリを採用しているか、何を導入してはいけないか。
- 環境の癖。 素直にやると、黙って失敗したり紛らわしいエラーで止まったりするセットアップ手順。
- コードを読めばわかること。 ファイルを見ればわかることを書き写しても、分量が増えるだけで情報は増えません。しかも誰にも気づかれないまま古くなります。
- 特定のタスクにだけ必要な知識。 ごく一部のタスクで役立つ代わりに、無関係なセッションすべてで場所を取ります。
- 一般的なプログラミングの心得。 「読みやすいコードを書く」のような指示は、出力を変えないまま注意だけを奪います。
ルールを置く階層
指示ファイルは、たいてい複数の階層から読み込まれます。リポジトリのルート（チームで共有しコミットする）、サブディレクトリ（その配下にだけ当てはまるルール）、そして個人用のファイル（個人の好みで、コミットしない）です。 各ルールは、それが成り立つ最も狭い階層に置きます。フロントエンドのディレクトリにしか関係しないルールが、バックエンドの作業中にコンテキストを占める必要はありません。個人の好みも、チームで共有するファイルに置くものではありません。ファイルの肥大化を防ぐ
指示ファイルは、意識して減らさないかぎり増え続けます。問題が起きるたびにルールを足す理由は生まれますが、ルールを消す理由はなかなか生まれないからです。そしてある長さを超えると、守られる率が下がります。個々のルールが他のルールに埋もれ、ファイル自体がタスクと注意を奪い合うようになるためです。 歯止めになる習慣が2つあります。- コードベースが機械的に強制するようになったルールを削除する。 リンターや型定義がチェックする規約は、指示ファイルに書く必要がありません。書かなくても違反はチェックで検出されます。
- 条件つきの知識はSkillへ切り出す。 「Xの作業をするときは」で始まるルールは、毎回のセッションで必要なものではありません。Skillは必要になった時点で読み込まれるので、そのタスクが来るまでウィンドウを占有せずに済みます。
セッションを運用する
動的コンテキストは、何をウィンドウに入れるかを絞り、セッションを続けるか切り直すかを見極めることで設計します。セッションを作業単位に合わせる
セッションを「コンテキストの単位」として扱います。同じ理解を前提にする作業は1つのセッションにまとめ、すでに分かったことがエージェントから見えている状態で進めます。その前提を共有しない作業は新しいセッションで始め、余計な履歴を引き継がせません。 よくある失敗が、無関係なタスクを同じセッションで続けてしまうことです。1つ目のタスクで開いたファイル、出力、そこで決めたことは、2つ目のタスクを進めている間もウィンドウに残ります。しかもモデルはそれらも読んで答えを組み立てるので、単に無駄というだけでは済みません。前のタスクのやり方を今の依頼に持ち込み、精度を落とします。 境界の引き方は、そもそもタスクの大きさを決めるときと同じです。単独でrevertできる程度に独立していて、単独でレビューできる程度に小さい作業単位なら、1つのセッションでも完結します。具体的な基準はタスク分解を参照してください。この切り分けは、そのまま別のエージェントへ委任できる範囲にもなります。セッションを切り直すタイミングを見極める
そろそろセッションを切り直したほうがよいというシグナルが3つあります。- 同じ問題で2回修正指示を出しても収束しないとき。コンテキストには直した内容と並んで失敗した試行が残っており、その両方が出力を引っ張り続けます。
- タスクが変わり、それまでの履歴が役に立たなくなったとき。
- セッションの冒頭で伝えた制約に反する出力が出てきたとき。制約がもう考慮されていないか、すでに残っていない可能性があります。
蓄積せずに要約する
多くのエージェントには、溜まった履歴を要約に置き換えて続行する圧縮機能があります。ウィンドウの余裕は確保できますが、その代わりに細部が失われます。 そのため圧縮は、何も変わらない処理ではなく節目として扱います。大事な制約が要約に残っているかを確認し、消えていれば伝え直します。かさばる処理を退避する
探索では、結論に必要な量よりはるかに多くのテキストを読むことになります。実装箇所を突き止めるだけでも数千行を読むことがありますが、答えが1段落で済むなら、その数千行は用が済めば不要です。 こうした処理はサブエージェントに任せます。サブエージェントが生の情報を自分のウィンドウに抱え、結果だけを返してくれます。メインのセッションは、大量の材料を持ち込まずに結論だけを受け取れます。 外部データにも同じ考え方が当てはまります。Issueやライブラリのドキュメント、デザインデータは、関係するかもしれないからと前もって渡すのではなく、必要になった時点でウィンドウに入れます。 取得の経路は問いません。MCPサーバーでも、APIの直接呼び出しでも、Webページの取得でも同じです。大事なのは、あらかじめ貼り付けて渡すのではなく、必要になった時点でエージェント自身に取得させることです。関連ページ
Vibe Coding
人とエージェントが1つのタスクを対話しながら進めるとき、本ページの原則がどう効いてくるかを扱います。
Agentic Workflow
実装を自走するエージェントへ並列に任せるとき、本ページの原則がどう効いてくるかを扱います。
Subagents
かさばる探索をメインのコンテキストウィンドウの外に置くための具体的な仕組みです。