AIコーディング辞典
AIコーディングは専門家だけのものに感じられる。説明のない専門用語。原因の分からない失敗。作業量と噛み合わない請求。
実際にはそんなことはない。この分かりにくさの多くは作られたものだ。分かりにくいままであることで得をする、VCの資金で回る経済圏がまるごと存在している。
やり取りの基本になる用語は、半日あれば身につく。それが手に入れば、全体が当て推量には感じられなくなる。
なぜコンテキストは劣化するのか。なぜ請求はこんなに高いのか。なぜ同じプロンプトが日によって違う振る舞いをするのか。
どれも、使うべき言葉さえ分かれば、すっきりした答えがある。
この辞典はそのためにある。AIコーディングの語彙を、平易な言葉に翻訳したものだ。
語彙の先も知りたい人へ。 62,000人を超える開発者が aihero.dev/newsletter（英語）に登録し、最新のスキル、AIエンジニアリングについての考察、先を行き続けるための資料を受け取っている。
目次
セクション 1 — モデル
- [AI](#ai) - [モデル (Model)](#モデル-model) - [パラメータ (Parameters)](#パラメータ-parameters) - [学習 (Training)](#学習-training) - [推論 (Inference)](#推論-inference) - [エフォート (Effort)](#エフォート-effort) - [トークン (Token)](#トークン-token) - [次トークン予測 (Next-token prediction)](#次トークン予測-next-token-prediction) - [非決定性 (Non-determinism)](#非決定性-non-determinism) - [モデルプロバイダー (Model provider)](#モデルプロバイダー-model-provider) - [ハーネス (Harness)](#ハーネス-harness) - [モデルプロバイダーへのリクエスト (Model provider request)](#モデルプロバイダーへのリクエスト-model-provider-request) - [入力トークン (Input tokens)](#入力トークン-input-tokens) - [出力トークン (Output tokens)](#出力トークン-output-tokens) - [プレフィックスキャッシュ (Prefix cache)](#プレフィックスキャッシュ-prefix-cache) - [キャッシュトークン (Cache tokens)](#キャッシュトークン-cache-tokens)セクション 2 — セッション・コンテキストウィンドウ・ターン
- [ステートレス (Stateless)](#ステートレス-stateless) - [コンテキスト (Context)](#コンテキスト-context) - [コンテキストウィンドウ (Context window)](#コンテキストウィンドウ-context-window) - [ステートフル (Stateful)](#ステートフル-stateful) - [エージェント (Agent)](#エージェント-agent) - [システムプロンプト (System prompt)](#システムプロンプト-system-prompt) - [セッション (Session)](#セッション-session) - [ターン (Turn)](#ターン-turn)セクション 3 — ツールと環境
- [環境 (Environment)](#環境-environment) - [ファイルシステム (Filesystem)](#ファイルシステム-filesystem) - [ツール (Tool)](#ツール-tool) - [ツール呼び出し (Tool call)](#ツール呼び出し-tool-call) - [ツール結果 (Tool result)](#ツール結果-tool-result) - [MCP](#mcp) - [許可リクエスト (Permission request)](#許可リクエスト-permission-request) - [許可モード (Permission mode)](#許可モード-permission-mode) - [エージェントモード (Agent mode)](#エージェントモード-agent-mode) - [サンドボックス (Sandbox)](#サンドボックス-sandbox)セクション 4 — 失敗のかたち
- [追従 (Sycophancy)](#追従-sycophancy) - [ハルシネーション (Hallucination)](#ハルシネーション-hallucination) - [パラメトリック知識 (Parametric knowledge)](#パラメトリック知識-parametric-knowledge) - [知識カットオフ (Knowledge cutoff)](#知識カットオフ-knowledge-cutoff) - [コンテキスト由来の知識 (Contextual knowledge)](#コンテキスト由来の知識-contextual-knowledge) - [注意の関係 (Attention relationship)](#注意の関係-attention-relationship) - [注意の予算 (Attention budget)](#注意の予算-attention-budget) - [注意の劣化 (Attention degradation)](#注意の劣化-attention-degradation) - [スマートゾーン (Smart zone)](#スマートゾーン-smart-zone)セクション 5 — 引き継ぎ
- [クリア (Clearing)](#クリア-clearing) - [引き継ぎ (Handoff)](#引き継ぎ-handoff) - [一次ソース (Primary source)](#一次ソース-primary-source) - [二次ソース (Secondary source)](#二次ソース-secondary-source) - [引き継ぎ成果物 (Handoff artifact)](#引き継ぎ成果物-handoff-artifact) - [仕様書 (Spec)](#仕様書-spec) - [チケット (Ticket)](#チケット-ticket) - [コンパクション (Compaction)](#コンパクション-compaction) - [自動コンパクション (Autocompact)](#自動コンパクション-autocompact)セクション 6 — メモリとステアリング
- [メモリシステム (Memory system)](#メモリシステム-memory-system) - [AGENTS.md](#agentsmd) - [段階的開示 (Progressive disclosure)](#段階的開示-progressive-disclosure) - [コンテキストポインタ (Context pointer)](#コンテキストポインタ-context-pointer) - [スキル (Skill)](#スキル-skill) - [サブエージェント (Subagent)](#サブエージェント-subagent)セクション 7 — 仕事の進め方
- [ヒューマン・イン・ザ・ループ (Human-in-the-loop)](#ヒューマンインザループ-human-in-the-loop) - [AFK](#afk) - [自動チェック (Automated check)](#自動チェック-automated-check) - [自動レビュー (Automated review)](#自動レビュー-automated-review) - [人間によるレビュー (Human review)](#人間によるレビュー-human-review) - [バイブコーディング (Vibe coding)](#バイブコーディング-vibe-coding) - [デザインコンセプト (Design concept)](#デザインコンセプト-design-concept) - [問い詰め (Grilling)](#問い詰め-grilling) - [プロトタイピング (Prototyping)](#プロトタイピング-prototyping) - [DX](#dx) - [AX](#ax)セクション 1 — モデル
AI
技術の名前ではなく、動き続けるラベル。「AI」はモデルやトークンのように固定された対象を指す言葉ではなく、コンピュータが新しく、印象的にできるようになったことを指す。いまは大規模言語モデルを指している。過去にはまったく別のものを指していた。
| 年代 | 「AI」が意味していたもの |
|---|---|
| 1950年代 | 記号的推論 — 定理証明器、チェッカーのプログラム。 |
| 1960〜70年代 | ルールベースの記号処理プログラム — ELIZA、SHRDLU。 |
| 1980年代 | エキスパートシステム — 人間の専門知識を数千の手書き if-then ルールに落とし込んだもの。 |
| 1990年代 | ゲーム木探索 — ディープ・ブルーがカスパロフに勝利（1997年）。研究者は「AI」の語を避けていた。 |
| 2000年代 | 統計的機械学習 — スパムフィルタ、レコメンダー。まだ「AI」ではなく「機械学習」と呼ばれていた。 |
| 2010年代 | ディープラーニング — 画像認識（AlexNet、2012年）、AlphaGo（2016年）。 |
| 2020年代 | 大規模言語モデル — ChatGPT（2022年）以降、「AI」はチャットボットを意味するようになった。 |
指す先が動く仕組みには名前がある。AI効果と呼ばれるもので、ある手法が安定して動くようになると呼び名が変わり — 「あれはただの探索だ」「ただの統計だ」となり — 「AI」は次の未解決の課題へと滑っていく。この観察自体は古い。バートラム・ラファエルは1971年にこう書いている。「AIとは、コンピュータでまだ適切に解く方法が分かっていない問題の総称である」。ラリー・テスラーの版（1979年ごろ）はこうだ。「知能とは、機械がまだやっていないことすべてを指す」。
AIについての会話がしばしば噛み合わないのはこのためだ。「AIは推論できない」「AIは過大評価だ」といった主張には隠れたタイムスタンプが付いている。エキスパートシステムの話かもしれないし、2010年代の画像分類器の話かもしれないし、先月のLLMの話かもしれない。どれを指すかで結論は変わる。議論が行き詰まったときの対処は、たいていその語を実際に意味している正確な用語に置き換えることだ。モデルなのか、ハーネスなのか、エージェントなのか、渡したコンテキストなのか。
避けるべき表現: 技術的な主張のなかの「AI」 — 意味している部分の名前を使うこと。実践全体のラベルとしての「AIコーディング」は問題ないが、「AIがハルシネーションを起こしている」はよくない。
使い方:
「CTOが、トリアージのキューをAIで捌けないか知りたがっている」
「スコープを切る前に翻訳しよう。彼女が言っているのは、チケットシステムにアクセスできるハーネスに載ったLLMのことだ。『AI』単体では仕様にならない」
モデル (Model)
パラメータそのもの。ステートレスで、次トークン予測しかしない。「Claude Opus 4.x」や「GPT-5.x」がモデルだ。モデル単体ではエージェント的なことは何もできず、ハーネスに載せる必要がある。
モデルはファイルを読むことも、コマンドを実行することも、ウェブを見ることも、昨日のことを覚えていることもできない。トークンを受け取り、トークンを予測して返す。それがモデルプロバイダーへのリクエスト1回分だ。エージェントが働いているように見えるもの — ツールを選び、結果を読み、タスクが終わるまでループする — はすべて、ハーネスがその予測を何度も連ねてオーケストレーションしている姿である。
モデルプロバイダーはモデルをティアで提供する。大きくて賢いが遅くて高価なものと、小さくて速く安いが能力の劣るものだ。ティアの選択は実際の判断になる。計画や難しいデバッグには重量級、機械的な変更には軽量級。ハーネスはセッションの途中での切り替えも許している。
この語を厳密に使うと診断も鋭くなる。「モデルがこれを苦手にしている」は具体的な主張だ。同じモデルでも別のハーネスに載せたり、別のコンテキストを与えたりすると、まったく違う振る舞いをすることが多い。モデルのせいにする前に、何を渡したかを確認すること。期待外れの出力の大半は、パラメータではなくコンテキストかハーネスに原因がある。
使い方:
「計画のステップだけモデルをSonnetからOpusに切り替えるべき？」
「試してもいいけど、このタスクは大半をハーネスが担っている。システムプロンプトとツールが間違っていたら、モデルを替えても効かない」
パラメータ (Parameters)
モデルの中にある数値。しばしば数十億個あり、学習で調整される。モデルが「知っている」ことはすべてここに入っている。学習がこれを書き込み、推論はこれを変えずに使う。重み（weights） とも呼ばれる。
仕組みとしては、入力を出力に変えているのがパラメータだ。次トークン予測は巨大な計算である。コンテキストウィンドウにあるトークンが入り、パラメータを通じて掛け合わされ、次のトークンの予測が出てくる。モデルの中に事実のデータベースはないし、コードのルックアップテーブルもない。あるのは、有用な出力が出やすいように並べられた数値だけだ。標準ライブラリのAPIのように、学習内容からモデルが暗唱できる事実はパラメトリック知識と呼ばれる。どこかから取得されるのではなく、パラメータに格納されているものだ。
押さえておく価値があるのは、パラメータが学習後に凍結されるという点だ。セッション中に何をしてもこれは変わらない。あなたの訂正も、見せたコードベースも、犯した失敗からの学習もだ。どのセッションも同じ数値の上で走る。モデルがステートレスなのも、組み込みの知識が知識カットオフで止まるのも、プロジェクト固有の情報がコンテキスト経由でしか届かないのも、これが理由だ。パラメータが変わる唯一の方法は追加の学習であり、それは事実上、別のモデルを作ることになる。
使い方:
「うちのコードベースでファインチューニングできない？」
「それはパラメータを更新することになるから、その後は別のモデルだね。プロジェクト1つのためなら、再学習よりコードベースをコンテキストとして読ませるほうがほぼ確実に安い」
学習 (Training)
膨大な量のテキストをモデルに与え、次トークン予測が良くなるようにパラメータを調整して、モデルのパラメータを決めるプロセス。モデルプロバイダーが一度だけ行う、高価な処理である。事前学習（本体の計算）と事後学習（指示追従や安全性などの後段の調整）の両方を含むが、この辞書のレベルでは区別は重要ではない。
仕組みは大規模な反復だ。テキストの一部をモデルに見せ、次のトークンを予測させ、実際の次トークンのほうへパラメータを少し寄せる。これを数兆トークンにわたって繰り返す。事実やルールとして保存されるものは何もない。モデルが「知っている」ことはすべて、予測がうまくなったことの副産物であり、パラメトリック知識としてパラメータに圧縮されている。
日々の作業に効いてくる帰結は2つ。学習はある時点で終わるので、モデルには知識カットオフがある — 先月上げたライブラリのバージョンをモデルは見ていない。そして学習はあなたにできることではない。モデルがあなたのコードベースも規約も社内APIも知らないとき、対処は決して「モデルに教える」ことではなく、その素材をコンテキストに載せることだ。コンテキストこそ、あなたが制御できる唯一の入力である。
使い方:
「社内APIを覚えさせられない？」
「学習では無理だね。あれはモデルプロバイダーが何か月もかけてやることだから。代わりにAPIドキュメントをコンテキストに載せよう。そっちが実際に手元にあるレバーだ」
推論 (Inference)
学習済みのモデルを走らせて出力を生成すること。モデルプロバイダーへのリクエストのたびに起きる。パラメータは固定のままで、モデルは与えられたコンテキストに対して次トークン予測を行うだけだ。学習に比べれば安いが、トークン単位で課金され、モデル利用コストの大半を占める。
モデルの一生は2つの段階に分かれる。
| 段階 | いつ起きるか | 何をするか | パラメータ |
|---|---|---|---|
| 学習 | リリース前に一度だけ | 学習用コーパスからパラメータを作る | 書き込み中 |
| 推論 | 誰かがモデルを使うたびに毎回 | 凍結されたパラメータをコンテキストに適用してトークンを生成する | 読み取り専用 |
推論時に何をしてもパラメータには書き戻されない。今日した訂正が明日には残っていないのはそのためだ。丁寧に直し方を説明したのに次のセッションで同じ間違いをするモデルは、あなたを無視しているのではない。そのやり取りから学ぶことが原理的にできないのだ。モデルはステートレスであり、継続性はその外側から — コンテキストウィンドウかメモリシステムから — 与えるしかない。
課金の仕組みもここから説明できる。リクエストごとにモデルはコンテキスト全体に対して走るので、コストは入力トークンと出力トークンに比例し、ツール呼び出しを何十回も行うエージェントは、その往復ごとに推論の代金を払う。コンテキストのサイズが品質だけでなくコストの問題でもあるのはこのためだ。
使い方:
「なんで定額ライセンスじゃなくて、使った分だけ請求が増えるの？」
「支払っているのは推論の代金だよ。モデルプロバイダーへのリクエストのたびに、プロバイダーのハードウェア上でモデルが走る。学習はもう済んでいるけど、推論のコストはリクエストごとに積み上がるし、ツールを呼べば1ターンが何回ものリクエストに膨らむこともある」
エフォート (Effort)
エフォートは、答える前にモデルがどれだけ推論するかを決めるダイヤルだ。モデルプロバイダーへのリクエストごとに設定し、目に見える応答を書き始める前にモデルが辿る思考の長さを制御する。その思考も他と同じく推論時に生成されるもので、ハーネスが隠していることは多いが、モデルが実際に行っている作業である。
エフォートを上げるとコストが増え、遅くなる。推論の過程はトークンとして出力され、目に見えなくても出力トークンとして課金され、1トークンずつ生成される。つまりエフォートを上げると答えが来るまでの待ち時間が伸び、請求額も増える。熟考と、速度・コストのトレードだ。
多くのハーネスはエフォートを小さな段階として提供している。
| レベル | 何に向くか |
|---|---|
| 低 | 機械的な編集、調べもの、進め方が1つに決まっている明確な変更。 |
| 中 | 日常のコーディング。通常のデフォルト。 |
| 高 | 厄介なバグ、設計上の判断、多段階の計画。 |
| 最大 | 最も難しい問題。間違えると巻き戻しに高くつく場面。 |
設定を誤ったときの症状は両方向に出る。難しい問題にエフォートを低くすると、必要な推論を飛ばした自信満々の浅い答えが返ってくる。読み心地は良いのに間違っていて、あとでコストを払うことになる。逆に1行のリネームに最大を設定すると、最低設定でも出せた結果のために長い思考を待たされる。
エフォートはセッション単位ではなくタスク単位で合わせること。本当に考える必要がある部分では上げ、その周りの定型作業では下げる。
使い方:
「この並行処理の修正をずっと外してくる。3回説明し直した」
「エフォートを上げてみて。推論が重いバグだから、デフォルト設定だとアプローチを決める前の思考が足りていない」
トークン (Token)
モデルが読み書きする最小単位。おおむね単語くらいの大きさだが一致はしない。よく使う語は1トークン、珍しい語や長い語は複数に割れる。コンテキストウィンドウのサイズも、コストも、レイテンシも、すべてトークンで数える。
テキストはトークナイザーによってトークンになる。トークナイザーとは、学習の前に決められた数万個の断片からなる固定の語彙で、任意の入力をその語彙の並びに分割する。モデルは文字も単語も見ていない。入力時にすべてのテキストがトークンに変換され、出力時には次トークン予測が1トークンずつ生成していく。
目安として、1トークンは英語の単語の約4分の3にあたるので、1000トークンはおよそ750語だ。日本語は1文字が1トークン前後になることも多く、同じ内容でも英語よりトークン数が増えやすい。コードはさらに読みにくい。よくあるキーワードや定型はコンパクトに収まる一方、自動生成された識別子、ハッシュ、base64の塊、minify済みの出力は「1語」あたり多数のトークンに割れる。傾向としては、トークナイザーの元データによく現れたテキストは短く効率的な符号になり、現れなかったテキストは細かく刻まれる。a3f9c2e1 のようなハッシュはどこにも現れていないので多数のトークンに割れるが、function は1トークンだ。見た目は小さいのに珍しい文字列だらけのファイルが、コンテキストウィンドウを驚くほど食うのはこのためである。
トークンは他のすべてを測る単位でもある。コストはトークン単位で、プロバイダーは入力トークンと出力トークンを別々に課金する。速度は1秒あたりのトークン数だ。出力が1トークンずつ生成されるからである。そしてコンテキストウィンドウは固定のトークン数なので、ファイルのトークン数がどれだけ入るかを決める。
避けるべき表現: 「単語」 — トークンの境界は単語の境界と一致しないし、実際に効いてくる単位は秒あたりトークン数とドルあたりトークン数だ。
使い方:
「このプロンプト、どれくらいの大きさになる？」
「トークナイザーに通してみて。スキーマ自体は小さいけど、JSONのキーが変わった形だから思ったより多くのトークンに割れるはず」
次トークン予測 (Next-token prediction)
モデルが実際にやっていること。コンテキストを与えられると、次のトークンを1つサンプリングし、末尾に追加し、また走る。文であれツール呼び出しであれ1000行のファイルであれ、出力はすべて1トークンずつ組み立てられる。モデルにはこれ以外の動作モードがない。
各ステップは同じことをする。コンテキストウィンドウにあるトークンがパラメータを通り、語彙のすべてのトークンについて確率が出る — これが次に来る確率は高い、こちらは低い、というように。その確率から1トークンがサンプリングされ、末尾に追加され、少し長くなったコンテキストでループが回る。同じプロンプトでも実行のたびに出力が変わるのは、このサンプリングのステップがあるからだ。非決定性は後付けのバグではなく、仕組みそのものに組み込まれている。
この仕組みを押さえておくと、一見おかしな振る舞いも説明がつく。モデルはトークンを出す前にそれが 真 かどうかを確かめない。 ありそう かどうかだけを見る。これがハルシネーションの根っこだ。また、1トークンずつ確定させながら進むので、自信ありげな最初の一文がその後の答え全体を誤った方向へ引っ張ることがある。そして出力トークンは厳密に1つずつ生成されるため、生成速度がエージェントの作業速度の下限を決める。
使い方:
「エージェントはどうやってツールを呼ぶ『判断』をしてるの？」
「していないよ。最後まで次トークン予測なんだ。ツール呼び出しは、出力ストリームからハーネスが解釈する構造化された文字列にすぎない」
非決定性 (Non-determinism)
同じ入力でも出力が変わりうること。同一のコンテキストでモデルを2回走らせると、違う答えが返ってくることがある。単語1つの違いのこともあれば、まったく別のアプローチのこともある。あなたのコードは何も変わっていなくても、これは起きる。
これはモデルがテキストを生成する仕組みと、モデルプロバイダーがリクエストを捌く仕組みに由来する性質だ。推論の際、モデルは次のトークン候補についての確率分布を作り、そこから1つがサンプリングされる。多くの場合、意図的にランダム性が入っている。常に最尤のトークンを選ぶと、反復的で質の低い文章になるからだ。応答の早い段階で1トークン違うだけで、その後のトークンはすべて変わる。単語1つの違いがまったく別のアプローチになるのはこのためだ。プロバイダー側の配信でも変動が乗る。リクエストは共有ハードウェア上でバッチにまとめられ、バッチ間のごく小さな浮動小数点の差が、僅差のトークン選択をひっくり返すことがある。これを全部消せる設定は存在しない。
同じタスクをエージェントに投げても、結果にはばらつきが出ると考えておくこと。ほとんどの応答は品質の釣鐘曲線の中に収まる — だからこそ非決定性が許容できる — が、裾は本当にある。妙に冴えている日もあれば、筋を見失っているように感じる日もある。同じタスク、違うサイコロの目だ。実務上の帰結は2つある。再試行は正当な戦略だ。失敗した1回は分布からの1回の抽出にすぎず、同じタスクをもう一度やらせるとうまく当たることがある。そして、決定的なツールより検証が重要になる。エージェントの振る舞いは一度テストしても再現するとは限らないので、悪い引きを捕まえるのは自動チェックの役目になる。
これを物語にしすぎないよう注意すること。人間はパターンを見つける機械なので、悪い結果が続くと「今週モデルが劣化した」証拠のように感じられる。たいていは単なる分布のせいだ。
使い方:
「Claudeが今日ひどい。悪いバージョンをデプロイした？」
「たぶん違うよ。モデルの出力は非決定的だから、同じタスクでも良い日と悪い日がある。原因探しを始める前に、明日もう一度試してみて」
モデルプロバイダー (Model provider)
推論のためにモデルを提供する主体。多くはリモートのサービス（Anthropic、OpenAI、Google）だが、ローカルでもよい — 手元のマシンで動く Ollama、LM Studio、llama.cpp など。ハーネス自身がモデルを走らせるのではなく、プロバイダーに走らせてもらう。
装置一式を持っているのはプロバイダーだ。パラメータはプロバイダーのハードウェア上にあり、モデルプロバイダーへのリクエストのたびに、ハーネスがネットワーク越しにトークンを送って予測を受け取る。そのため、モデルやハーネスのせいにされがちな問題の一群は、実はここに住んでいる。レート制限、能力の低下、障害はすべてプロバイダー側の話だ。セッションの途中でエージェントが止まったり、どのターンでもエラーになったりするときは、何よりも先にプロバイダーのステータスページを見る価値がある。
商業的な条件を決めるのもプロバイダーだ。入力トークンと出力トークンの単価、プレフィックスキャッシュの割引、そしてそもそもどのモデルが使えるか。なお、プロバイダーとモデルの作り手が別の会社であることもある。Bedrock、Vertex、OpenRouter は他社のモデルを提供している。
ローカルのプロバイダーは、能力と引き換えに制御を得る。自前のハードウェアに載るモデルは最前線のものよりずっと小さいが、データはマシンの外に出ず、トークンごとの請求も発生しない。
使い方:
「エアギャップ環境の顧客向けに、これをオフラインで動かせる？」
「モデルプロバイダーをローカルのものに差し替えればいい。先方のマシンで Ollama か llama.cpp を動かす。ハーネスは気にしないよ、叩くエンドポイントが変わるだけだ」
ハーネス (Harness)
モデルをエージェントに変える、その周辺のすべて。ツール、システムプロンプト、コンテキストウィンドウの管理、権限、フックが含まれる。Claude.ai と Claude Code は同じモデルの上で動くが、ハーネスが違うので振る舞いが違う。
モデル自体がやることは1つだけだ。テキストを受け取り、テキストを出す。ファイルを読むことも、コマンドを実行することも、前のターンを覚えていることもできない。それらをすべて供給するのがハーネスである。モデルプロバイダーへのリクエストごとにコンテキストを組み立て、モデルが求めたツール呼び出しを実行し、ツール結果を戻し、セッションの履歴を保存し、危ない操作の前に許可を求め、いつコンパクションするかを決める。エージェントループ — モデルが提案し、ハーネスが実行し、また繰り返す — を回しているのはハーネスだ。
これは診断に効く。2つの製品の間で、あるいは昨日と今日とで振る舞いが違うとき、変数はモデルでないことが多い。ハーネスだ。システムプロンプトの違い、ツールの構成の違い、権限のデフォルトの変更、コンテキスト管理の戦略の変更は、どれもモデルを一切変えずに振る舞いを変える。設定の大半が置かれる場所もハーネスである。AGENTS.mdファイル、権限設定、フックは、モデルではなくハーネスへの指示だ。
例: Claude Code、Cursor、Codex CLI。そして Claude.ai — こちらはコーディング用ではなくチャット用のハーネスだ。
使い方:
「同じモデルなのに、なんで Claude Code はファイルを編集して、Claude.ai は質問に答えるだけなの？」
「ハーネスが違うんだ。Claude Code にはファイルシステムのツールがあり、システムプロンプトも違い、権限のレイヤーもある。ここではモデルは変数じゃない」
モデルプロバイダーへのリクエスト (Model provider request)
ハーネスからモデルプロバイダーへの1往復。ハーネスが現在のコンテキストを送り、プロバイダーが応答を1つ返す（ツール呼び出しか、最終的な答えのどちらか）。エージェントがツールを呼べば、ユーザーのメッセージ1通から多数のリクエストが生まれる。ツール結果のたびに次のリクエストが発生するからだ。
リクエストは毎回すべてを運ぶ。システムプロンプト、それまでの会話全体、すべてのツール結果だ。モデルはステートレスなので、プロバイダーはリクエスト間に何も保持しない。40回目のリクエストは、39回目が送ったものにツール結果を1つ足したものを再送する。この反復を経済的に成立させるためにプレフィックスキャッシュがある。
リクエストは課金の単位でもある。入力トークン、出力トークン、キャッシュの割引は、すべてリクエスト単位で数えられる。何気ない質問が驚くほど高くつくのはこのためだ。コストはあなたのメッセージの長さに比例するのではなく、リクエストの回数と、その1回ごとが運ぶコンテキストの大きさの積に比例する。
リクエストとターンは区別しておく価値がある。ターンはあなたとのやり取り1回であり、「落ちているテストを直して」という1ターンは、リクエストの連鎖として展開する。
| リクエスト | モデルが返すもの | ハーネスの動き |
|---|---|---|
| 1 | ツール呼び出し: テストを実行 | 実行し、失敗の出力を追記 |
| 2 | ツール呼び出し: テストファイルを読む | ファイルの中身を追記 |
| 3 | ツール呼び出し: ソースを読む | ファイルの中身を追記 |
| 4 | ツール呼び出し: ソースを編集 | 編集を適用し、結果を追記 |
| 5 | ツール呼び出し: もう一度テスト実行 | 実行し、成功の出力を追記 |
| 6 | 最終回答:「直った、テストは通る」 | あなたに表示 |
1ターンで6リクエスト。しかも毎回コンテキスト全体を再送している。トークンがどこへ消えたのか気になったら、ターンではなくリクエストを数えること。
使い方:
「質問1つで4万トークン使ったの？」
「ツール呼び出しを見て。grep が12回、read が8回、編集が4回。ツール結果のたびに次のモデルプロバイダーへのリクエストが走るし、そのたびにセッションのプレフィックス全体が再送される」
入力トークン (Input tokens)
モデルプロバイダーへのリクエストごとにハーネスが送るトークン — システムプロンプト、会話の履歴、ツール結果、つまりモデルが書き始める前に読むものすべて。出力トークンより処理コストが低いため、安い単価で課金される。
AIコーディングでは、請求額の大半を入力トークンが占める。モデルはステートレスなので、ターンごとにセッション全体が入力として再送される。最初のメッセージ、すべての応答、それ以降のすべてのツール結果だ。50ターン目の入力には、それまでの49ターンが入っている。1回のリクエストが生む出力は数百トークンでも、積み上がった履歴として10万トークンを再送していることがある。
このコストを下げるのがプレフィックスキャッシュだ。以前のリクエストと完全に一致する履歴は、定価の入力ではなく安価なキャッシュトークンとして課金される。それでも入力コストが痛いときの対処は、再送される量そのものを減らすこと — タスクの合間にクリアするか、コンパクションすることだ。
使い方:
「請求は高いのに、エージェントはほとんど何も書いていない」
「入力トークンだよ。ターンのたびにセッション全体が再送される。プレフィックスキャッシュがなければ、リクエストごとに履歴の代金を払い直すことになる」
出力トークン (Output tokens)
モデルが生成して返すトークン。生成により多くの計算量がかかるため、入力トークンより高い単価で — よくあるのは5倍前後で — 課金される。
モデルが書くものはすべて数えられる。あなたが読む文章、出力されたコード、ツール呼び出し、そして答える前に行う拡張思考もだ。最後のものは意外に思われやすい。推論のトークンは、ハーネスが表示しない場合でも出力として課金され、エフォートを上げればその消費が増える。
出力トークンはセッションのテンポも決める。モデルは入力を素早く読むが、出力は1トークンずつ生成する。だからターンが遅いと感じるときは、ほぼ必ず入力を読んでいるのではなく出力を書いている。待たされているなら、たいてい長い答えが来る。
使い方:
「入力は小さいのに、リファクタのセッションでクレジットがどんどん減る」
「エージェントがパッチではなくファイル全体を書き直しているね。出力トークンは入力の5倍くらいの単価だから、差分の編集を出すようにさせれば請求は下がる」
プレフィックスキャッシュ (Prefix cache)
連続するモデルプロバイダーへのリクエストが、共通する先頭部分の再処理を省けるようにするプロバイダー側の保存領域。リクエストの先頭が直近のものと一致すれば — 同じシステムプロンプト、ある地点までの同じ履歴 — プロバイダーは以前の処理結果を再利用し、そのトークンをずっと安い単価のキャッシュトークンとして課金する。
キャッシュが効くのは、セッションが末尾に追記されていく形で伸びるからだ。リクエストのたびに履歴全体が入力トークンとして再送されるが（理由はその項目を参照）、普通のセッションでは履歴が変わるのは末尾だけだ。各リクエストは、前回のものに新しいメッセージが数個足されたものになる。プロバイダーは長い共通の先頭を一度だけ処理して結果を保存し、プレフィックスが終わったところから再開する。キャッシュがなければ、50ターンのセッションは1ターン目の再処理に50回分の代金を払うことになる。
キャッシュには有効期限もある。エントリが温かいままでいる時間はモデルプロバイダーごとに違い、たいていは時間単位ではなく分単位だ。その窓を超えてセッションを放置すると、次のリクエストは一度だけ定価でプレフィックスを作り直し、その後またキャッシュが効き始める。これは主にハーネスを作る側の関心事で、利用者から見える影響は、長い休憩のあとのリクエストがその前より高くつく、という形で現れる。
使い方:
「セッションの途中で請求が跳ねたのはなぜ？」
「ハーネスがターンごとにシステムプロンプトへ現在時刻を差し込み始めたんだ。プレフィックスキャッシュは最初に変わったトークンで壊れるから、それ以降のリクエストは全部定価で課金された」
キャッシュトークン (Cache tokens)
プロバイダーが以前のモデルプロバイダーへのリクエストからキャッシュしていて、再処理せずに済む入力トークン。連続するリクエストが共通の先頭部分を持つとき、プロバイダーはプレフィックスキャッシュを通じて処理結果を再利用し、その部分をずっと安い単価で課金する。長いセッションを成立させているレバーであり、これがなければターンごとに履歴全体の代金を払い直すことになる。
これが効いてくるのは、セッションの課金の仕組みのせいだ。モデルはステートレスなので、リクエストのたびに会話全体 — システムプロンプト、すべてのメッセージ、すべてのツール結果 — が入力トークンとして再送される。50ターン目には、各リクエストが50ターン分の履歴を運んでおり、その全部に毎回定価を払うことになるはずだ。キャッシュはこの計算を変える。同一のプレフィックスとしてプロバイダーが既に処理したトークンはキャッシュトークンとして課金され、多くの場合その単価は入力の10分の1以下になる。長いセッションでは送るものの大半がキャッシュトークンになり、請求額が正気の範囲に収まる。
どこがキャッシュされ、どこがされないかは例で見るのが早い。各アルファベットは会話の内容のかたまりを表し、リクエストはそれまでの会話を毎回送る。
| リクエストが送るもの | キャッシュ | 定価で課金 | 理由 |
|---|---|---|---|
AB |
なし | AB |
最初のリクエスト。照合する相手がいない |
ABC |
AB |
C |
AB は前回のリクエストの完全なプレフィックス |
ABCD |
ABC |
D |
プレフィックスはまだ無傷 |
AXCD |
A |
XCD |
編集で B が X に変わり、そこで一致が途切れた |
キャッシュは特定の壊れ方をする。一致するのは完全なプレフィックスだけだ。会話の前のほうで何かが変われば — ハーネスが内容を並べ替えた、タイムスタンプが更新された、ファイルの表現が変わった — その地点から先はキャッシュが外れ、以降すべてが定価の入力として課金される。キャッシュは数分の無操作でも失効するので、長い中断のあとに再開したセッションは履歴の代金を一度払い直す。原因がはっきりしないままセッションのコストが跳ねたときは、使用状況レポートでキャッシュトークンと入力トークンを比べること。キャッシュが壊れていれば、まずそこに出る。
使い方:
「長いセッションのコストがきつい。リファクタ1回で8ドルだ」
「キャッシュトークンを見て。ハーネスがターンの合間にシステムプロンプトやファイルを並べ替えているなら、プレフィックスが壊れて毎回定価の入力を払い直していることになる」
セクション 2 — セッション・コンテキストウィンドウ・ターン
ステートレス (Stateless)
情報を先へ持ち越さないこと。モデルはモデルプロバイダーへのリクエストをまたいでステートレスであり、リクエストのたびにコンテキストウィンドウ全体が再送される。モデルにはそれ以外を見る手段がないからだ。エージェントは既定でセッションをまたいでステートレスで、新しいセッションは前のセッションの痕跡なしに空から始まる。ステートフルと対になる語。
モデル自体は恒久的にステートレスだ。パラメータは学習後に凍結され、推論時に何をしても変わらない。モデルはあなたの訂正から学ばないし、昨日同じことを言われたのを覚えてもいないし、あなたのことを知っていくわけでもない。会話がどれだけそう感じさせても、である。セッション内で感じる連続性はハーネスが作り出したものだ。ハーネスがやり取りの記録を保持し、リクエストのたびに再送している。モデルは会話を覚えているのではなく、読み直している。
実務上の帰結はこうだ。セッションをまたいで覚えていてほしいことがあるなら、エージェントが読み返す場所に書いておく必要がある。AGENTS.mdファイル、メモリシステム、引き継ぎ成果物はそのためにある。将来のセッションのコンテキストに読み込まれ、モデルが持たない記憶の代わりを務めるファイルだ。前に直したはずの間違いをエージェントが繰り返すとき、問うべきは「なぜ学習しなかったのか」ではなく — できないのだから — 「その訂正を、どこに書けば以降のすべてのセッションが読むのか」である。
使い方:
「クリアするたびに規約を忘れるのはなぜ？」
「モデルがステートレスだからだよ。新しいセッションは空から始まる。持ち越したいなら、AGENTS.md か、ハーネスがセッション開始時に読むメモリファイルに書いておいて」
コンテキスト (Context)
エージェントがいま参照できる関連情報。抽象名詞としての語であり、モデルが見る生の入力（それはコンテキストウィンドウ）でも、進行中の履歴（それはセッション）でもなく、 タスクに関係することのうちエージェントが知っていること を指す。「コンテキストに載せる」とはこの集合に含めること、「コンテキストエンジニアリング」とはそれを取捨選択する技芸のことだ。
3つの語はきれいに分かれる。
| 用語 | 何を指すか |
|---|---|
| コンテキスト | エージェントがいま持っている、タスクに関係する情報 |
| コンテキストウィンドウ | リクエストごとにモデルが見る、文字どおりのトークン列 |
| セッション | ハーネスが保存している進行中の会話 |
この区別が重要なのは、コンテキストが量ではなく質の尺度だからだ。コンテキストウィンドウがほぼ満杯でも、コンテキストが貧しいことはある。古いツール出力が数千トークン分あって、どれも目の前のタスクの話ではない、という状態だ。逆に、ほぼ空でもコンテキストが良いことはある。タスクの成否を決めるたった1つの型定義が入っている場合だ。
日々の失敗の多くはコンテキストに行き着く。エージェントが存在しないAPIをでっち上げたり、決定と矛盾したり、スキーマを当て推量したりしたとき、最初に問うべきは「そのとき何がコンテキストにあったか」だ。たいていは、必要な事実がそもそも載っていなかったか、注意の劣化に埋もれていたかである。対処は取捨選択だ。タスクに必要なものを載せ、必要でないものを入れない。
使い方:
「型に存在しないフィールドを作り続けるんだけど」
「型のファイルがコンテキストに入っていないね。呼び出し側を読んで推測している。先に定義を読み込ませよう」
コンテキストウィンドウ (Context window)
モデルプロバイダーへのリクエストごとにモデルが見るすべて。有限で、モデルごとに大きさが異なり、モデルが何かを知覚する 唯一 の面である。
中身は1本のトークン列だ。システムプロンプト、それまでの会話、ハーネスが戻したすべてのツール結果。その列に入っていればモデルは使えるし、入っていなければモデルはその存在を知らない。あなたのコードベースも、昨日編集したファイルも、3セッション前に出した指示もだ。ウィンドウの外にあるものは、何かに影響を与える前に、たいていはツール呼び出しを通じて中へ持ち込む必要がある。
有限であるということは、いっぱいになるということだ。ターンごとに追記されていき — あなたのメッセージ、モデルの応答、ツール結果 — 長いセッションはいずれ上限に当たり、コンパクションかクリアを強いられる。同時に、ウィンドウの中身は互いに競合する。1トークン載せればその分だけ残りが減り、必要でなかった内容もモデルの注意を占める。実務的な構えは、ウィンドウを予算として扱うことだ。タスクに必要なものを載せ、それ以外は外に置く。
避けるべき表現: 「メモリ」 — コンテキストウィンドウは作業中の状態であって、セッションをまたいで残らない。メモリはその上に載る別の概念だ。
使い方:
「モノレポ全体をプロンプトに貼ればいい？」
「コンテキストウィンドウは20万トークン。リポジトリの5分の1くらいだよ。タスクが触るファイルを選んで、残りはツール呼び出しの向こうに置いておこう」
ステートフル (Stateful)
情報を先へ持ち越すこと。セッションはターンをまたいでステートフルだ。セッションが進むほどコンテキストは溜まり、長いセッションがバカゾーンへ流れていくのはそのためである。エージェントは、情報を環境に永続化して将来のセッションの開始時に読み直すメモリシステムを足すことで、セッションをまたいでステートフルにできる。モデルは決してステートフルにならない。連続して見えるものはすべて、ハーネスがコンテキストを再投入しているだけだ。ステートレスと対になる語。
各レイヤーで状態がどこにあるかを並べる。
| レイヤー | ステートフルか | どうやって |
|---|---|---|
| モデル | 決してならない | パラメータは凍結。各リクエストに入っているものしか見えない |
| セッション | ターンをまたいで | ハーネスがすべてのメッセージとツール結果をコンテキストに追記する |
| ハーネス | セッションをまたいで | メモリファイル、AGENTS.md、引き継ぎ成果物 — 書き出して、後で読み直す |
| 環境 | 常に | セッションが動いていようといまいと、ファイルは残る |
どのレイヤーのステートフルさも、1つ下の層に保存されたものを読み直すことで作られている。セッションが連続して感じられるのは、ハーネスがメッセージ履歴をステートレスなモデルへ再送しているからであり、エージェントがセッションをまたいで覚えているのは、ハーネスが環境からファイルを読み直しているからだ。モデル自身に状態が保存されることは一度もない。
状態は常に欲しいものとは限らない。持ち越されたものはすべてその後に影響するので、セッションの早い段階で立てた誤った前提も一緒に運ばれる。クリアは、セッションの状態を意図的に捨てて、書き出されているものからやり直す行為だ。
使い方:
「昨日の設定の好みを覚えていた。これはモデルが学習したってこと？」
「違うよ。ハーネスがそれをメモリファイルに書いて、セッション開始時に読み直したからエージェントがステートフルなだけだ。モデル自体は昨日のことを何も見ていない」
エージェント (Agent)
ツール、システムプロンプト、コンテキストウィンドウでハーネス化され、ユーザーとターンを交わすモデル。Claude Code はエージェントだ。Cursor もエージェントだ。Claude.ai もエージェントだ。 あなたが実際に話しかけている相手がエージェントであり、目的に合わせて構成された、動いている状態のモデルである。
この辞書の他の語と違い、「エージェント」は機械的な部品の名前ではない。モデルはパラメータのファイルであり、ハーネスは指し示せるソフトウェアだ。エージェントはそのどちらでもなく、あなたが話しかけている単位である。人はAIを絶えず擬人化するが、その擬人化された単位がエージェントだ。仕事を任せる相手であり、あなたのメッセージを読んで答える相手であり、「またビルドを壊した」の「あいつ」である。エージェントが何かをしたと言うとき、実際にはモデルとハーネスの組み合わせがやったことを指しているが、その組み合わせを1人の行為者として扱っている。
考え方自体は今回のAIの波より古い。ソフトウェアエージェント — 目標を委ねると、あなたの代わりに動くプログラム — は、AIと同じくらい長く存在してきた概念だ。
避けるべき表現: 「AI」「ボット」 — 曖昧すぎて、パラメータの話なのかハーネス化されたものの話なのかが隠れてしまう。
使い方:
「移行作業はどのエージェントを使ってる？」
「ローカルで Claude Code、UIの作業は Cursor。下のモデルは同じで、ハーネスが違うだけだよ」
システムプロンプト (System prompt)
モデルプロバイダーへのリクエストすべての先頭にハーネスが付ける指示 — エージェントの常設ブリーフだ。自分が何者か、どう振る舞うか、どのツールを呼べるか、どの規約に従うか。セッションを通じて変わらないのが普通である。
システムプロンプトを書くのはあなたではなくハーネスのベンダーで、コーディング用のハーネスでは大きい。振る舞いのルール、ツールの説明、例外的なケースの扱いで数万トークンになることも多く、それがターンごとに入力トークンとして課金される。あなた自身の常設の指示もこれに相乗りする。AGENTS.mdのようなファイルはセッション開始時にシステムプロンプトの隣に読み込まれるので、モデルはあなたのメッセージを見る前に、ベンダーのブリーフとあなたのブリーフをまとめて読むことになる。
すべてのリクエストで同一なので、これはプレフィックスキャッシュの先頭を形成する。ハーネスが途中で編集せず、セッションを通じて固定しておくのはこれも理由の1つだ。
モデルは、ユーザーのメッセージよりシステムプロンプトを優先するように学習されている。だからエージェントが頼んでもいない規約に固執したり、どうしても直らない形式で出力したりするとき、それはたいていシステムプロンプトに従っており、あなたのメッセージが議論に負けている。カスタマイズ可能なハーネスもある。システムプロンプトへの完全なアクセスを与えてくれるので、エージェントが実際に何を言われているのかを読み、変更できる。
使い方:
「同じモデルの2つのハーネスで、同じプロンプトなのに振る舞いが全然違う」
「システムプロンプトが違うんだ。片方は簡潔なコード編集向けに、もう片方は説明向けに調整されている。分岐はそこ、あなたのメッセージが届く前の段階にある」
セッション (Session)
エージェントとのやり取りの、ひと区切りの実行。空から始まり、メッセージ、ツール結果、読んだファイルが溜まっていき、クリアされるか、閉じられるか、コンパクションされて新しいセッションになったところで終わる。コンテキストウィンドウを 満たしていく ものがセッションだ。コンテキストウィンドウが箱なら、セッションはそこにゆっくり詰まっていく中身にあたる。1つのコンテキストウィンドウに収まらない大きさの仕事は、複数のセッションに分ける必要がある。
セッションのメッセージ履歴が、エージェントの作業記憶である。モデルはステートレスなので、覚えているように見えるものはすべて — あなたが何を頼んだか、テストが何と言ったか、3ターン前に何を決めたか — メッセージ履歴の中にあり、モデルプロバイダーへのリクエストのたびに再送されている。セッションに入っていないものは、エージェントにとって存在しない。
その記憶はセッションとともに終わる。新しいセッションは無から始まる。昨日のセッションの終わりにはコードベースをよく理解していたエージェントも、今朝は何も知らない。残るのはファイルシステムだ。あるセッションで書かれたファイルは次のセッションで読める。引き継ぎ、メモリシステム、AGENTS.mdはそこに依っている。
セッションをどこで終えるかはあなたが決める。セッション内のすべてはその後のすべてのターンに影響するので、無関係なタスクを同じセッションで片付けると、残りかすが次の答えに色を付ける。1セッション1タスクにしておくとコンテキストが関連したものに保たれるし、タスクを終えた時点はクリアの自然な区切りになる。
使い方:
「1つのセッションはどれくらい保つ？」
「仕事による。焦点の定まったリファクタは、終わりの見えない調査より長く冴えたままだよ。セッションが膨らんできたら、押し切らずに引き継ぐかコンパクションすること」
ターン (Turn)
ユーザーのメッセージ1通と、それに応じてエージェントがユーザーに返すまでに行うすべて。モデルプロバイダーへのリクエストを1回以上含み、ツールを呼べば何回も含む。確認の質問はターンを閉じ、あなたの返信が次のターンを開く。階層はセッション > ターン > モデルプロバイダーへのリクエスト だ。
ターンに名前を付ける価値があるのは、その長さを決めるのがあなたではなくエージェントだからだ。あなたはメッセージを1通渡し、エージェントは返すまでに何回ツールを連ねるかを決める。ターンは一文の回答のこともあれば、読んで、編集して、テストを走らせる20分のこともある。これは同じ性質を2つの角度から見たものだ。長いターンはAFKでの作業を可能にするが、同時に、見ていないところで物事が狂う場所でもある。エージェントが返してきたときには、あなたの意図から遠く離れているかもしれない。
ターンは舵を切る自然な単位でもある。ターンの内側はすべてあなた抜きで進み、方向を変えられるのはターンとターンの間だ。多くのハーネスはこれを和らげている。途中で割り込んでエージェントを止めて方向を変えられるし、作業中にメッセージを書いておけばターンが終わったところで読まれる。ターンの着地点に何度も不満を覚えるなら、たいていの対処はターンを小さくしてもらうことだ。まず計画を、次に1ステップずつ。自律性を差し出す代わりに、舵を切れる隙間を増やす。
使い方:
「1ターンに2分かかったの？」
「そのターンの中でツール呼び出しを14回している。1回ごとに別のモデルプロバイダーへのリクエストだよ。エージェントが返してくるまでにレイテンシが積み上がる」
セクション 3 — ツールと環境
環境 (Environment)
エージェントが働きかける世界 — ハーネスの外側にあって、エージェントがツール結果を通じて知覚し、ツール呼び出しを通じて変更するもの全般。ハーネスはエージェントを 動かす もので、環境はエージェントが その中で働く 場所だ。AGENTS.mdのようなファイルは環境にあり、それをコンテキストウィンドウへ読み込むのがハーネスである。最も一般的な環境はファイルシステムだが、それだけではない（データベース、リモートAPI、ブラウザのセッションも環境になりうる）。
エージェントは、見にいったときにしか環境を見ていない。環境について知っていることはすべてツール結果として届いたものなので、その像はスナップショットの集まりであり、それぞれ撮った瞬間には正しい。エージェントが読んだ後にファイルが変わると — あなたが手で編集した、ビルド手順が再生成した — 何かのきっかけで読み直すまで、エージェントは古い写しから推論し続ける。もうそんな形をしていないファイルについてエージェントが自信満々に語るとき、たいていこれだ。環境が動いたのに、スナップショットが動いていない。
環境は残り続ける層でもある。常にステートフルな唯一の層だ。セッションのコンテキストはセッションが終われば消えるが、環境に書かれたファイルは次のセッションが読めるように残る。メモリシステム、引き継ぎ成果物、AGENTS.md はそこに依っている。明日もエージェントに知っていてほしいことは、最終的に環境に置かれる必要がある。
環境の大きさを決めるのはあなただ。サンドボックスは環境を狭め、エージェントが届く範囲を制限する。ツールを足せば環境は広がり、データベースやAPIが届く範囲に入る。境界の内側がエージェントの知覚し変更できるもので、外側のものはエージェントにとって存在しない。環境がエージェントの仕事をどれだけ支えられるように整えられているかが、そのコードベースのAXである。
避けるべき表現: ランタイムやハーネス自体を指して「環境」と言うこと — ハーネスは包む側、環境は作業場だ。
使い方:
「エージェントがステージングDBのスキーマを見られない」
「環境に繋ごう。ステージングに読み取り専用でスコープした psql ツールを渡せばいい。ハーネスは問題ない、働きかける対象がないだけだ」
ファイルシステム (Filesystem)
エージェントが読み書きし、その中でコマンドを実行するファイルとディレクトリの木 — コーディングエージェントにとって既定の環境の形だ。AGENTS.md、スキル、ソースコード、ビルドスクリプト、ツールの設定は、すべてファイルシステムに置かれる。ハーネスが「あなたのプロジェクトで起動する」とき、それはエージェントをファイルシステムに向けているということだ。
エージェントがそこに触れるのはツール呼び出しを通じてだけだ。ファイルを読む、書く、シェルコマンドを実行する。ディスク上のものは、ツール呼び出しが読み込むまでコンテキストウィンドウに入らない。だからこそ、ウィンドウよりはるかに大きいリポジトリでも作業できる。ファイルシステムがすべてを保持し、コンテキストは今のタスクが読んだものだけを保持する。ハーネスによっては、カレントディレクトリのファイル名を既定でコンテキストウィンドウに読み込むものもある。中身ではなく木構造だけで、これはコンテキストポインタとして働く。エージェントは何が存在するかを見て、必要なファイルを読む。
そして、それはあなたと共有されている。エージェントが編集するファイルは、あなたがエディタで開き、gitで差分を見るファイルと同じものだ。ファイルシステムは、エージェントの仕事をレビューする共通の作業場である。
使い方:
「なんで AGENTS.md を拾ってくれないの？」
「別のファイルシステムに対して動いているね。サンドボックスがプロジェクトルートではなく親ディレクトリをマウントしている。ハーネスの向き先を直そう」
ツール (Tool)
エージェントが呼べるようにハーネスが公開する関数 — Read、Write、Bash、Search など。ツールは、エージェントが環境を知覚し、環境に働きかける手段だ。ツール結果を通じてしか環境を見られないし、ツール呼び出しを通じてしか変更できない。ツール呼び出しは1回ごとにモデルプロバイダーへのリクエストを追加で消費する。次に何をするか決める前に、結果をモデルへ戻す必要があるからだ。
多くのコーディングエージェントが最初から持っているツール。
| ツール | 何をするか |
|---|---|
| Read | ファイルの中身をツール結果として返す |
| Write | ファイルシステム上でファイルを作成・編集 |
| Bash | シェルコマンドを実行し、その出力を返す |
| Search | コードベース全体からパターンに一致するファイルや文字列を探す |
ツールは3つのもので定義される。名前、何をするかの説明、パラメータのスキーマだ。ハーネスはこの定義をリクエストのたびにモデルへ送り、モデルは他のすべてと同じやり方で — トークンを書くことで、この場合は引数付きの構造化された呼び出しを書くことで — ツールを選ぶ。モデル自身は何も実行しない。ハーネスが呼び出しを読み、関数を実行し、結果を返す。
エージェントに何ができるかは、ツールの一覧が決める。能力の高いモデルでもツールが狭ければ狭いエージェントになる。持っているもので何とかしようとするからだ。エージェントが Bash に強く依存するのはこのためで、シェルという1つのツールがシステムの大半に手を届かせる。ある能力をきれいに与えたいなら、そのためのツールを足すこと。ハーネスの外からツールを差し込む標準がMCPだ。
ツールの定義はリクエストごとにコンテキストを占めるので、ツールが多いと1つも呼ばないうちから固定費がかかる。しかも説明の似たツールが並ぶと、モデルは正しいものを選ぶのが下手になる。
使い方:
「エージェントから直接ステージングに問い合わせできる？」
「ステージングに読み取り専用でスコープした psql ツールをハーネスに足そう。そのためのツールがないと、エージェントはファイルシステムの外に対して盲目だよ」
ツール呼び出し (Tool call)
ツールの名前と引数を並べたモデルの出力 — 中身はただの構造化テキストだ。それ自体は何もしない。読んで実行するのはハーネスの仕事である。1回のモデルプロバイダーへのリクエストでモデルが生成する。
ツール呼び出しのライフサイクル。
| ステップ | 担当 | 何が起きるか |
|---|---|---|
| 1 | モデル | システムプロンプトの説明から、どんなツールがあるか知る |
| 2 | モデル | 呼び出しを出力する — ツール名と引数、たいていJSON — そこで止まる |
| 3 | ハーネス | 呼び出しを解釈し、許可モードに照らして確認する |
| 4 | ハーネス | 許されていれば実行する |
| 5 | ハーネス | 結果を次のリクエストでツール結果として返す |
エージェントの作業1ターンは、たいていこの往復が何度も連なったものになる。
この呼び出しも他のすべてと同じく次トークン予測で生成されるので、モデルの出力が間違いうるのと同じように間違いうる。存在しないパス、そのコマンドにないフラグ、正しくはないがもっともらしい引数。ハーネスが実行するのは書かれたものであって、意図されたものではない。打ち間違えたパスは丁寧にエラーになってはくれず、別のファイルを編集する。
使い方:
「テストを実行したと言っているのに、ファイルのタイムスタンプが変わっていない」
「やり取りの記録を見て。実際にツール呼び出しを出したのか、それとも実行したと書いただけなのか。モデルは呼び出しを作るけど、ハーネスが実行していなければ何も起きていない」
ツール結果 (Tool result)
ツール呼び出しを実行したあとにハーネスが返すもの — ファイルの中身、コマンドの出力、エラー。エージェントが環境を見る唯一の窓だ。 次の モデルプロバイダーへのリクエストでモデルまで戻り、そこでモデルが次の行動を決める。ツール呼び出しとツール結果は同じやり取りの両端で、どちらも1つのターンの中にある。
ツール結果のライフサイクル。
| ステップ | 担当 | 何が起きるか |
|---|---|---|
| 1 | ハーネス | ツール呼び出しを実行する — コマンドを走らせ、ファイルを読む |
| 2 | ハーネス | 結果を捕まえる。出力、中身、あるいはエラー |
| 3 | ハーネス | それをメッセージとしてコンテキストに追記する |
| 4 | ハーネス | 次のモデルプロバイダーへのリクエストでコンテキスト全体を送る |
| 5 | モデル | 結果を読んで決める。次のツール呼び出しか、最終的な答えか |
結果はそのセッションの残りの間ずっとコンテキストに残る。コーディングセッションのコンテキストは、たいていツール結果が大半を占める。読んだファイル、走らせたテスト、実行した検索がすべてそのまま入り、役に立たなくなってからも長くトークンを占め続ける。大きな結果がいくつかあるだけで — 冗長なテストログ、丸ごと読み込んだ生成ファイル — 会話そのものより速くセッションをコンテキストウィンドウの縁へ押しやることがある。
モデルに見えるのは結果だけなので、その背後にある環境を確かめる手立てはない。出力が途中で切れていても、コマンドが黙って失敗していても、ハーネスが中身の代わりにエラーを返していても、モデルは与えられたものから推論する。エージェントが持っているシステムの像がおかしいと感じたら、見るべきはツール結果だ。記録のどこかに、あなたが真実だと知っていることと違うことを言っている結果がある。
使い方:
「そのファイルが空であるかのように推論しているんだけど」
「ツール結果が中身ではなく権限エラーとして返っているね。モデルはそのエラー文字列しか見ていない。ファイルを見る手段は他にないんだ」
MCP
Model Context Protocol. 外部のツールサーバーをハーネスに差し込むためのプロトコルで、ハーネスに同梱されている以外のツールをエージェントに与える仕組みだ。エージェントが「MCPを呼ぶ」ことはない。呼ぶのはツールであり、そのツールをハーネスがたまたまMCPサーバーから得ていた、というだけである。リソース（読み取り専用のデータ）やプロンプト（再利用できるテンプレート）も提供できるが、主な用途はツールの提供だ。
このプロトコルが解いているのは統合の問題だ。標準がなければ、ハーネスごとに自前の Linear 連携、自前の Slack 連携、自前のデータベース連携を書き、別々に保守することになる。MCPがあれば、統合はサーバーとして一度書けばよく、MCP対応のどのハーネスからも使える。ハーネスがサーバーに接続し、サーバーが提供するツールを申告し、それらが組み込みのツールと並んでエージェントから使えるようになる。
代償はコンテキストで支払われる。サーバーが申告するツールは定義として届き — 名前、説明、パラメータのスキーマ — モデルは知っているツールしか呼べない。素朴なやり方では、すべての定義を最初にコンテキストウィンドウへ読み込む。気前のよいサーバーをいくつか入れると、あなたが1文字打つ前に、セッションは数千トークンのツールスキーマから始まる。そのタスクでは一度も使わないツールに注意の予算を払うことになる。
これを緩和するために、ツール検索を備えるハーネスが増えている。定義一式ではなく、利用可能なツールへのコンテキストポインタだけをコンテキストに置き、エージェントが名前や目的でツールを検索し、必要になったときに定義を読み込む。使っているハーネスがこれをしないなら初期コストはそのままかかるので、プロジェクトが実際に必要とするサーバーだけを有効にする価値がある。
使い方:
「エージェントに Linear のチケットを読ませたい」
「Linear の MCP サーバーを使うようにハーネスを設定しよう。Linear のAPIをエージェントが呼べるツールとして公開してくれる。自前のツールラッパーを書かずに済む」
許可リクエスト (Permission request)
事前に承認されていないツール呼び出しを実行する前に、ハーネスがユーザーに見せるもの。モデルがツール呼び出しを出すと、ハーネスはすぐに実行せず、いったん止まって尋ねる。承認すれば実行され、拒否すればハーネスがその拒否をツール結果としてモデルに返す。危険な操作や慎重を要する操作について、ハーネスが人間をループに入れる仕組みである。
許可リクエストのライフサイクル。
| ステップ | 担当 | 何が起きるか |
|---|---|---|
| 1 | モデル | ツール呼び出しを出す |
| 2 | ハーネス | 許可モードと保存済みの承認に照らして確認する |
| 3 | ハーネス | 事前承認済みならすぐ実行。そうでなければ止まってリクエストを表示 |
| 4 | ユーザー | 1回だけ承認、このセッションの間ずっと承認、あるいは拒否 |
| 5 | ハーネス | 呼び出しを実行するか、拒否をツール結果として返す |
リクエストを拒否することは、エージェントの舵を切ることでもある。モデルは他のツール結果と同じように拒否を読み、それに反応する。別のやり方を試すか、どうしてほしいかを尋ねてくる。多くのハーネスは拒否にメッセージを添えられるので、リクエストが操舵点になる。「そうじゃなくて、マイグレーションスクリプトを使って」という一言が、モデルが次の行動を決めるまさにその瞬間に届く。
代償は、リクエストのたびにあなたを同期的に待つことだ。答えるまでエージェントは止まったままで、見ているときは問題ないが、見ていないときは問題になる。ひっきりなしにリクエストを出すエージェントはAFKで働かせられない。そのダイヤルが許可モードだ。どの呼び出しを自由に走らせ、どれを先に尋ねさせるか。理想を言えば、サンドボックスで安全にして自由な側を広げるのがよい。
使い方:
「会議に出ている間、10分間ずっと許可リクエストで止まっていた」
「それが人間をループに入れるコストだね。安全なツールを事前承認して、本当に危ない呼び出しでだけリクエストが出るようにしよう」
許可モード (Permission mode)
エージェントモードのうち、権限を制御する部分 — どのツール呼び出しが許可リクエストを出し、どれが自動で走るかを決める。ハーネスが振る舞いの指示まで束ねるようになる前、モードという仕組みが本来担っていた役割だ。
ハーネスはこのモードを段階として用意している。
| モード | 読み取り | 書き込みとシェル | よくある用途 |
|---|---|---|---|
| 読み取り専用 / plan | 自動 | 禁止 | 調査、計画、レビュー |
| デフォルト | 自動 | 都度確認 | 日々の、見ている状態での作業 |
| 自動編集 | 自動 | 編集は自動、シェルは確認 | 信頼できるリポジトリ、機械的な変更 |
| 「Yolo」/ 全自動 | 自動 | 自動 | サンドボックス、AFKの実行 |
どの段に立つかは安全性と中断のトレードで、失敗は両方向に体感できる。きつすぎると、あなたがボトルネックになる。無害な読み取りのたびにエージェントが数秒ごとに止まり、あなたは惰性で承認を押し、やがて承認が何も意味しなくなる。この判子押しは両方の悪いところ取りで、中断だけがあって保護がない。緩すぎると、先に見ておきたかったファイル編集やコマンド実行が済んでしまう。
緩い側が最も正当化しやすいのはサンドボックスの中だ。まずいツール呼び出しの被害範囲が閉じ込められる。その外では、読み取りは自動承認し、取り返しのつかない操作には人間をループに残す、というあたりに落ち着く人が多い。
使い方:
「grep のたびに止まって、AFKの実行が台無しになった」
「読み取り専用のツールについては許可モードを緩めて、書き込みとシェルでは確認を残そう。調査中のセッションで出る許可リクエストは、ほとんどノイズだよ」
エージェントモード (Agent mode)
実行時にエージェントの動き方を決めるプリセット — 許可モードと、システムプロンプトに差し込まれる振る舞いの指示を束ねたものだ。例を挙げると、危険な呼び出しで確認を出すデフォルト、編集を止めて調査へ向かわせる plan モード、編集を自動承認する accept-edits モード、すべてを自動承認する bypass permissions モード（口語では YOLO モード）。セッションの途中で切り替えられる。
モードを単なる権限設定と分けるのは、この束ね方だ。許可モードはゲートにすぎず、どのツール呼び出しを通すかを決める。ゲートだけだと、編集したいのにできないエージェントができあがる。書き込みを提案し、止められ、別の道を探す。差し込まれる指示はその「したい」を取り除く。plan モードは編集を止めるだけでなく、いまは計画の段階だとエージェントに伝えるので、ゲートに体当たりする代わりに、読み、尋ね、提案する。ゲートと舵が同じ方向を向く。
実際には、タスクの中で信頼が変わるのに合わせてモードを変える。1つのタスクがいくつものモードを通ることもある。進め方をまだ形にしている間は plan モード、最初の繊細な編集は確認付きのデフォルト、エージェントが変更を理解していると示したら accept-edits、サンドボックスの中でAFK実行するなら bypass。モードの変更にコストはない。会話はそのままの位置で続き、権限と指示だけが新しくなる。中身を読まずにすべての確認を承認しているなら、モードは実際の信頼よりきつく設定されている。編集を却下し続けているなら、緩すぎる。
ベンダーごとの呼び方: Claude Code は「permission modes」、Codex は「approval modes」と呼ぶ。どちらも振る舞いを束ねるようになる前からある呼称だ。
使い方:
「計画だけ欲しいのに、ファイルを編集し続ける」
「plan モードに切り替えて。書き込みを止めて調査に留まるよ」
「あとでやるAFKの実行では？」
「bypass モードで。ただしサンドボックスの中だけ」
サンドボックス (Sandbox)
エージェントがその中で動く、隔離された環境 — コンテナ、VM、使い捨てのファイルシステム、権限を絞ったシェルなど。エージェントの操作の被害範囲を限定する。破壊的なコマンドを実行しても、悪意のあるものを取ってきても、被害は閉じ込められる。AFKを実用にする安全の土台だ。
サンドボックスと許可モードは、同じ問題を反対側から解いている。権限は操作が走る前に尋ね、サンドボックスは走ってしまった操作が届く範囲を限る。権限はあなたがループの中にいることを要求し、確認のたびに中断が入るので、ひっきりなしに尋ねるセッションはほとんど自律していない。サンドボックスは注意の代わりにインフラを支払う。隔離が強いほど、尋ねるべきことは減る。
隔離には段階がある。
| 段階 | 何であるか | 何を閉じ込めるか |
|---|---|---|
| 制限付きシェル | コマンドごとのOSレベルの封じ込め | プロジェクト外への書き込み、ネットワーク接続 |
| コンテナ | まっさらなファイルシステム、認証情報なし、使用後は破棄 | エージェントが自分のマシンにしたこと全部 |
| VM / クラウド | 完全に別のマシン。ハーネスが用意することも多い | カーネルレベルの脱出を含めてすべて |
どのサンドボックスも閉じ込められないもの: 正当な経路で外へ出ていく操作だ。あなたのgit認証情報を持つエージェントはpushできるし、ネットワークがあれば本番のAPIを叩ける。隔離をどれだけ厚くするかを決める前に、何が境界を越えるのかを決めること。
使い方:
「一晩bypass-permissionsで走らせたいけど、まだ踏み切れない」
「サンドボックスに入れよう。まっさらなコンテナ、認証情報のマウントなし、外向きのネットワークなし。最悪でも自分のファイルシステムを吹き飛ばすだけで、コンテナを捨てれば終わりだ」
セクション 4 — 失敗のかたち
追従 (Sycophancy)
自信たっぷりに同意してくるモデルの出力。原因は学習にある。モデルは人間が好んだ答えを優遇するように形作られており、人間は「あなたは間違っている」と言われるより同意されるほうを好みやすい。だからモデルは、同意すれば報われると学んだ。その同意が正しくないときでもだ。
こういう形で現れる:
- 押し返しに折れる — 「本当に？」と言うと、正しかった答えを撤回する。
- だめな入力を褒める — 分析する前に、壊れた計画を素晴らしいと同意する。
- 偏った枠づけ — あなたが書いたと匂わせるとレビューは好意的に、他人が書いたと匂わせると否定的に傾く。同じ成果物なのに評価が違う。
- 模倣 — あなたの間違いを、追認としてそのまま返してくる。
見分けるテスト: あなたの誘導がなくても、モデルは同じことを言っただろうか。変わったのがあなたの口調や枠づけだけなら、それは分析の変化ではなく追従だ。
対処: 自分の好みを隠すこと。プロンプトを中立に書く。「このコードは良い？」ではなく「このコードをレビューして」。
避けるべき使い方: たまたま自分にとって都合のよい間違った答えを何でも「追従」と呼ぶこと。見分けるテストを通さない限り、この語は「間違い」以上の価値を持たない。
使い方:
「リファクタの計画を良さそうだと言われたのに、『本当に？』と聞いたら全部撤回された」
「典型的な追従だね。あなたが自信ありげだったから同意して、疑わしげだったから折れた。計画の質は変わっていない、変わったのは口調だ。クリアして、どちらの匂わせもなしに聞き直してみて」
ハルシネーション (Hallucination)
自信をもって間違っているモデルの出力。原因も対処も異なる2つの種類がある。
| 種類 | 何がまずいのか | 原因 | 対処 |
|---|---|---|---|
| 事実性 | 世界についての事実を作る・間違える — 存在しない関数、誤ったAPIシグネチャ、架空の出典 | パラメトリック知識の欠落。知識カットオフより後が多い | 正しいコンテキスト由来の知識を載せる |
| 忠実性 | 読み込まれているコンテキスト、ユーザーの指示、自分自身の先の推論から出力がずれる | 注意の劣化。バカゾーンで悪化する | クリアかコンパクション |
次トークン予測は、背後の事実が本物かどうかに関係なく流暢な出力を作る。モデルには「自分が知らない」という内部の信号がないので、でっち上げたメソッドも正しいメソッドと同じ確信に満ちた調子で出てくる。ハルシネーションによるコードは構造上もっともらしい。そのAPIが存在したなら こう見えるはず の形をしているからだ。だからこそ流し読みのレビューをすり抜け、実行して初めて壊れる。
どちらの種類を見ているのかは把握しておく必要がある。片方の対処がもう片方を悪化させるからだ。事実性は知識が足りていない状態で、対処はコンテキストを足すこと — ドキュメント、型定義、そのファイル。忠実性は知識はあるのに注意の競争に負けている状態で、対処はコンテキストを減らすことだ。忠実性を事実性と誤診してドキュメントを追加で貼ると、コンテキストが膨らんでずれはさらに悪化する。エージェントが何かを間違えたら、どちらの問題かを決める前に、正しい情報がすでにコンテキストにあったかどうかを確認すること。
避けるべき使い方: 「間違い」の同義語としての「ハルシネーション」 — 種類を名指ししなければ、この語に診断上の価値はない。
使い方:
「スキーマに parseAsync メソッドがあるとハルシネーションを起こした」
「事実性？ それとも忠実性？」
「そのメソッドは貼ったドキュメントに載ってる。40ターン目あたりから読まなくなっただけ」
「じゃあ忠実性だ。ドキュメントを足すんじゃなくて、コンパクションして読み直させよう」
パラメトリック知識 (Parametric knowledge)
学習によってモデルが「知っている」ことで、パラメータに蓄えられている。学習の時点で凍結されており、モデルは自分のパラメータを見ることも更新することもできない。圧縮の過程で細部は失われる。数十億の事実が決まった数のパラメータに詰め込まれ、珍しいものほどぼやける。ありふれた話題での流暢さの源であり、珍しい話題での作り話の源でもある。コンテキスト由来の知識と対になる語。
パラメトリック知識は事実として保存されているのではない。学習はモデルに検索用のデータベースを与えたりしない。テキストをうまく予測できるようになるまでパラメータを調整するだけで、ある話題についてのテキストをうまく予測できるモデルは、その話題を知っているかのように振る舞う。知識の信頼性は、それが学習データにどれだけ現れたかに従う。数百万の例がある話題は正確に再現されるが、数えるほどしか例がない話題では、似た話題の見た目をもとに推測する。モデルにとって再現と推測は同じ処理なので、自分がどちらをしているのか判別できない。でっち上げの答えも正しい答えと同じ流暢さで出てくる。ハルシネーションとは、モデルの推測が外れたときのことだ。
パラメトリック知識は古びもする。パラメータは知識カットオフで変化を止めるので、その日付より後に公開されたり改名されたりしたライブラリはそこに存在せず、変わったAPIは古い形のまま覚えられている。
珍しすぎる場合も、新しすぎる場合も、手当ては同じだ。その知識をパラメータに足すことはできないので、コンテキスト由来の知識として供給するしかない。
使い方:
「Reactは完璧に書くのに、うちの社内SDKではメソッドをでっち上げる」
「Reactはパラメトリック知識の中で密度が高いんだ。学習例が何百万とある。あなたのSDKはそうじゃないから、モデルはもっともらしい形で埋めてくる。SDKのドキュメントをコンテキストに載せよう」
知識カットオフ (Knowledge cutoff)
これ以降のパラメトリック知識をモデルが持たない日付。カットオフより後のライブラリ、API、出来事は、ドキュメントをコンテキスト由来の知識として読み込まない限り、作り話の罠になる。カットオフはモデルのリリースごとに異なる。
カットオフが存在するのはモデルの作られ方のせいだ。学習はテキストのスナップショットをモデルのパラメータに焼き込み、その後パラメータは凍結される。モデルは自分の知識に縁があることを知らない。カットオフより後のことを尋ねられても拒否はせず、いちばん近い既知のものから外挿する。この罠が静かなのはそのためだ。古いバージョンのライブラリ向けに書かれたコードはもっともらしく見え、たいていコンパイルも通り、変わった部分でだけ失敗する。
対処はいつも同じで、最新の情報をコンテキストに入れることだ。変更履歴を読み込む、インストール済みバージョンの型定義を指す、ウェブからドキュメントを読ませる。コンテキストにあるものは、パラメータに何もないことに勝る。
使い方:
「v3 のSDK構文を書き続ける。うちは v5 なのに」
「v5 は知識カットオフより後に出たんだ。v5 の変更履歴をコンテキスト由来の知識として読み込ませよう。でないと古いパラメトリック版から作り続けるよ」
コンテキスト由来の知識 (Contextual knowledge)
エージェントがいまコンテキストから直接読める事実 — ユーザーのタスク、読み込んだファイル、ツール結果、セッション開始時に読み込まれたAGENTS.mdの内容。パラメトリック知識と対になる語だ。パラメトリックはパラメータから 思い出す もの、コンテキスト由来はウィンドウから 読む ものである。エージェントがコンテキスト由来の知識で作業しているとき、ハルシネーションはずっと少ない。答えがぼやけた記憶から掘り出されるのではなく、目の前にあるからだ。
2種類の知識のうち、あなたが制御できるのはコンテキスト由来のものだけだ。パラメータは凍結されているので、モデルに欠けている知識 — 社内SDK、知識カットオフより後に出たライブラリ、昨日決めたこと — を与える唯一の方法は、コンテキストに入れることである。実務的なAIコーディングの多くはここに帰着する。必要な事実を、必要になった瞬間にモデルの前へ置くことだ。
コンテキスト由来の知識とパラメトリック知識が衝突すると、たいていコンテキスト由来のほうが勝つ。現行のAPIドキュメントを貼れば、モデルは古いAPIの記憶ではなくそちらに従う。とはいえ、特に長いセッションの奥では古い版が滲み出てくることもある。ドキュメントを読み込ませているのに古いパターンへ戻り続けるなら、それはパラメトリック知識がコンテキスト由来のものを越えて漏れているということだ。訂正を言い直すか、作業の近くに置き直すと効く。
パラメトリック知識と違い、コンテキスト由来の知識は使うのにコストがかかる。ウィンドウに載せたものはすべてトークンを消費し、モデルの注意の予算を奪い合う。だから多く載せれば自動的に良くなるわけではない。狙うのは、すべての事実ではなく、関係のある事実をウィンドウに置くことだ。
この語を使うのは パラメトリック知識と対比するときだけでよい。それ以外の場面では単に コンテキスト と言えばいい。
避けるべき表現: 「作業記憶」 — コンテキスト由来の知識は いま ウィンドウにあるもので、メモリシステムはセッションをまたいだ内容をそこへ運ぶ仕組みだ。尺度が違うので混同しないこと。
使い方:
「ドキュメントを貼るとAPIを完璧に書くのに、貼らないとでっち上げるのはなぜ？」
「ドキュメントが入っていればコンテキスト由来の知識で、ページから読んでいる。なければパラメトリックで、珍しいエンドポイントはぼやけるんだ」
注意の関係 (Attention relationship)
各トークンを予測するとき、モデルはコンテキストにある他のすべてのトークンを勘定に入れる。強く効くものもあれば、ほとんど効かないものもある。2つのトークンの組み合わせが 注意の関係 であり、意味のある組（「彼女」と「サラ」、getUser() の呼び出しとその function getUser の定義）は、無関係な組より強く影響し合う。Nトークンのコンテキストには、およそN²個の関係がある。
モデルの理解らしきものが宿っているのは、この組み合わせだ。代名詞を解決できるのは、「彼女」と「サラ」の注意の関係が強いからである。正しい引数で関数を呼べるのは、呼び出し箇所と先ほど読んだ定義との関係が働いているからだ。これらはどこかから引かれてくるのではなく、モデルプロバイダーへのリクエストのたびに、すべての組についてその場で計算される。
N²という数字は腰を据えて眺める価値がある。直感より速く増えるからだ。
| コンテキストの大きさ | 組み合わせ（約N²） |
|---|---|
| 1,000トークン | 約100万 |
| 10,000トークン | 約1億 |
| 100,000トークン | 約100億 |
しかも各組は1回では済まない。モデルは複数のアテンションヘッドを持ち — 最前線のモデルの正確な数は公表されていないが、50から100程度と見ておけば妥当だろう — 各ヘッドがすべての関係について自分の版を計算する。つまり上の表の組み合わせは、ヘッドの数だけ重複する。膨大な量だ。
あるタスクにとって意味があるのは、そのうちごく一部の関係だけだ。あなたの指示と、それが支配するコードとの組み合わせは、数えるほどしかない重要な組の1つであり、プールの中のほぼ全部はノイズである。しかも両者は違う速さで増える。意味のある関係の数はだいたい一定なのに、プール全体はコンテキストの大きさに対して二次で増える。1,000トークンでは、あなたが気にしている組は100万分の1だ。100,000トークンでは、100億分の1になる。これが注意の予算の下にある算術であり、意味のある関係に回る取り分が薄くなりすぎたときの体感が注意の劣化である。
使い方:
「差分の中で2つの user シンボルを混同し続ける。バカゾーンに入った感じだね」
「うん、各呼び出し箇所とその宣言の注意の関係が、もう一方と競合している。トークンの形が同じで束縛が違うからだ。片方をリネームすれば組み合わせがはっきりするよ」
注意の予算 (Attention budget)
各トークンがコンテキストの残り全体に配れる影響力には限りがある。ある関係に大きく影響を割けば、他に回る分は減る。この予算はトークンごとのもので、コンテキストが伸びても増えない。長いセッションが薄まっていくのはこのためだ。
信号とノイズとして考えるとよい。あなたの指示は音量の決まった信号で、コンテキストウィンドウにある他のすべてのトークンは競合する音だ。指示の音量が下がるわけではない — 一字一句そこにある — が、コンテキストが伸びるほど周りの部屋が騒がしくなり、信号対雑音比が落ちる。コンテキスト1万トークンの時点では最も大きく響いていた指示が、15万トークンでは背景のうなりになる。これが注意の劣化の裏にある仕組みだ。モデルは忘れているのではなく、信号がノイズに埋もれている。
症状は不服従のように見える。早い段階で制約に同意したエージェントが、そこからずれていき、制約を貼り直しても効果は短い。原因は指示のほうではなく、それと競合しているウィンドウの中身のほうにある。
あなたが制御できるのは、コンテキストに何を入れるかだ。タスクに寄与しない内容は中立ではない。寄与しているものすべてに対するノイズになる。ウィンドウを小さく保ち、溜まったコンテキストが割に合わなくなったらクリアし、重要な制約は最初に言ったから保たれると期待せず、言い直すこと。
使い方:
「冒頭に貼ったスキーマをずっと無視するのはなぜ？」
「バカゾーンにだいぶ入っているね。トークンごとの注意の予算は固定なのに、コンテキストは伸び続けた。スキーマの信号が、いまは何千もの新しいトークンと競合している」
注意の劣化 (Attention degradation)
セッションが伸びるほど、各トークンの注意の予算はより多くの競合に分散される。意味のある関係1つあたりの信号は細り、無関係なコンテキストからのノイズが押し寄せる。同じモデル、同じパラメータで、同じ皿から食べる口が増えただけだ。スマートゾーン／バカゾーン効果の原因である。
現れ方は、セッションの途中でモデルが下手になっていく形だ。1時間守っていた制約が滑り始め、言われたことを聞き直し、先に読んだファイルを無視したコードを書く。モデルには何の変化もない。変数は、いまどれだけのコンテキストに注意を配っているかだけである。
これは緩やかに進むので、セッションの内側からは捕まえにくい。エラーも出ないし閾値もない。各ターンは前より少し悪いだけで、滑りがはっきりする頃にはバカゾーンにしばらく居座っている。
回復するには、コンテキストを足すのではなく減らす。無視された指示を貼り直しても、同じ混雑したウィンドウに競合を1つ足すだけで、効果は短い。効くのはこちらだ。クリアしてタスクに必要なものだけ読み直す、コンパクションする、新しいセッションへ引き継ぐ。指示追従の低下は、モデルについての信号ではなくコンテキスト長についての信号として扱うこと。
使い方:
「かなりバカゾーンだね。型ファイルにないジェネリクスをでっち上げてる」
「注意の劣化だ。型定義はまだコンテキストにあるけど、その後に足したもの全部の下に信号が埋もれている。クリアして読み直そう」
スマートゾーン (Smart zone)
セッションの序盤、エージェントは「スマートゾーン」にいる。冴えていて、集中していて、思い出しもよい。セッションが伸びるにつれて「バカゾーン」へ流れていく。雑になり、忘れっぽくなり、ミスが増え、忠実性のハルシネーションも増える。同じモデル、同じハーネスで、違うのはコンテキストの量だけだ。注意の劣化の体感的な効果である。最前線のモデルでは、バカゾーンは12万5千〜15万トークンあたりから始まることが多い — ただしこの数字には議論がある。セッションが膨らんだらクリアするかコンパクションすること。押し切らないこと。
低下は緩やかなので見落としやすい。エラーメッセージも、目に見える境界もない。エージェントが少しだけ調子を落とし、やがてはっきり落ちる。よくある兆候は、20ターン前に出した指示を忘れる、直したはずの間違いを繰り返す、コンテキストと矛盾することを自信ありげに断言する、といったものだ。滑らかに滑っていくので、つい押し切って説明し直すことになり、それがコンテキストを増やして問題を悪化させる。
ゾーンはコンテキストウィンドウの上限とは連動しない。ウィンドウの大半が空いていても、セッションがバカゾーンの奥にいることはある。上限はハーネスが続行を拒む地点で、品質はそのずっと手前で落ち始める。計画はウィンドウではなくスマートゾーンを基準に立てること。タスクの実用的な予算は、技術的に保持できるトークン数ではなく、エージェントがうまく働けるトークン数だ。
スマートゾーンは予算であり、無関係な作業がそれを使う。セッション内で片付けたタスクはすべてトークンを消費するので、同じセッションで2つ目のタスクを始めるということは、バカゾーンに近いところから始めるということだ。1セッション1タスクにすれば、どのタスクにもセッションの最も冴えた部分を割り当てられる。1つのタスクがスマートゾーン1つより大きいときは分割すること。自然な切れ目で引き継ぐかコンパクションし、次の断片は新しいセッションにやらせる。
使い方:
「最初の3つのコンポーネントは完璧だったのに、4つ目でめちゃくちゃにされた」
「スマートゾーンを出ているね。モデルは同じで、いまはバカゾーンの奥にいるだけだ。コンパクションして計画を読み直させれば、次のコンポーネントはうまくいくよ」
セクション 5 — 引き継ぎ
クリア (Clearing)
いまのセッションを終えて、新しいセッションを始めること。次のメッセージは、空のセッションと空のコンテキストウィンドウから始まる。たいていはユーザーが判断して行う。
クリアは、汚れたコンテキストに対する処置だ。セッションにはあらゆるものが溜まる。失敗した試み、間違った方向、古いツール結果、捨てた計画。モデルはターンのたびにそれを全部読み直すので、まずい履歴が新しい作業の足を引っ張る。長いセッションの奥ではエージェントが曖昧になり、言うことを聞かなくなる。はっきり出した指示が無視され、品質が落ち、しっかりやれと促しても効かない。かき分けているノイズがコンテキストに残ったままだからだ。クリアはそのノイズを取り除く。
クリアは会話を消すわけではない。多くのハーネスはセッションの履歴をあなたのコンピュータに保存するので、記録は読み返すことも再開することもできる。消えるのはエージェントの作業状態だ。モデルはステートレスなので、新しいセッションは古いセッションが知っていたことを何も知らない。次のセッションが必要とする決定や進捗がいまのセッションにあるなら、先にエージェントへ引き継ぎ成果物を書かせ、それを指す形で新しいセッションを始めること。
空から始める代わりにセッションを要約して新しいコンテキストに入れるコンパクションと比べてみるとよい。クリアのほうが鈍器だ。ゴミも含めて、何も持ち越さない。
使い方:
「落ちるテストのところでループにはまっている」
「クリアしちゃおう。計画のドキュメントとテストファイルを持って新しいセッションで始める。いまのコンテキストと戦っても仕方ない」
引き継ぎ (Handoff)
あるセッションから別のセッションへエージェントのコンテキストを渡すこと。運び方はいろいろある。書き出された引き継ぎ成果物、メモリ上の要約（コンパクション）、その他だ。何も渡さないクリアとは区別する。理由もさまざまで、役割の切り替え（計画役 → 実装役）、AFK実行の開始、並列セッションへの展開、コンテキストウィンドウの空き確保などがある。
受け取る側のセッションはコンテキストゼロから始まる。モデルはステートレスで、古いセッションのものは新しいセッションからは何も見えない。次のセッションが必要とするものは明示的に運ぶ必要があり、それ以外は消える。「戻り道がない」という制約が運び方を決める。新しいセッションは古いセッションに意図を聞き直せないので、運ばれた材料はそれ単体で成り立っている必要がある。
| 仕組み | 形 | 性質 |
|---|---|---|
| 引き継ぎ成果物 | 環境上のファイル | 何かが依存する前に読んで直せる。多くのセッションで使い回せる |
| コンパクション | コンテキストウィンドウ内の要約 | 自動で安価。中身を検分しにくい。後継は1つだけ |
まずい引き継ぎの目に見える失敗は、蒸し返しだ。古いセッションが決着させた論点を新しいセッションが開け直す。何が決まったかは記録されたのに、なぜそう決まったかが記録されなかったからである。引き継ぎの良し悪しは、コンテキストゼロのセッションがそれで何をできるかで判断すること。
使い方:
「計画セッションが重くなってきた。このまま続けるべき？」
「引き継ごう。決定事項をドキュメントに書いて、クリアして、それを読ませる形で新しいセッションから実装を始める」
一次ソース (Primary source)
元の形のままの真実の源 — コード、会話の記録、生のログ、実際のAPIレスポンス。そのものについての説明ではなく、そのもの自体だ。二次ソースと対になる語。
コードベースが何をしているか知りたいなら、一次ソースはコードだ。ドキュメントも、アーキテクチャ図も、READMEも、それについての記述にすぎない。書かれた時点では正確でも、その後は別のスケジュールで動いている。エージェントがあなたのプロジェクトについて自信ありげに間違ったことを言うとき、問うべきはどのソースから作業していたかだ。ドキュメントを読んだエージェントはそのドキュメントの古さを受け継ぎ、コードを読んだエージェントは現在の真実を読んでいる。
一次ソースが既定にならないのは、コストのせいだ。コンテキストウィンドウに載せるのは高くつく。ファイル全体、記録全体、すべてのトークンが入力として課金され、注意の予算を奪い合う。その対価として得られるのが完全性だ。何が重要かという誰かの判断で事前にふるいにかけられていない。先月書かれた要約には、今日になって重要だと判明した細部は入っていない。一次ソースには入っている。
精度が要るときは一次ソースに手を伸ばすこと。正確なシグネチャ、実際のエラー、例外を投げている行。コンテキスト管理の多くは、一次ソースの代金を払う場面と、二次ソースで十分な場面を見分けることに尽きる。
使い方:
「エージェントはリトライが指数バックオフすると言うけど、実際にはエンドポイントを叩き続けているのが見えている」
「設計ドキュメントからそう読んだんだね。実際のリトライのモジュールを指してあげよう。振る舞いが問題になるときは一次ソースから作業すること」
二次ソース (Secondary source)
一次ソースについての記述で、一段離れたもの — コードを説明するドキュメント、記録を説明する要約、検索結果を説明するレポート。説明対象よりコンテキストウィンドウに載せるのが安く、構造上こぼれがある。何が重要かを書き手が決めており、落とされたものは要約しか持たない読み手には見えない。
コンテキストエンジニアリングの多くは、二次ソースを作る作業だ。コンパクションはセッションの履歴を要約に変え、次のセッションの種にする。サブエージェントはノイズの多い検索に自分のコンテキストを費やし、短いレポートを返す。引き継ぎ成果物はセッションの決定を、次のセッションが読む文書に凝縮する。メモリシステムはセッションが学んだことをノートに蒸留する。どれも同じトレードをしている。忠実さと引き換えに余白を得る、というトレードだ。
二次ソースは2通りの壊れ方をする。こぼれること — スキーマの決定を落としたコンパクションの要約、例外的なケースに触れなかったレポート。そしてずれること — 一次ソースが変わっても記述が追随せず、ドキュメントが先四半期のアーキテクチャを今四半期の自信で語る。エージェントがどちらかの壊れ方をした二次ソースに基づいて動くと、間違った情報から自信をもって作業することになる。対処は一次ソースへ戻すことだ。
どちらの失敗も、二次ソースが間違いだということにはならない。コンテキストウィンドウは有限で、一次ソースは高い。要約もレポートも引き継ぎ文書もなければ、大きなものは何も入らない。技量が要るのは、どの細部なら失われても持ちこたえるかを見極めること、そして持ちこたえないものは一次ソースに照らして確かめることだ。よくできた二次ソースは、元の資料へのコンテキストポインタを持っている。どの記録から来たかを名指しする要約、どのファイルを説明しているかを名指しするドキュメント。記述だけでは足りないとき、読み手は欠落から推し量る代わりにポインタを辿れる。
使い方:
「引き継ぎ文書には認証は完了と書いてあるのに、新しいセッションはトークン更新の不具合を見つけ続けている」
「その文書は二次ソースだよ。前のセッションが信じていたことを書いただけで、真実を書いたわけじゃない。新しいセッションに認証のテストを走らせて、一次ソースのほうを信じさせよう」
引き継ぎ成果物 (Handoff artifact)
引き継ぎの運び手として使う文書 — あるセッションが環境に書き、別のセッションが読む。仕様書、チケット、計画ドキュメントはすべて引き継ぎ成果物だ。
書く理由はこうだ。モデルはステートレスなので、クリアすればセッション内のものは何も残らない。決定も、制約も、書きかけの計画も、それを抱えていたコンテキストと一緒に消える。環境は残る。重要な状態をファイルに書き出すことは、それを次のセッションが読み返せる場所へ移すことだ。
この成果物は二次ソースである。作業そのものではなく、作業についての記述だ。だからこそ新しいセッションに手短に伝えられる大きさに収まるし、だからこそ誤解も招きうる。書いたセッションが信じていたことが記録されており、落としたものや間違えたものは読み手には見えない。主張が重要な場面では、次のセッションはそれを鵜呑みにせず、一次ソース — コードやテスト — に照らして確かめるべきだ。
良い成果物は、コンテキストゼロのセッションに読み込まれる前提で書かれている。「さっき話したファイル」ではなく具体的なファイルパス。次のセッションが蒸し返さないよう、何をなぜ決めたか。何が終わっていて何が残っているか。書かせる側のセッションに行き先を伝えると効く。「この作業を何も知らない新しいセッションのために、引き継ぎ文書を書いて」というふうに。
もう1つの運び方はコンパクションで、こちらはメモリ上で要約する。成果物には2つの利点がある。ディスクに置かれるので、何かが依存する前に読んで直せること。そして使い回せること。同じ仕様書で並列の5セッションに指示を出せる。
使い方:
「これを計画側のエージェントと実装側でどう分ける？」
「計画側に引き継ぎ成果物を書かせよう。ファイルパス、決定、制約。実装側のセッションはその成果物へのポインタから始めて、それを指示書として作業する」
仕様書 (Spec)
複数のセッションにまたがる仕事を記す引き継ぎ成果物 — 何を作るかを書くもので、各セッションが自分の担当をどうこなすかは書かない。作業が進むにつれて変わっていく。チケットで構成される。
仕様書があるのは、セッションが使い捨てなのに大きな仕事はそうではないからだ。コンテキストウィンドウ1つ分を超える労力がかかるものは、コンテキストの外に住処が要る。クリアしても残る、エージェントの環境のどこか — リポジトリ内のファイルでも、GitHubのイシューでも、エージェントが到達できるイシュートラッカーでもよい。仕様書がその住処だ。目標、制約、これまでの決定、そしてチケットの一覧と状態。新しいセッションはどれもそれを読めば、前のセッションが溜め込んだノイズを引き継がずに、仕事がどこまで進んでいるかを把握できる。
仕様書には見覚えのあるスタイルがいくつかあり、たいていはチームがすでに使っている書き方を引き継いでいる。プロダクト要求仕様書（PRD）はユーザーから見た何となぜに寄る。機能、振る舞い、受け入れ基準だ。設計ドキュメント や RFC は技術寄りで、採用した方式、退けた代替案、トレードオフを書く。小さい側では、チケットのチェックリストを並べただけの plan.md が、複数セッションにまたがる機能に対して同じ役割を果たす。スタイルより役割のほうが重要だ。エージェントにとってこれらはすべて同じもの、つまり各セッションの冒頭で読む、意図の持続的な記述である。
使い方:
「これは全部1セッションでやるべき？」
「いや、仕様書に書き起こそう。チケットに分けて、それぞれを自分のセッションで走らせる。1つのコンテキストで全部やろうとすると、半分行く前にバカゾーンに入るよ」
チケット (Ticket)
1セッション分の仕事を切り出す引き継ぎ成果物。単独で成り立つこともあれば、仕様書の子の1つとしてぶら下がることもある。チケットは兄弟チケットをブロックしたりブロックされたりできるので、作業の順序は直線的な計画ではなく依存グラフから決まる。
決定的な制約は大きさだ。1セッション分であること。チケットは、セッションがスマートゾーンから出る前に完了できる大きさであるべきで、この制約は検証できる。チケットに取り組むセッションが、仕事が終わる前にいつも劣化するなら、チケットが大きすぎる。分割すること。各セッションが5分の作業のためにコンテキストの大半を準備に費やしているなら、小さすぎる。まとめること。
良いチケットは、他に何のコンテキストも持たない読み手に向けて書かれている。目標、受け入れ基準、関係するファイルや決定へのコンテキストポインタ。前のセッションが知っていたことを導き直さずに作業を始められるだけの情報だ。
依存グラフは並列化の鍵でもある。互いに独立したチケット — グラフの葉 — は、それぞれ自分のセッションで同時に走らせられる。複数のエージェントを同時に動かす有効なやり方だ。
使い方:
「移行の仕様書、どこから手を付ける？」
「チケットのグラフを見て。スキーマ変更がバックフィルをブロックしていて、バックフィルがAPI切り替えをブロックしている。葉を1つ選んで、そこにセッションを当てよう」
コンパクション (Compaction)
メモリ上で行う引き継ぎ。前のセッションの履歴を要約し、その要約を種にして新しいセッションを始める。設計上こぼれがある。やり取りの記録は一次ソースで、要約は二次ソースだ。細部と引き換えに余白を得ている。ユーザーが手動で起動するか、自動コンパクションで自動的に起きる。
仕組みはこうだ。コンテキストウィンドウは有限で、長いセッションはそれを満たす。すべてのツール結果、読んだファイル、間違った回り道が履歴に残る。重くなってくると、ハーネスはモデルにセッションの要約を頼み、元の履歴を捨て、その要約を種に新しいセッションを始める。要約に入らなかったものはコンテキストから消える。これを和らげているハーネスもある。古い記録をディスクに残し、要約の中にそこへのコンテキストポインタを置く。二次ソースが自分の一次ソースへリンクしているので、要約が落とした細部は元を読み直せば取り戻せる。
要約を書くのはモデルなので、指示を出せる。「スキーマに関する決定は残して」と言えば、生成される成果物はより意図的になる。タイミングも効く。タスクの途中ではなく、計画が固まった後など、フェーズの切れ目でコンパクションすること。
すべてを捨てて冷たい状態から始めるクリアと対比するとよい。コンパクションは要点を持ち越そうとし、クリアは要点がもっと良い場所にすでに書かれていることに賭ける。
使い方:
「コンテキストが重くなってきたけど、まだテストを通す作業が残っている」
「始める前にコンパクションしよう。残すべきものを要約のプロンプトに書いて、新しいセッションがスキーマの決定を保ち、探索の跡を落とすようにする」
自動コンパクション (Autocompact)
コンテキストウィンドウが満杯に近づいたとき、ハーネスが自動的に起動するコンパクション。
ハーネスはコンテキストウィンドウの埋まり具合を見ている。閾値 — よくあるのは80%前後 — を越えると、いったん止まり、モデルにそれまでのセッションを要約させ、その要約を種に新しいセッションを始める。作業は何事もなかったかのように続く。
ただし、何かは起きている。コンパクションにはこぼれがあり、自動コンパクションはあなたが選んでいない瞬間にこぼす。手動のコンパクションはフェーズの切れ目で行われ、何を残すかをモデルに伝えられる。自動コンパクションは閾値に当たった時点で、タスクの途中でも発火する。リファクタの半ばかもしれず、あなたのどの決定を残す価値があるかを要約が自分で決める。典型的な症状はこうだ。エージェントは自信をもって作業を続けているのに、1時間前に立てた制約を静かに忘れており、その仕事が制約と矛盾し始めて初めて気づく。
防ぎ方は、発火させないことだ。コンテキストの残量表示を見て、自然な切れ目で手動でコンパクションする。あるいは、決定を計画ドキュメントやディスク上の引き継ぎ成果物に書いておく。そこなら要約が落とすことはできない。多くのハーネスは余白の設定も変えられる。閾値を早めたり遅らせたり、自動コンパクションを完全に切ったりできるので、発火前にどれだけ余裕を残すかを調整できる。
使い方:
「さっきスキーマについて決めたことを覚えていないみたいなんだけど」
「ターンの合間に自動コンパクションが走ったね。序盤の決定が要約されて、何かが落ちたんだろう。計画ドキュメントを読み直させるか、次からは手動でコンパクションして、残すものを自分で決めよう」
セクション 6 — メモリとステアリング
メモリシステム (Memory system)
エージェントをセッションをまたいでステートフルにしようとする仕組み。セッション中に情報を環境へ永続化し、以降のセッションの開始時にコンテキストウィンドウへ読み直すことで、ユーザーがセッションをクリアした後も連続性を持ち越す。
メモリシステムには2つの半分がある。書き込み側では、セッション中にエージェントが学んだこと — あなたが述べた好み、プロジェクトについての事実 — を環境のファイルとして記録する。読み込み側では、セッション開始時にハーネスがそのファイル群、あるいはその索引をコンテキストウィンドウへ戻す。自前のメモリシステムを備えたハーネスも多く、Claude Code の /memory はその1つだ。自分で組むこともできる。ノートを置くディレクトリと、それを参照せよというAGENTS.mdの指示があればよい。
常時読み込まれる内容につきもののトレードオフはここにも当てはまる。メモリは溜まっていくので、多くの仕組みは1行の索引だけを読み込み、本体はコンテキストポインタの向こうに置く。すべてを展開したりはしない。そしてメモリは二次ソースなので、ずれる。3月に記録された事実は、プロジェクトが先へ進んだ6月にも同じ確信で読み込まれる。メモリシステムには剪定が必要だ。AGENTS.md と同じである。
使い方:
「MySQLじゃなくてPostgresだと、毎回言い直している」
「メモリシステムを組もう。最初のターンで学んだことをファイルシステムに書いて、セッション開始時に読み直す。モデル自体はステートレスで、メモリの層が連続性を演出しているだけだ」
AGENTS.md
セッション開始時にハーネスがコンテキストウィンドウへ読み込む、環境上のファイル — プロジェクトからエージェントへの常設ブリーフだ。ハーネスをまたいだ慣習で、独自の変種を持つハーネスもある（Claude Code のものは CLAUDE.md）。
自動で読み込まれるので、セッションをまたいで同じことを繰り返さずに済む手段の1つになる。モデルはステートレスだ。あるセッションで与えた訂正は次のセッションには残らないので、このプロジェクトは pnpm を使うこと、テストは特定のフラグ付きで走らせること、あのディレクトリは生成物なので触らないことを、新しいセッションのたびに伝えるはめになる。同じことで2回エージェントを訂正したら、その訂正は AGENTS.md に書く候補だ。
向いている内容は、コードから導けないことすべてだ。ビルドやテストのコマンド、コードベースからは明らかでない規約、動かせない制約（「生成されたクライアントは絶対に編集しない」）。短く、断定的に。これはドキュメントではなくブリーフである。
トレードオフは、そこに書いたものが常に読み込まれることだ。指示は溜まっていき、その大半はどのタスクにも関係がなく、長い AGENTS.md はトークンを食うと同時に自分自身を薄める。コンテキストにある指示が増えるほど、モデルがそのうちの1つに従う確からしさは下がる。
避けるべき使い方: 段階的開示すべき内容を AGENTS.md に置くこと — そこに書かれたものは、そのセッションに必要かどうかに関わらず、毎ターン、毎セッショントークンのコストを払う。スタイルガイドならスキルやコンテキストポインタの向こうに置ける。AGENTS.md には、どこにでも当てはまる行だけを残すこと。
使い方:
「どのセッションも、始まった時点で4kトークン使っているのはなぜ？」
「AGENTS.md を見て。スキルの向こうに置くべきスタイルガイドを、誰かが丸ごと貼り付けているね」
段階的開示 (Progressive disclosure)
エージェントがいま必要とするコンテキストだけを読み込み、残りはコンテキストポインタで示すこと。UIデザインからの借り物で、あちらでは、いまのタスクに関係するコントロールだけを見せ、残りはクリックの向こうに隠すことを意味する。
この技法があるのは、コンテキストが二重にコストだからだ。先に読み込んだトークンは毎ターン入力トークンとして課金され、しかもエージェントが必要としているかどうかに関わらず注意の予算を消費する。スタイルガイド全文とデプロイ手順書とデータベース規約を詰め込んだAGENTS.mdは、そのすべてについてエージェントを下手にする。いまのタスクに効く指示が、効かない指示に薄められるからだ。兆候は、コンテキストに入っているはずのルールを無視するエージェントである。入ってはいるが、埋もれている。
段階的開示はこれを逆転させる。常時読み込む層を小さく保つ。話題ごとに一文と、詳細がどこにあるかを示すポインタだけ。エージェントはコンポーネントを書くときにスタイルガイドを読み、デプロイするときにデプロイ手順書を読み、テストを直すときはどちらも読まない。スキルは、この型をハーネスに組み込んだものだ。短い説明が毎セッション読み込まれ、指示の全文は必要になったときだけ読まれる。
使い方:
「スタイルガイド全部を AGENTS.md に放り込むべき？」
「やめよう、段階的開示だ。スタイルガイドはスキルとして参照して、実際にコンポーネントを書くときにエージェントが読み込むようにする。AGENTS.md はターンごとにトークンのコストを払うことになる」
コンテキストポインタ (Context pointer)
ある文書の中にある、別の文書を指す言及。タスクがそれを求めたときにだけ、エージェントがコンテキストウィンドウへ引き込める。段階的開示を組み立てる単位だ。
内容を直接書き込む代わりにポインタを使う理由はコストだ。ポインタはコンテキストウィンドウの1行にすぎない。その先の文書は数千トークンあるかもしれないが、エージェントが実際にポインタを辿るまで、そのトークンは何のコストにもならない。2,000トークンの手順書をAGENTS.mdに展開すれば、すべてのセッションがその代金を払う。「デプロイ手順: internal/deploy.md を参照」に置き換えれば、デプロイするセッションだけがそれを読み込む。タスクが合致したとき、エージェントはツール呼び出しでポインタを辿る。
ポインタが働くには2つの要素が要る。安定したパスと、辿る価値があるかをエージェントが判断できるだけの説明だ。パスだけのポインタは、辿る理由のないポインタである。中身の手がかりのない「internal/deploy.md を参照」は、それを必要としていたセッションに飛ばされる。タスクが現れる形に合うように書くこと。「リリース、デプロイ、ロールバックのときは、まず internal/deploy.md を読む」というふうに。
意識して見ると、ポインタはあちこちにある。AGENTS.md の各行、スキルの説明（ハーネスは説明を読み込み、スキルの本体はその向こうで待つ）、ディレクトリ一覧のファイル名、ドキュメント同士のリンク。
ポインタは、二次ソースを、その元になった一次ソースへ結び直すこともできる。元の記録を名指しするコンパクションの要約、説明対象のソースファイルを名指しするドキュメント。これで二次ソースのこぼれが回収可能になる。要約では足りないと分かったとき、エージェントは要約が残したもので済ませる代わりに、ポインタを辿って元を読める。
避けるべき表現: 「参照」 — 素っ気なさすぎて、辿ればコンテキストが増えることが伝わらない。「ポータル」 — 大げさすぎる。
使い方:
「AGENTS.md が巨大になってきた」
「大半は中身じゃなくてコンテキストポインタにすべきだね。常に効くルールだけ直接書いて、デプロイ手順書とスタイルガイドはスキルにして、ポインタだけ残そう」
スキル (Skill)
教えられる能力を1つの単位に束ねたもの — あるタスクをうまくこなすための指示と資材で、コンテキストポインタが目の前のタスクのためにコンテキストウィンドウへ引き込むまでは環境に置かれている。ハーネスにおける段階的開示の単位だ。
スキルは agentskills.io で定義されたオープンな標準である。もとは Anthropic が開発し、その後多くの主要ハーネスが採用したので、一度書いたスキルは各ハーネスで動く。形式は次のものを含むフォルダだ。
SKILL.mdファイル — メタデータ（最低でも名前と説明）と、指示そのもの- 任意で、エージェントが実行できるスクリプト
- 任意で、指示が指し示すテンプレートや参考資料
既定でコンテキストに置かれるのは名前と説明だけだ。エージェントのタスクが合致したとき、残りが読み込まれる。それまでスキルはほとんど場所を取らない。指示の全文がどれだけ大きくても、1〜2文分のトークンで済む。
ここがAGENTS.mdとの違いだ。あちらはタスクに関係なくすべてのセッションに読み込まれる。スキルは特定の種類の仕事が出てきたとき — リリース、新サービスの雛形作り、マイグレーションの作成 — に読まれ、それ以外のときは無視される。
避けるべき表現: 「ツール」 — ツールはエージェントが 呼ぶ もので、スキルは 読む 指示だ。
使い方:
「デプロイ手順書はどこに置くべき？」
「スキルとして置こう。デプロイが絡むタスクのときだけ読み込まれる。AGENTS.md に置くと、週に1回しか使わないもののために毎ターントークンを燃やすことになる」
サブエージェント (Subagent)
エージェントがツール呼び出しで起動する別のエージェント。自分のコンテキストウィンドウを持つ自分のセッションで走り、結果を1つのツール結果として返す。引き継ぎとは違い、親は明示的に戻りを期待している。引き継ぎには戻り道がない。さらにサブエージェントを起動することはできない — 木の深さは1段だ。サブエージェントは階層を組むためではなく、コンテキストを隔離するためにある。
狙いは、ノイズの多い作業を親のコンテキストの外に出すことだ。広い検索や長いファイル読みの遠征は何ページものツール結果を生むが、その大半は答えを見つけるまでの間しか意味がない。親の中で走らせれば、それが以降ずっと親のコンテキストに残る。サブエージェントの中で走らせれば、ノイズは使い捨てのウィンドウを埋め、最終的な報告だけが親のコンテキストに着地する。この報告は二次ソースだ。親が受け取るのは生の結果ではなく、サブエージェントが何を見つけたかについての記述なので、報告から漏れたものは親には見えない。
サブエージェントは並列にも走る。親は独立した作業に対して、いくつも同時に展開できる。
使い方:
「grepの結果でコンテキストが吹き飛んでいる」
「サブエージェントに検索させよう。ノイズは自分のコンテキストウィンドウで燃やして、あなたが実際に必要な2つのファイルパスだけ報告してくれる」
セクション 7 — 仕事の進め方
ヒューマン・イン・ザ・ループ (Human-in-the-loop)
セッションの間、1人以上の人間がエージェントと組んで進める働き方 — その場でレビューし、方向を変え、一緒に作業する。人間はそこにいて関与しており、個々の操作を承認するだけの存在ではない。
対になるのはAFKの働き方で、そちらはエージェントが無人で走り、あなたは後から結果を判断する。ヒューマン・イン・ザ・ループは、問題がまだ安いうちに捕まえるということだ。エージェントが違うファイルに手を伸ばす、要件を読み違える、行き止まりへ進み始める — それが見えたら一文で方向を変えられる。その間違いの上に積み上がった20分の自信満々の作業を、後から発見するのではなく。エージェントは自分が道を外れたことを確実に察知できるわけではない。放っておくと、止まって尋ねるより前へ押し進む傾向がある。
どちらの型が合うかは仕事による。仕様がはっきりしていて、リスクが低く、検証が容易なタスクはAFKに向く。曖昧なタスク、取り返しのつかないタスク、完成物のレビューが難しいタスク — スキーマ移行、際どい設計判断、本番に触れるもの — はループに留まるのが向く。判断の勘所はこうだ。間違った曲がり方をしたとき、それはどれだけ高くつき、どれだけ遅れて気づくのか。
性質上ループの中でしか成り立たない仕事もある。あなたの反応が入力だからだ。問い詰めは、あなたがそこにいて質問に答えないと機能しない。プロトタイピングも、あなたがそこにいて成果物に反応しないと機能しない。
ループに留まるのはあなたの注意を支払うことであり、それが希少な資源だ。エージェントの扱いがうまくなるということの一部は、より多くの仕事を安全にループの外へ出していくことである。計画、自動チェック、そして始終の監督ではなく最後の人間によるレビューによって。
使い方:
「これは一晩AFKで走らせる？」
「いや、スキーマ移行だからヒューマン・イン・ザ・ループでいこう。1ステップずつ見て、バックフィル元のカラムを間違えたら舵を切りたい」
AFK
Away from keyboard（離席中）。ユーザーがセッションを開始し、あとはエージェントを無人で走らせる働き方。AIコーディングのスループットを掛け算するもので、あなたが寝ている間、食事をしている間、別の仕事をしている間に、多数のAFKセッションを並行して走らせられる。安全にやるには、たいてい緩めの許可モードとサンドボックス化が要る。
あなたがいないとき、エージェントは曖昧さの扱い方を変える。見ているときなら、曖昧な判断は質問として浮上し、あなたが答える。席を外した後は、エージェントが既定値を選んで先へ進み、以降のすべての判断がその推測の上に積み上がる。特徴的な失敗は、最初の10分の誤った判断の上に築かれた、何時間分もの完成した自信満々の仕事に戻ってくることだ。仕事は雑ではない。筋は通っている。ただし間違ったことについて筋が通っている。
実行中に入力を与えられないぶん、前と後に与える。前もって: 曖昧さを先に解消しておく — 問い詰めのセッション、書かれた仕様書 — ことで、エージェントが独りで埋める隙間を減らす。実行中: 自動チェックと自動レビューが、あなたが払っていない注意の代わりを務め、機械的に捕まえられるものは早く落とす。後で: 実行はレビューできるものに着地させる。すでにマージされた変更ではなく、PRに。AFKは人間によるレビューをなくすのではなく、全部を最後へ先送りする。だからこそ、最後に届くものはレビューに値する形でなければならない。AXがAFKの実行で最も効いてくるのもこのためだ。誰も見ていないとき、エージェントが得られる支援は環境だけである。
避けるべき表現: 「バックグラウンドエージェント」 — 人間の働き方（「ユーザーが席を外している」）ではなく機械の側（「バックグラウンドで動いている」）を中心に据えてしまう。AFKは重要な事実、つまりユーザーが見ていないことを名指ししている。
使い方:
「これはAFKで走らせる。サンドボックス化したエージェント3体でリファクタして、朝にPRをレビューするよ」
「うん、ファイルシステムは読み取り専用、ネットワークなしで」
自動チェック (Automated check)
環境で走る決定的な検証 — テスト、型チェック、lint、ビルド、pre-commit フック。合否だけで、判断は伴わない。エージェントが誰の手も借りずに自己修正できる信号だ。不安定なテストはチェックが壊れているのであって、チェックでないわけではない。自動チェックは 設計上 決定的である。
自己修正はループとして働く。エージェントが変更を加え、ツール呼び出しとしてチェックを走らせると、失敗の出力がコンテキストウィンドウに着地する。ファイルと行番号付きの型エラー、期待値と実際の値を伴うアサーション失敗。それだけあれば、エージェントは問題を直してもう一度チェックを走らせられる。通るまで何度でも、人間をループに入れずに。このループを信頼できるのは決定性のおかげだ。同じコードは常に同じ判定を返すので、通ったことに意味がある。不安定なチェックはこれを毒する。エージェントは問題のなかったコードを「直し」たり、本物の失敗を再試行で通り抜けたりする。
良いチェックがコードベースのAXの大部分を占めるのはこのためだ。厳格な型、速いテストスイート、リンタのあるリポジトリでは、エージェントは自分の間違いの大半をあなたが見る前に捕まえる。それらのないリポジトリでは、作ったものをそのまま出す。この差が最も効くのはAFKの実行で、そこでは実行中に行われる検証がチェックだけだからだ。ただしチェックは、主張していることしか捕まえない。緑のチェックは主張された性質が成り立つことを意味するのであって、コードが正しいことを意味しない。判断の形をした隙間のためにあるのが自動レビューと人間によるレビューである。
避けるべき表現: 「フィードバックループ」「バックプレッシャー」 — どちらもチェックとレビューを一緒くたにする。避けるべき表現: 「テスト」 — テストは自動チェックだが、自動チェックのすべてがテストではない。
使い方:
「AFKの実行で、エージェントが壊れたコードを出し続ける」
「サンドボックスにはどんな自動チェックが繋がってる？」
「ユニットテストだけ」
「型チェックと lint も足そう。PRが上がる前に、そこから自己修正するようになるよ」
自動レビュー (Automated review)
別のエージェントの仕事をエージェントがレビューすること。多くの場合、別のモデルや別のシステムプロンプトで行う。非決定的で、判断を下す。走る場所はどこでもよい。PRに対するマージ前、コミット履歴に対する事後、セッション途中のサブエージェントとして。CIで動くLLM-as-judgeは自動レビューであって自動チェックではない。どちらに分類されるかは、どこで走るかではなく、その判定が 何をしているか で決まる。
これが機能するのは、作業したエージェントから切り離されているからだ。コードを書いたエージェント自身に自分の仕事をレビューさせても、得るものはごく少ない。バグを生んだセッションには、それを生んだ推論も入っていて、エージェントは自分の結論を追認として読み返す。新しいコンテキストウィンドウを持つレビュー役にはその執着がない。他人が見るように差分を見る。レビューが依っているのはそこだ。別のモデルや、レビュー専用のシステムプロンプトを使えばさらに鋭くなる。盲点が違うし、「問題を探して」という漠然としたものではなく、実際に気にしていること（セキュリティ、APIの契約、性能）に絞ったシステムプロンプトを与えられる。
自動レビューは他のレビュー層の間に収まる。自動チェックは決定的で、機械的に主張できることを捕まえる。人間によるレビューは高価で、最もスケールしない。自動レビューはその中間で、判断の形をした問題 — 誤解を招く関数名、見落とした例外ケース — を機械のコストで捕まえる。非決定的なので、見落としもするし、問題でないものを指摘もする。人間が見る前に下限を引き上げるフィルタとして扱うこと。人間を置き換える関門ではない。
避けるべき表現: 「AIレビュー」「エージェントレビュー」 — 作業しているエージェント自身と区別できないほど曖昧だ。
使い方:
「AFKの実行から、質の悪いPRが多く出てくる」
「マージ前に自動レビューの段を足そう。別のモデル、独立したシステムプロンプトで、セキュリティと契約の変更に絞って」
人間によるレビュー (Human review)
エージェントが作ったコードを、ユーザーが読んで判断すること。差分や変更されたファイルを読めばレビューだが、エージェントが何をしたかの 説明 を読むのはレビューではない。語りは成果物ではない。説明は二次ソースであり、しかもレビューされる当事者が書いたものだ。差分が一次ソースであり、レビューとはそれを読むことである。
エージェントは生産されるコードの量を増やすので、レビューがボトルネックになる。有用な考え方の1つは、レビューの戦略を層にすることだ。自動チェックが機械的な失敗を捕まえ、自動レビューが記述可能な問題を捕まえ、人間によるレビューはあなたにしか判断できないことに取っておく。その変更が正しい変更なのか、その進め方がこのコードベースに合っているのか、そもそもこれは存在すべきなのか。
レビューは早いほど安い。作業前に計画を読むのも、途中で小さな差分を読むのも数分で済むが、AFK実行の後に完成したブランチを掘り返すのはもっと時間がかかる。レビューの検問所をどこに置くかは、後回しの話ではなくヒューマン・イン・ザ・ループの判断である。
避けるべき表現: 単なる「コードレビュー」 — 人間によるものか自動のものか曖昧だ。
使い方:
「AFKの出力を人間レビューしたよ」
「差分を読んだ？ それとも要約だけ？」
「差分だよ。要約にはデッドコードを削除したと書いてあったけど、その関数、生成ファイルから呼ばれていた」
バイブコーディング (Vibe coding)
人間によるレビューを経ずにエージェントのコードを受け入れる働き方。差分は中身の見えないものとして扱われる。重要なのはプログラムがちゃんと動くかどうかで、中身が何かではない。自動レビューや自動チェックは走っているかもしれない。バイブコーディングはそのどちらについても何も言っていない。
この語は Andrej Karpathy によるもので、2025年初頭に名付けられた。「完全にバイブに身を委ね」「コードが存在することすら忘れる」 — 欲しいものを述べ、返ってきたものを受け入れ、動かして判断する。
バイブコーディングは、検分と引き換えに速度を得る。エージェント主導の作業では差分を読むのがたいてい最も遅い段なので、それを外せば主なボトルネックが消える。失敗が安いコード — プロトタイプ、使い捨てのスクリプト、社内ツール — なら妥当なトレードだ。リスクは、そのコードの寿命と重要度に比例して増える。
コストは後から来る。バイブコーディングされた変更は、誰も読んでいないコードベースとして積み上がる。確認されたのが振る舞いだけなので、振る舞いに現れないもの — ログに書き出される秘密情報、抜けた例外ケース、静かに間違ったデータの扱い — は誰にも見られないまま出荷される。そのシステムを誰かが初めてデバッグする日が、そのコードを誰かが初めて読む日になる。人間によるレビューが外れた以上、残っている自動の検証 — テスト、型、自動レビュー — が、そのコードが通る唯一の関門だ。
避けるべき使い方: 「質の低いAIコーディング」の同義語としての「バイブコーディング」 — この語はレビューの構えを名指ししているのであって、出てきたコードの質を指しているのではない。
使い方:
「認証フローで何が変わったか読んだ？」
「バイブコーディングした。ログインはまだ動く、確認したのはそれだけ」
「pushする前に差分を読んで。認証をバイブでやると、そうやってログに秘密情報が漏れるんだ」
デザインコンセプト (Design concept)
何を作ろうとしているのかについての共通理解。ユーザーとエージェントの間で共有されているが、どの成果物とも別のものだ。ブルックスの用語（『デザインのためのデザイン』）で、会話も、引き継ぎ成果物も、コードも、すべてデザインコンセプトを捉えよう・そこへ到達しようとする資産であって、そのどれもデザインコンセプト そのもの ではない。デザインコンセプトの質は、それを作った会話の質を通して感じ取られる。
この語は、よくある苛立ちの背後にある隙間を名指ししている。エージェントは頼んだとおりのものを書いたのに、それでも間違っている、という状況だ。原因はたいてい、自分が何を欲しいのかを詰め切れていなかったことにある。デザインコンセプトがあなたの頭の中で完成していなかった。プロンプトは詰められていた部分を捉え、詰められていなかった部分については何も言わなかった。エージェントはその沈黙を自分の前提で埋めた。合わせる相手がなかったからだ。何も故障してはいない。共有されたデザインコンセプトがなかった。共有できる全体が、まだ存在していなかったのだ。
デザインコンセプトが共有されたかどうかは、同僚相手と同じやり方で分かる。相手が、まだ尋ねていない質問に、あなたと同じように答え始める。そこに至るまでの作業は会話であり、問い詰めはその意図的な版だ。早すぎる段階で仕様書を書くのは、ずれをより長持ちする資産に固定するだけである。デザインコンセプトは、あなたが学ぶにつれて動きもする。資産はそれに遅れる。先週の理解に忠実な仕様書が、今週のセッションを誤らせうるのはこのためだ。
使い方:
「頼んだとおりのものを書いているのに、それでも違うんだよね」
「まだデザインコンセプトを共有できていないね。エージェントは隙間を前提で埋めている。仕様書を書かせる前に、キャンセル、返金、部分履行がお互いの中で揃うまで話し続けよう」
問い詰め (Grilling)
エージェントと一緒にデザインコンセプトを育てるための技法。エージェントがソクラテス式にユーザーへ聞き取りを行い、1度に1つの決定を取り上げ、それぞれについて推奨する答えを提示する。完成した計画へ急ぐのを遅らせる。コンセプトが安定するまで引き継ぎ成果物は書かない。
この技法があるのは、エージェントが隙間を黙って埋めるからだ。2行のプロンプトから仕様書を書けと言われたエージェントは、あなたがまだ決めていない決定のところで立ち止まらない。既定値を選んで書き込む。出来上がりは完成して見え、推測は選択と見分けがつかないので、気づくのは遅れる。レビューの場か、作られた機能が例外ケースを、あなたが選んだ覚えのないやり方で処理したときだ。問い詰めはこれを逆転させる。推測する代わりに、エージェントに尋ねさせる。
これはヒューマン・イン・ザ・ループの技法だ。あなたの答えが入力である。会話では答えられない質問 — 実物を見ないと分からないもの — に当たったら、プロトタイピングに切り替えること。
使い方:
「いきなり仕様書を書き始めて、キャンセルのロジックを間違えた」
「先に問い詰めよう。部分キャンセル、返金、タイミングについて、文書に何か書く前にあなたへ聞かせる。コードで解決するより会話で解決するほうが安い」
プロトタイピング (Prototyping)
会話では解像度が足りず、話の対象になる実物が必要なときに、エージェントに何かの粗い版を素早く作らせること。
問い詰めは設計上の決定を会話で解決する。会話は安いが解像度が低い。言葉では答えられない問いもある。その操作がどう感じられるか、そのAPIの形は実際の呼び出しコードで扱いやすいか、そのレイアウトは現実のデータ量で成立するか。聞き取りがそういう問いに当たり、正直な答えが「分からない、見てみないと」になる。そこから先は議論が堂々巡りになる。代わりに、エージェントに作らせ、それを見て、答えを持って会話に戻る。
エージェントは作るコストを下げる。だからこれが実用になる。以前は1日かかったモックの粗い版が数分でできるので、日常的にやる価値がある。これはヒューマン・イン・ザ・ループの技法だ。プロトタイプは、あなたが反応するためにある。
たいていは一度見て終わりにはならない。プロトタイプで反復すること。反応し、変更を頼み、また反応する。各周回が、会話では届かない解像度で、実物に照らして次の決定を1つ解決していく。
プロトタイプは全部が使い捨てである必要はない。実際に評価している部分だけを本番品質で作れば、決定がついたときに、反応の対象だったコンポーネントやAPIをそのまま本物のコードベースへ移せる。だからプロトタイピングは、仕様書が参照する材料として欠かせない。
使い方:
「ウィザードを1ページにするか3ステップにするかで30分議論している」
「言葉では決着しないよ。エージェントに両方プロトタイプさせよう。クリックして回れば5分で分かる」
DX
開発者体験（Developer experience） — コードベースとツールチェーンが、人間の良い仕事をどれだけ容易にしているか。良いDXとは、速いフィードバック、明確なエラーメッセージ、実際に抱いている疑問に答えてくれるドキュメント、一発で通るセットアップだ。この語はAIコーディングよりずっと前からある。この辞書に入っているのは、主にAXとの対比のためである。
DXは人間とコードベースの間の相互作用であり、それ以上のものではない。2つの読み手の主な違いは、人間がステートフルで、エージェントがステートレスであることだ。人間はコードベースを一度学べばその知識を翌日以降ずっと持ち歩ける。だからDXが悪くても生き延びられる。遅いCIはpushをまとめることで回避し、足りないドキュメントは一度Slackで聞くことで回避し、分かりにくい構造はどこに何があるかを覚えることで回避する。回避策は積み上がり、チームは自分たちと戦ってくるコードベースの中で生産的になってしまう。
エージェントは、その積み上がりを一切持たずに同じコードベースに向き合う。セッションをまたいでステートレスなので、毎回ゼロからコードベースを学び直す。速いテストスイートや明確なエラーメッセージの恩恵は受けるが、昨日理解したことは環境に書き込まれていない限り消えている。しかもその環境はツール結果を通してしか知覚できない。AXが名指ししているのはこの隙間だ。開発者がエージェントであるときに残るDXの部分と、コンテキストウィンドウを空けておくといった、人間にはない関心事である。
重なりがあるので、DXへの投資はしばしばAXも無料で改善する。厳格な型、速いテスト、予測できる構造はどちらにも効く。分かれもあるので、常にそうとは限らない。美しいオンボーディング文書は人間を1週間助けるが、AGENTS.mdから辿れない限りエージェントには何も届かない。
使い方:
「うちのDXは問題ないよ。新入社員は1週間で戦力になる」
「その1週間、誰かが横についているから戦力になるんだ。エージェントにその1週間はない。AXは別で見よう」
AX
エージェント体験（Agent experience） — あるコードベースでエージェントが良い仕事をできるように、環境がどれだけ整っているか。DXのエージェント向けの対応物だ。同じエージェントがあるリポジトリではうまくやり、別のリポジトリではうまくいかないとき — 同じモデル、同じハーネスで — 違いはたいていAXにある。とっさにモデルのせいにしたりプロンプトを書き直したりしたくなるが、直すべき場所はリポジトリ側であることのほうが多い。
良いAXには主に3つの側面がある。
| 側面 | 良いAXとはどういう状態か |
|---|---|
| 自動チェック | 速くて決定的な自動チェック — 型、テスト、lint — があり、人間なしでエージェントが自己修正できる |
| アーキテクチャ | 全部を読まなくても辿れるコードベース。予測できる構造、小さなインターフェースの背後に多くの振る舞い、何をするかが分かる名前 |
| 空いているコンテキスト | AGENTS.md、スキル、ツールが絞られていて、コンテキストウィンドウの大半がタスクに使え、エージェントがスマートゾーンに留まる |
AXとDXは重なる — 良いチェックときれいなアーキテクチャはどちらの読み手にも効く — が、分かれもする。人間は暗黙知にも、遅いCIにも、「課金モジュールはサラに聞いて」にも耐えられるが、エージェントは耐えられない。エージェントはIDEのツールチップやきれいなダッシュボードの恩恵を受けない。必要なのは、ツール結果にテキストとして現れる失敗だ。DXが良くてAXが悪いコードベースはありうる。
避けるべき使い方: AXをDXの同義語として扱うこと — 2つの読み手には別々の投資が要る。
使い方:
「エージェントはAPIのリポジトリでは良いコードを書くのに、フロントエンドではひどい」
「APIのリポジトリには厳格な型と速いテストスイートがある。フロントエンドにはどちらもなくて、常時読み込まれるスキルが40個ある。それはモデルの問題ではなくAXの差だよ」