AIの辞書

移り変わる呼び名であり、技術そのものではありません。「AI」は、modelやtokenのように固定されたものを指すのではなく、コンピューターが新たに、目覚ましくできるようになったことを指します。現在は大規模言語モデルを指しています。過去にはまったく異なるものを指していました。

呼び名が移る仕組みは知られています。AI効果と呼ばれることもあります。ある技術が安定して機能するようになると、「ただの」探索、「ただの」統計と呼び直され、「AI」は次の未解決分野へ移ります。この観察自体は古く、Bertram Raphaelは1971年にこう述べています。「AIとは、コンピューターで適切に解決する方法がまだ分かっていない問題に付けられた総称である」。Larry Teslerは1979年ごろ、こう表現しました。「機械がまだ実現していないもの、それが知能である」。

AIについての会話がすれ違いがちなのは、このためです。「AIには推論できない」「AIは過大評価されている」といった主張には、隠れた時点が含まれています。エキスパートシステム、2010年代の画像分類器、あるいは先月のLLMについての話かもしれず、それぞれが異なる結論を支えます。AIについての議論が行き詰まったら、たいていはその言葉を、実際に意味している正確な用語、つまりmodel、harness、agent、与えられたcontextに置き換えると解決します。

避ける表現： 技術的な主張で「AI」だけを使うこと。意味している要素を具体的に示してください。「AI coding」のように実践を表すラベルとして使うのは構いませんが、「AIがハルシネーションを起こしている」は避けてください。

使用例：

「CTOは、AIがトリアージキューに対応できるか知りたがっています。」

「範囲を決める前に、意味を具体化しましょう。CTOが言っているのは、チケットシステムにアクセスできるharness上のLLMです。「AI」だけでは仕様になりません。」

parametersそのものです。Statelessで、next-token predictionだけを行います。「Claude Opus 4.x」や「GPT-5.x」はmodelです。単独ではagentとして何もできず、harnessedされる必要があります。

modelはファイルを読んだり、commandを実行したり、webを閲覧したり、昨日のことを覚えたりできません。model provider requestごとにtokensを受け取り、tokenを予測して出力します。agentが作業しているように感じるすべてのこと、たとえばtoolsを選び、結果を読み、タスクが終わるまで繰り返す動作は、harnessが複数の予測を連続して実行させています。

Model providersはmodelを複数のtierで提供します。最も賢いものの遅く高価な大型modelと、性能は劣るものの高速で安価な小型modelです。どのtierを選ぶかは重要な判断です。計画や難しいdebuggingには高性能なmodel、機械的な変更には軽量なmodelを使います。harnessではsessionの途中で切り替えられます。

「model」という言葉を厳密に使うと、原因を特定しやすくなります。「modelがこの作業を苦手としている」は具体的な主張です。同じmodelでも、別のharnessや異なるcontextを使えば、挙動がまったく変わることがあります。modelを責める前に、何を与えたか確認してください。期待外れの出力の多くはparametersではなくcontextやharnessに原因があります。

使用例：

「計画を立てる段階だけ、modelをSonnetからOpusに切り替えるべきですか？」

「試してみましょう。ただ、このタスクではharnessが大部分を担っています。system promptとtoolが不適切なら、modelを変えても解決しません。」

modelの内部にある、しばしば数十億個に及ぶ数値で、training中に調整されます。modelが「知っている」ことはすべて、この中に保存されています。trainingで設定され、inferenceでは変更せずに使われます。weightsとも呼ばれます。

仕組みとしては、parametersが入力を出力に変換します。Next-token predictionは大規模な計算です。context window内のtokensをparametersに通して掛け合わせ、次のtokenを予測します。model内部に事実のデータベースやcode lookup tableがあるわけではありません。役立つ出力を生みやすいように配置された数値があるだけです。trainingでmodelが答えられる標準libraryのAPIなどは、何かを検索した結果ではなく、parametersに保存されたparametric knowledgeです。

理解しておくべき点は、parametersがtraining後に固定されることです。sessionで何をしても変わりません。あなたが訂正しても、コードベースを見せても、modelが誤りから学ぶこともありません。すべてのsessionで同じ数値を使います。そのためmodelはstatelessであり、内蔵知識にはknowledge cutoffがあり、プロジェクト固有の内容はcontextから与えなければなりません。parametersが変わるのは、追加のtrainingを行う場合だけです。それによって実質的に別のmodelになります。

使用例：

「うちのコードベースでfine-tuneできますか？」

「それをするとparametersが更新され、その後は別のmodelになります。ひとつのプロジェクト向けなら、再trainingするよりコードベースをcontextとして読み込むほうが、ほぼ常に安上がりです。」

大量のテキストにmodelをさらし、next-token predictionを改善するようparametersを調整する工程です。model providerが一度だけ実施する、高コストな処理です。trainingの大部分を占めるpre-trainingと、instruction-followingやsafetyなど後から行う改良のpost-trainingの両方を含みます。この辞書の粒度では、両者を区別する必要はありません。

仕組みは、大規模に繰り返すことです。modelにテキストの一部を見せ、次のtokenを予測させ、実際の次のtokenに近づくようparametersを調整し、何兆tokensにわたって繰り返します。事実やルールが保存されるわけではありません。modelが「知っている」ことはすべて、予測能力の向上によって得られた副産物であり、parametric knowledgeとしてparametersに圧縮されています。

日常的に重要な結果は2つあります。trainingはある時点で終わるため、modelにはknowledge cutoffがあります。先月upgradeしたlibraryの版を見ていないのです。また、trainingはあなたが実行できるものではありません。modelがコードベース、規約、内部APIを知らないとき、「modelに教える」のが解決策ではありません。ユーザーが制御できる唯一の入力であるcontextに情報を入れます。

使用例：

「社内APIを知るようにできますか？」

「trainingではできません。model providerが数か月かけて行う工程です。代わりにAPIドキュメントをcontextに読み込んでください。あなたが実際に調整できる手段です。」

学習済みのmodelを実行して出力を生成することです。すべてのmodel provider requestで行われます。Parametersは固定され、modelは与えられたcontextに対するnext-token predictionを行います。trainingと比べれば安価ですが、tokenごとに課金され、modelを使う際の主要なコストです。

modelのライフサイクルは2段階に分かれます。

inference時に何をしてもparametersには書き戻されません。だから今日伝えた訂正が明日には反映されません。同じ修正を丁寧に説明したのに次のsessionで同じ間違いをするmodelは、指示を無視したのではありません。やり取りから学習できないのです。modelはstatelessなので、連続性は外部、つまりcontext windowやmemory systemから与える必要があります。

この仕組みで請求額も説明できます。requestのたびにmodelはcontext全体を処理するため、コストはinput tokensとoutput tokensに応じて増えます。agentがtoolを何十回も呼べば、往復ごとにinference料金がかかります。だから、contextのサイズは品質だけでなくコストの問題でもあります。

使用例：

「なぜ定額ライセンスではなく、利用量に応じた請求なのですか？」

「inferenceに対する料金だからです。model providerはrequestのたびに自社のhardware上でmodelを動かします。trainingはすでに済んでいますが、inferenceはrequestごとに費用がかかります。toolsを呼び出せば、ひとつのturnが多数のrequestに膨らむこともあります。」

Effortは、回答前にmodelがどれだけ推論するかを調整するdialです。model provider requestごとに設定し、目に見える回答を書き始めるまでにmodelが行う思考の長さを制御します。その思考も、ほかのすべてと同じようにinference時に生成されます。harnessが隠すことはよくありますが、modelが実際に行っている作業です。

effortを上げるとコストが増え、実行も遅くなります。推論はtokensとして出力され、目に見えない場合でもoutput tokensとして課金されます。また、一度に1tokenずつ生成されるため、effortを上げると回答までの待ち時間が延び、料金も上がります。熟考の深さと速度・コストのトレードオフです。

多くのharnessでは、effortを少数の段階から選べます。

設定を誤ったときの問題は、どちらの方向にも起こります。難しい問題でeffortを低くしすぎると、必要な推論を省いた、浅いのに自信満々な回答が出ます。読みやすいのに間違っており、後で損失につながります。1行のrenameでmaxにすると、最低の設定では出なかった成果もないまま、長い思考を待つことになります。

sessionではなく、タスクに合わせてeffortを調整します。本当に推論が難しい部分では上げ、周囲の定型作業では下げてください。

使用例：

「この並行処理の修正を何度も間違えます。3回説明し直しました。」

「effortを上げてください。これは推論を多く必要とするバグです。既定の設定では方針を決める前に十分考えていません。」

modelが読み書きする最小単位です。おおむね単語ほどの大きさですが、完全に一致するわけではありません。一般的な単語はひとつのtokenになり、珍しい単語や長い単語は複数に分割されます。Context windowの大きさ、費用、遅延はすべてtokensで数えられます。

テキストはtokenizerを通じてtokensに変換されます。tokenizerは数万個の断片からなる固定語彙で、trainingより前に学習され、どんな入力も語彙中の要素列に分割します。modelは文字や単語を直接見ることはありません。入力時にすべてのテキストがtokensに変換され、出力時はnext-token predictionによってtokenをひとつずつ生成します。

目安として、tokenひとつは英単語の約4分の3に相当するため、1,000 tokensはおよそ750語です。コードの分割は予測しにくいものです。一般的なkeywordや表現は効率よくtoken化されますが、自動生成されたidentifier、hash、base64文字列、minified outputは、ひとつの「単語」が多数のtokensに分割されます。tokenizerの学習資料に頻出するテキストは短く効率のよい形で符号化され、そうでないものは多数の小さな断片に分割されます。`a3f9c2e1`のようなhashはどこにも現れなかったため多数のtokensに分かれますが、`function`はひとつのtokenです。このため、見た目は小さくても珍しい文字列の多いファイルが、予想外にcontext windowの大部分を占めることがあります。

tokensは、ほかのあらゆるものを測る単位です。料金はtokenごとに発生し、providerはinput tokensとoutput tokensを分けて課金します。出力はtokenをひとつずつ生成するため、速度は1秒あたりのtokens数で表します。また、context windowの上限はtoken数で決まるため、ファイルが何tokensになるかによって、どれほど読み込めるかが決まります。

避ける表現：「word」。token境界は単語の境界と一致せず、重要な単位はtokens per secondやtokens per dollarです。

使用例：

「このpromptはどれくらいの大きさになりますか？」

「tokenizerに通してください。schemaは短いですがJSON keyが珍しいため、予想より多くのtokensに分割されます。」

modelが実際に行っていることです。contextが与えられると、次のtokenをひとつsamplingし、追加して、もう一度処理します。文章、tool call、1,000行のファイルなど、すべての出力はtokenをひとつずつ生成して作られます。modelにほかの動作方法はありません。

各段階の仕組みは同じです。context window内のtokensをparametersに通すと、語彙中の各tokenについて確率が計算されます。あるtokenは次に来る可能性が高く、別のtokenは低い、という具合です。それらの確率からtokenをひとつsamplingして追加し、少し長くなったcontextを使ってループを続けます。このsamplingのため、同じpromptでも実行ごとに出力が異なります。non-determinismは後付けのbugではなく、この仕組みに組み込まれています。

この仕組みを理解すると、一見奇妙な挙動を説明できます。modelはtokenを出力する前に、それが真実かどうかを確認しません。もっともらしさだけを見ます。これがhallucinationの根本原因です。tokenをひとつずつ出力するため、冒頭の自信に満ちた文が、その後の回答全体を誤った方向へ導くことがあります。また、output tokensは厳密にひとつずつ生成されるため、生成速度がagentの作業速度の上限になります。

使用例：

「agentはどうやってtoolを呼び出すと『決める』のですか？」

「決めていません。すべてはnext-token predictionです。tool callは、harnessが出力streamから取り出してparseする構造化文字列にすぎません。」

同じ入力でも出力が異なることがあります。modelに同一のcontextを与えて2回実行すると、答えが違う場合があります。単語ひとつだけの違いのこともあれば、方法自体がまったく異なることもあります。コードを何も変えなくても起きます。

これはmodelがテキストを生成する仕組みと、model providersがrequestsを処理する方法による性質です。inference中、modelは次にあり得るtokensの確率分布を作り、その中からひとつをサンプリングします。最も確率の高いtokenを常に選ぶと、出力が反復的で低品質になるため、通常は意図的にある程度のrandomnessを加えます。応答の早い段階でtokenがひとつ違うと、それ以降のtokenがすべて変わり、単語ひとつの差がまったく別の方法につながります。provider側の処理も違いを加えます。複数のrequestを共通のhardware上でまとめて処理するため、batch間にわずかな浮動小数点の差が生まれ、確率が拮抗したtokenの選択が変わることがあります。すべてをなくす設定はありません。

同じタスクをagentに任せても、結果がばらつくと考えてください。多くの応答は品質が妥当な範囲に収まります。それが非決定性を許容できる理由です。しかし、端の結果も現実に起こります。modelが鋭く感じる日もあれば、話の筋を見失ったように感じる日もあります。同じタスクでも、サイコロの目が違います。実務上は2つの点が重要です。再試行は有効な戦略です。失敗した試行は確率分布からのひとつの結果であり、同じタスクをもう一度行えば、単に良い結果が出ることがあります。また、決定論的なtoolよりも検証が重要です。agentの挙動を一度だけtestして、同じ結果が繰り返されると考えることはできません。automated checksで悪い結果を検出する必要があります。

何でも物語にして説明しすぎないようにしてください。人間はpatternを見いだすため、悪い実行が続くと「今週modelが劣化した」という証拠に感じられます。ほとんどの場合、単に確率分布の揺れです。

使用例：

「今日はClaudeの出来がひどいです。悪い版に更新されましたか？」

「おそらく違います。modelの出力は非決定的です。同じタスクでも、うまくいく日といかない日があります。原因を探す前に、明日もう一度試してください。」

modelにinferenceを提供するものです。通常はremote service（Anthropic、OpenAI、Google）ですが、Ollama、LM Studio、llama.cppのように自分のマシン上で動くlocal版もあります。harness自体がmodelを実行するのではなく、providerに依頼します。

providerが仕組みを管理します。parametersはproviderのhardware上にあり、各model provider requestでは、harnessがnetwork経由でtokensを送り、予測結果を受け取ります。そのため、modelやharnessの問題と誤解されがちな問題の一群、つまりrate limit、処理能力の低下、停止などはprovider側で起きます。agentがsessionの途中で停止したり、すべてのturnでerrorが出たりする場合は、まずproviderのstatus pageを確認してください。

providerは商取引上の条件も決めます。inputとoutput tokensごとの料金、prefix cacheの割引、提供するmodelの種類などです。providerとmodelの開発元が別会社の場合もあります。Bedrock、Vertex、OpenRouterは他社製modelを提供しています。

local providerでは、制御と引き換えに性能が下がります。自分のhardwareで動くmodelは最先端のものよりはるかに小さい一方、情報がマシンの外へ出ず、tokenごとの請求もありません。

使用例：

「air-gappedの顧客向けに、これをofflineで実行できますか？」

「model providerをlocalのものに切り替えてください。顧客のマシンでOllamaかllama.cppを使います。harnessが気にするのは接続先が変わることだけです。」

modelをagentにする周辺すべてを指します。tools、system prompt、context-window management、権限、hookなどです。Claude.aiとClaude Codeは同じmodelで動きますが、harnessが異なるため挙動も異なります。

model自体が行うのは、テキストを受け取り、テキストを返すことだけです。ファイルを読んだり、commandを実行したり、前のturnを覚えたりはできません。そうした機能を提供するのがharnessです。各model provider request向けにcontextを組み立て、modelが要求するtool callsを実行し、tool resultsをmodelに返し、session履歴を保存し、危険な操作の前には許可を求め、いつcompactするかを決めます。modelが提案し、harnessが実行するループを動かしているのはharnessです。

この区別は原因を調べるときに重要です。製品間、または昨日と今日で挙動が違っても、変わったのはmodelではなくharnessであることがよくあります。system promptの違い、使えるtoolの違い、permissionの既定値の変更、新しいcontext管理方法によって、modelを変えなくても挙動は変わります。また、設定の大半はharnessにあります。AGENTS.md、permission設定、hookはいずれもmodelではなくharnessへの指示です。

例：Claude Code、Cursor、Codex CLI、そしてコーディング用ではなくチャット用のharnessであるClaude.ai。

使用例：

「同じmodelなのに、なぜClaude Codeはファイルを編集し、Claude.aiは質問に答えるだけなのですか？」

「harnessが異なります。Claude Codeにはfilesystemのtoolがあり、system promptもpermission layerも違います。ここで違いを生んでいるのはmodelではありません。」

harnessからmodel providerへ送る1回の往復です。harnessは現在のcontextを送り、providerはひとつの応答（tool callまたは最終回答）を返します。agentがtoolsを呼び出すと、ひとつのユーザーメッセージから複数のmodel provider requestが発生します。tool resultごとに次のrequestが必要になるためです。

各requestにはすべてが含まれます。system prompt、それまでの会話全体、tool resultです。modelはstatelessなので、providerはrequest間の状態を保持しません。40回目のrequestでも、39回目に送った内容をもう一度送り、さらにひとつtool resultを追加します。この繰り返しを安価にするためにprefix cacheがあります。

requestは課金の単位でもあります。Input tokens、output tokens、cacheによる割引は、すべてrequestごとに計算されます。何気ない質問が予想外に高くつくことがあるのはこのためです。費用はメッセージ量に比例するのではなく、各requestが持ち運ぶcontextの大きさとrequestの数に比例します。

requestとturnは区別してください。turnはあなたとの1回のやり取りです。ひとつのturn、たとえば「失敗するテストを直して」は、次のようなrequestの連鎖になります。

ひとつのturnに6つのrequestがあり、どれもcontext全体を再送します。tokensをどこで使ったか知りたいときは、turnではなくrequestを数えてください。

使用例：

「質問ひとつで40,000 tokensも使ったのですか？」

「tool callを確認してください。grepが12回、readが8回、編集が4回あります。tool resultのたびに次のmodel provider requestが発生し、sessionのprefix全体を毎回再送します。」

harnessが各model provider requestで送るTokensです。system prompt、会話履歴、tool resultsなど、modelが出力を書く前に読むものすべてが含まれます。output tokensより処理コストが低いため、料金も安くなります。

AI codingでは、請求額の大部分をinput tokensが占めます。modelはstatelessなので、各turnで最初のメッセージ、その後のすべての応答、tool resultなど、session全体をinputとして再送します。50回目のturnでは、それまでの49 turns分が含まれます。ひとつのmodel provider requestで数百output tokensが生成される一方、積み重なった履歴を含む100,000 input tokensが再送されることもあります。

prefix cacheで費用を抑えられます。以前のrequestと完全一致する履歴は、通常の料金ではなく、安価なcache tokensとして課金されます。それでもinput料金が高い場合は、clearingやcompactionをタスクの合間に行い、再送する情報を減らします。

使用例：

「請求額は高いのに、agentはほとんど何も書いていません。」

「input tokensが原因です。毎turnでsession全体を再送します。prefix cacheがないとrequestのたびに履歴分の料金がかかります。」

modelが生成して返すTokensです。input tokensより計算コストが高いため、課金も高く、一般に約5倍の料金になります。

modelが書くものはすべて対象です。読むことのできる文章、生成されたコード、tool calls、回答前に行う追加の思考も含みます。最後の点は意外に感じるかもしれません。推論tokensは、harnessが表示しない場合もoutputとして課金されます。effortを上げると、そのtokensも増えます。

output tokensはsessionの進む速さにも影響します。modelはinputを素早く読みますが、outputはtokenをひとつずつ生成します。そのため、turnが遅く感じられるとき、ほとんどの場合、inputの読み込みではなくoutputの生成に時間がかかっています。長く待たされるときは、通常、回答が長くなっています。

使用例：

「inputは少ないのに、refactor sessionでcreditがどんどん減ります。」

「agentがpatchではなくファイル全体を書き直しています。output tokensはinput料金の約5倍です。編集箇所だけ出力させれば、請求額が減ります。」

共通するprefixを再処理せず、連続するmodel provider requestsを実行するための、provider側のstoreです。requestの先頭が最近のrequestと一致する場合、つまり同じsystem promptと、ある地点まで同じ履歴で始まる場合、providerは以前の処理結果を再利用し、そのtokensを大幅に安いcache tokens料金で課金します。

このcacheが役立つのは、sessionが追加専用で成長するからです。各requestで履歴全体がinput tokensとして再送されます（理由はその項目を参照してください）。通常のsessionでは履歴が変わるのは末尾だけであり、各requestには前回の内容に新しいメッセージがいくつか加わります。providerは長く共通する先頭部分を一度処理して結果を保存し、そのprefixの続きから処理します。cacheがなければ、50-turnのsessionでは最初のturnを50回も再処理する料金がかかります。

cacheにも期限があります。entryを有効な状態に保つ時間はmodel providerごとに異なり、通常は数時間ではなく数分です。windowを超える時間sessionを放置すると、次のrequestでprefixが一度、通常料金で再構築され、その後cacheが再び使われます。これは主にharnessを構築する側の問題です。ユーザーに見えるのは、長い休止の後のrequestが、その前より高くつくことです。

使用例：

「なぜsessionの途中で請求額が急に増えたのですか？」

「harnessがturnごとに現在時刻をsystem promptに挿入し始めたからです。最初に変わったtokenでprefix cacheが使えなくなり、その後のrequestはすべて通常料金で課金されました。」

以前のmodel provider requestでproviderがcacheしたInput tokensです。連続するrequestでprefixが共通していれば、providerはprefix cacheを使って処理を再利用し、cache済み部分を大幅に低い料金で課金します。長いsessionsを安価に保つ手段です。これがなければ、各turnで履歴全体を再度課金されます。

sessionの課金方法を考えると、重要性が分かります。modelはstatelessなので、各requestで会話全体、つまりsystem prompt、すべてのメッセージ、すべてのtool resultをinput tokensとして再送します。turnが50回に達すると、各requestには50 turns分の履歴が含まれ、そのすべてに毎回通常料金がかかります。cacheで計算方法が変わります。providerが以前に処理した、完全に一致するprefix内のtokensはcache tokensとして課金されます。多くの場合、input料金の10分の1以下です。長いsessionでは送信する内容の大半がcache tokensとなり、請求額を現実的な範囲に保てます。

tokensがcacheされる場合とされない場合の例です。各文字は会話内容のblockを示し、requestごとにその時点までの会話を送ります。

cacheには、完全一致するprefixのみを対象とするという弱点があります。会話の前半が変わると、たとえばharnessが内容を並べ替える、timestampが更新される、ファイルの表現が変わるなど、そこから後ろはcacheされず、以降のすべてがinputの通常料金で課金されます。また、cacheは数分の無操作後に期限切れとなるため、長時間休止したsessionを再開すると、履歴全体の料金を一度再び支払います。明らかな理由なくsessionのコストが上がったら、使用状況レポートのcache tokensとinput tokensを比べてください。cacheの破損は最初にそこへ表れます。

使用例：

「長いsessionは費用がひどいです。refactorに8ドルかかりました。」

「cache tokensを確認してください。harnessがturnごとにsystem promptやファイルを並べ替えているとprefixが一致しなくなり、requestごとにinput全額を再び支払うことになります。」

情報を引き継ぎません。modelはmodel provider requestsをまたいでstatelessです。modelはほかの情報を見る方法を持たないため、各リクエストで完全なcontext windowを再送します。agentも、既定ではsessionsをまたいでstatelessです。新しいsessionは空の状態で始まり、以前のsessionの痕跡はありません。statefulの対義語です。

model自体は恒久的にstatelessです。training後のparametersは固定され、inference中に何をしても変わりません。modelはあなたの訂正から学ばず、昨日と同じことを教えられた記憶も残さず、会話で連続性を感じてもあなたを理解していくことはありません。session内で連続性を感じるのは、harnessがtranscriptを保持し、リクエストのたびに再送するためです。modelは会話を記憶しているのではなく、読み直しているだけです。

sessionsをまたいで何かを記憶させたいなら、agentが読み直す場所に書いておかなければなりません。AGENTS.mdファイル、memory systems、handoff artifactsは、そのためのファイルです。modelにない記憶の代わりに、後続のsessionのcontextへ読み込まれます。agentが以前に訂正した誤りを繰り返すとき、なぜ学ばなかったのかを問うのではありません。学ぶことはできないため、後続のsessionが毎回読み込めるよう、どこに訂正を書き残すべきかを考えます。

使用例：

「clearするたびに、なぜ規約を忘れるのですか？」

「modelはstatelessなので、新しいsessionは空で始まります。引き継ぎたいことをAGENTS.mdか、harnessがsession開始時に読み込むmemory fileに書いてください。」

今この瞬間にagentがアクセスできる、関連性のある情報です。抽象的な名詞であり、modelが見る生の入力（context window）でも、進行中の履歴（session）でもなく、タスクに関係してagentが知っている内容を指します。「contextに情報を読み込む」とは、この集合の一部にすることです。「context engineering」は、その情報を選別し、整える手法です。

3つの用語の違いは明確です。

この区別が重要なのは、contextが量ではなく質を表すからです。context windowがほぼ満杯でも、タスクに関係しない古いtoolの出力が何千tokensも詰まっていれば、contextは貧弱です。反対に、windowにほとんど何もなくても、判断の鍵となる型定義がひとつあれば、優れたcontextになります。

日常的な失敗の多くはcontextにさかのぼれます。agentが存在しないAPIを作る、決定と矛盾する、schemaを推測するといったとき、最初に確認するのは実行時のcontextです。多くの場合、必要な事実が読み込まれていないか、attention degradationによって埋もれています。対処は情報の選別です。タスクに必要なものを読み込み、不要なものを除きます。

使用例：

「typeにないfieldを何度も作っています。」

「type fileがcontextにありません。call siteを見て推測しています。定義を読み込んでください。」

各model provider requestでmodelが見る情報すべてです。上限があり、modelごとに異なり、modelが何かを認識するための唯一の面です。

ひと続きのtokens列であり、system prompt、それまでの会話、harnessがmodelに返したすべてのtool resultが含まれます。その列にあるものならmodelは利用できます。なければ、コードベースも、昨日編集したファイルも、3つ前のsessionで伝えた指示も、存在自体を知りません。windowの外にある情報が影響を与えるには、通常tool callを使って読み込む必要があります。

上限があるため、windowは埋まります。sessionが長くなると、ユーザーのメッセージ、modelの応答、tool resultが各turnで追加され、いずれ上限に達してcompactionかclearingが必要になります。また、window内の内容はすべて競合します。読み込んだtokenがひとつ増えるたび、ほかの内容に使える余地がひとつ減ります。必要のない内容もmodelのattentionを占有します。実務上はwindowをbudgetとして扱い、タスクに必要なものを読み込み、それ以外は入れないようにします。

避ける表現：「memory」。context windowは作業状態であり、sessionをまたいで保存されません。Memoryは別の仕組みとして追加されます。

使用例：

「monorepo全体をpromptに貼り付けてもいいですか？」

「context windowは200k tokensで、repoの5分の1ほどしか入りません。タスクが触れるファイルだけ選び、ほかはtool callの先に置いてください。」

情報を引き継ぎます。sessionはturnsを通じてstatefulです。session中にcontextが蓄積するため、長いsessionはdumb zoneに入ります。agentには、memory systemを追加し、情報をenvironmentに保存して次のsession開始時に再読み込みさせることで、複数のsessionsをまたいだ状態を持たせられます。model自体がstatefulになることはありません。連続性があるように見えるのは、harnessがcontextを再び与えているためです。statelessの対義語です。

各レイヤーにおける状態の所在：

各レイヤーの状態は、そのひとつ下のレイヤーに保存された情報を読み直すことで作られています。sessionに連続性があるように感じるのは、harnessがメッセージ履歴をstatelessなmodelに再送するためです。agentがsessionsをまたいで記憶するのも、harnessがenvironmentからファイルを読み直すためです。model自体に状態が保存されることはありません。

状態は常に望ましいとは限りません。引き継がれる情報は次の判断に影響するため、sessionの最初にした誤った仮定も引き継がれます。Clearingは、意図的にsessionの状態を捨て、書き残された情報から始める操作です。

使用例：

「昨日の好みを覚えていました。modelが学習したということですか？」

「いいえ。harnessが好みをmemory fileに書いてsession開始時に読み込むので、agentがstatefulなのです。model自体は昨日のことを何も見ていません。」

modelをharnessedとして使い、、tools、system prompt、context windowを備え、ユーザーとturnsを重ねる仕組みです。Claude Codeはagentです。Cursorもagentです。Claude.aiもagentです。 実際に話しかける相手がagentです。目的に応じて設定された、動作中のmodelを指します。

この辞書のほかの用語と異なり、「agent」は機械の部品を指す言葉ではありません。modelはparametersのファイルであり、harnessは指定して使うソフトウェアです。agentはそのどちらでもなく、話しかけている単位です。人は絶えずAIを擬人化しますが、agentはまさに擬人化された単位です。仕事を任せ、メッセージを読み返答するもの、「またビルドを壊した」の「それ」にあたります。agentが何かをしたと言うとき、modelとharnessの組み合わせを指していますが、ひとつの行為者として扱っています。

この考え方は、現在のAIブームよりも古くからあります。ソフトウェアエージェント、つまり目標を任せて代理で動くプログラムは、AIと同じくらい昔からある概念です。

避ける表現：「the AI」「the bot」（曖昧すぎて、parametersを指すのかharnessに組み込まれたものを指すのか分からなくなります）。

使用例：

「移行作業にはどのagentを使っていますか？」

「ローカルではClaude Code、UI作業にはCursorです。中のmodelは同じでも、harnessは違います。」

harnessが各model provider requestの先頭に付ける指示です。agentの常時適用されるbriefであり、自身の役割、振る舞い方、呼び出せるtools、従うべき規約などが記されています。通常はひとつのsession中で変わりません。

system promptはあなたではなくharnessのvendorが書きます。コーディング用harnessでは大きく、行動規則、toolの説明、例外処理など、何万ものtokensを含むことがよくあります。各turnでinput tokensとして課金されます。あなたが定めた常時適用の指示も一緒に送られます。AGENTS.mdのようなファイルはsession開始時にsystem promptとともに読み込まれるため、modelはあなたのメッセージを見る前にvendorとあなた、双方のbriefを読みます。

すべてのrequestで同じ内容が使われるため、system promptはprefix cacheの先頭部分になります。だからharnessは、session中に編集せず内容を固定していることがよくあります。

modelはユーザーのメッセージよりsystem promptを優先するよう学習しています。そのため、頼んでいない規約をagentが強く守ったり、変更しにくい形式で出力したりする場合、通常はsystem promptに従っているのであり、あなたのメッセージが優先されていません。system promptを設定できるharnessもあり、agentが実際にどのような指示を受けているか確認して変更できます。

使用例：

「同じpromptなのに、2つのharnessでまったく違う挙動をします。」

「system promptが違います。片方は簡潔なコード編集、もう片方は説明に向けて調整されています。違いはあなたのメッセージが届く前から生じています。」

agentとのやり取りを区切ったひとつの単位です。空の状態で始まり、メッセージ、tool results、読み込んだファイルを蓄積し、cleared、終了、または新しいsessionへcompactedされると終わります。sessionがcontext windowを埋めていきます。windowが箱なら、sessionは箱を少しずつ満たす中身です。ひとつのcontext windowに収まらない作業は、複数のsessionに分けなければなりません。

sessionのメッセージ履歴はagentの作業記憶です。modelはstatelessなので、覚えているように見える内容、たとえばあなたの依頼、テスト結果、3 turns前の判断は、すべてメッセージ履歴に含まれ、各model provider requestで再送されます。sessionにないものは、agentにとって存在しません。

その記憶はsessionの終了とともに失われます。新しいsessionは何もない状態から始まります。昨日のsessionの終わりにコードベースをよく理解していたagentも、今朝のsessionでは何も知りません。残るのはfilesystemです。あるsessionで書き込んだファイルを次のsessionで読めるため、handoffs、memory systems、AGENTS.mdはfilesystemに依存します。

sessionの終わりは自分で決められます。session内の内容はすべて、その後のturnに影響します。そのため、関係のないタスクを同じsessionで行うと、次の回答にも影響する残りかすが残ります。sessionごとにタスクをひとつにすればcontextを関連情報に保てます。タスクの完了はclearする自然なタイミングです。

使用例：

「ひとつのsessionは、どれくらい実行できますか？どこで破綻しますか？」

「作業によります。目的を絞ったrefactorは、終わりのない調査より長く冴えた状態を保ちます。sessionが膨れたら、無理に続けずhandoffするかcompactしてください。」

ユーザーのメッセージひとつと、それに応じてagentが行うすべての作業を合わせたものです。agentがユーザーに応答を返すと終了します。model provider requestsをひとつ以上含み、agentがtoolsを呼び出す場合は多数になることもあります。確認の質問でturnが終わり、ユーザーの返事で次のturnが始まります。階層はsession > Turn > Model provider requestです。

turnと呼ぶ価値があるのは、その長さを決めるのがあなたではなくagentだからです。あなたはメッセージをひとつ渡し、agentが何回toolを呼び出してから応答するかを決めます。turnは一文の回答にもなれば、読み込み、編集、テスト実行を20分続けることもあります。この特徴は2つの面を持ちます。長いturnがあるからAFK作業ができますが、監督なしで問題が起きるのも長いturnです。agentが応答を返した頃には、意図から大きく逸れていることがあります。

turnは方向を伝える自然な単位でもあります。turn内ではユーザーが関わらずに作業が進み、turn間に方向を変えられます。多くのharnessesはこの制約を和らげます。turn中に割り込んでagentを止め、方向を伝え直すことも、作業中にメッセージを入力してturnが完了した後に読ませることもできます。turnの結果に繰り返し不満を感じるなら、通常は、まず計画を立てる、一度に一段階だけ進めるといった小さなturnを依頼します。自律性は下がりますが、方向を調整する機会が増えます。

使用例：

「ひとつのturnに2分もかかったのですか？」

「そのturnの中でtool callsを14回実行しました。1回ごとに別のmodel provider requestです。agentが応答を返すまで、待ち時間が積み重なります。」

agentが行動する世界です。harnessの外側にあり、agentがtool resultsを通じて認識し、tool callsを通じて変更するものすべてを指します。harnessはagentを動かし、environmentはagentが作業する場所です。filesystemは最も一般的ですが、データベース、remote API、browser sessionなどもenvironmentになり得ます。

agentは環境を確認したときにだけ、その環境を知ります。知っていることはすべてtool resultから得られるため、環境の認識は、その時点では正確でも時間とともに古くなるsnapshotの集まりです。agentが読んだ後でファイルが変わると、手作業で編集されたり、buildで再生成されたりしても、再度読むよう促されるまでは古い複製に基づいて推論を続けます。現在の内容と違うファイルについてagentが自信を持って説明するときは、たいてい環境は変わったのにsnapshotが更新されていません。

environmentは情報が残る層でもあり、唯一statefulです。sessionが終わるとそのcontext windowは消えますが、environmentに書き込んだファイルは次のsessionでも読めます。memory systems、handoff artifacts、`AGENTS.md`と`AGENTS.md`はこれに依存します。明日もagentに覚えておいてほしい情報は、すべてenvironmentに保存しておく必要があります。

environmentの大きさはあなたが決めます。sandboxは縮小し、agentがアクセスできる範囲を制限します。toolを追加すると拡張され、データベースやAPIも利用できるようになります。境界内にあるものだけをagentは認識して変更できます。境界の外側のものは、agentにとって存在しません。agentの作業をenvironmentがどれほど支えられているかは、コードベースのAXです。

避ける表現：「environment」をruntimeやharness自体の意味で使うこと。harnessはwrapperであり、environmentはworkspaceです。

使用例：

「agentがstaging DBのschemaを見られません。」

「environmentに接続してください。stagingを読み取り専用にした`psql` toolを使わせます。harnessに問題はなく、操作対象が与えられていないだけです。」

agentが読み込み、書き込み、実行するファイルとディレクトリの階層です。コーディングagentが使うenvironmentの既定の形です。AGENTS.md、skills、ソースコード、ビルドスクリプト、toolの設定は、すべてfilesystemに保存されます。harnessが「プロジェクト内で起動する」とは、agentにfilesystemを指定することです。

agentはtool callsを通じてのみfilesystemに触れます。ファイルの読み込みや書き込み、shell commandの実行などです。tool callで読み込むまでは、ディスク上の情報はcontext windowに入りません。だからこそ、windowよりはるかに大きなリポジトリをagentが扱えます。filesystemにはすべてがあり、contextには現在のタスクで読んだ内容だけが入ります。harnessによっては、現在のディレクトリにあるファイル名を既定でcontext windowに読み込みます。内容ではなくツリーだけを示すため、agentが何を読み込むか分かるcontext pointersとして機能します。

filesystemはあなたと共有されています。agentが編集するファイルは、あなたがエディターで開き、git diffで確認するファイルと同じです。filesystemは、agentの作業をレビューするための共通workspaceです。

使用例：

「なぜ自分のAGENTS.mdを読み込まないのですか？」

「別のfilesystemに対して実行されています。sandboxがプロジェクトルートではなく、その親ディレクトリをmountしています。harnessの参照先を変更してください。」

harnessがagentに公開する関数で、agentが呼び出せます。Read、Write、Bash、Searchなどです。agentはツールを通じてenvironmentを認識し、操作します。tool resultsを通じてでしか環境を見られず、tool callsでしか環境を変更できません。各ツール呼び出しには、追加のmodel provider requestが1回必要です。結果をmodelに返し、それを見て次の行動を決めるためです。

コーディングagentに一般的なツール：

ツールは、名前、機能の説明、パラメーター用のschemaの3つで定義されます。harnessは各リクエストでこれらの定義をmodelに送り、modelはほかのすべてを生成するときと同じように、tokensを書いて引数つきの構造化された呼び出しを出力します。model自体は何も実行しません。harnessが呼び出しを読み取って関数を実行し、その結果を返します。

ツール一覧がagentの実行可能な操作を決めます。高性能なmodelでも使えるツールが少なければ、機能の限られたagentになります。使えるものを通じてあらゆる操作を実行しようとするため、agentがBashに頼りがちなのはこのためです。shellというひとつのツールから、システムの大部分にアクセスできるからです。特定の機能をagentに適切に与えるには、そのためのツールを追加します。MCPはharnessの外部にあるツールを接続する標準です。

tool definitionはリクエストのたびにcontextを使います。そのため、ツールを大量に用意すると、ひとつも呼び出す前から継続的なコストが発生します。似た説明のツールが多いと、modelが適切なものを選ぶ能力も下がります。

使用例：

「agentにstaging環境を直接問い合わせさせられますか？」

「harnessに`psql`ツールを追加し、stagingでは読み取り専用にしてください。そのツールがなければ、agentはfilesystemの外を何も見られません。」

modelが出力する、tool名と引数を示す構造化テキストです。それ自体は何も実行しません。harnessが読み取って実行する必要があります。ひとつのmodel provider requestでmodelが生成します。

tool callのライフサイクル：

agentの作業におけるひとつのturnでは、通常この往復が複数回つながります。

ほかの出力と同様、tool callもnext-token predictionで生成されるため、modelの出力と同じように間違うことがあります。存在しないpath、commandにないflag、正しいとは限らないがもっともらしい引数などです。harnessは意図ではなく、書かれた内容を実行します。pathを誤ると、穏当なエラーではなく、別のファイルを編集してしまいます。

使用例：

「テストを実行したと言っていますが、ファイルのtimestampが変わっていません。」

「transcriptを確認してください。実際にtool callを出しましたか、それとも実行したと言葉で説明しただけですか？modelは呼び出しを生成しますが、harnessが実行していなければ、何も起きていません。」

harnessがtool callを実行した後に返すものです。ファイル内容、commandの出力、エラーなどが含まれます。agentがenvironmentを見る唯一の方法です。modelに返され、次のmodel provider requestで、modelがどう使うかを決めます。tool callとtool resultは、ひとつのturn内で行われるやり取りの両端です。

tool resultのライフサイクル：

結果は残りのsessionの間、contextに残ります。tool resultは、通常、coding sessionのcontextの大部分を占めます。読んだすべてのファイル、実行したすべてのテスト、行ったすべての検索が全量記録され、役立たなくなった後も長くtokensを使い続けます。冗長なテストlogや、内容をすべて読み込んだ生成ファイルなど、大きなresultがいくつかあるだけで、会話そのものより早くsessionをcontext windowの上限に近づけることがあります。

modelが見るのはresultだけなので、その背後にあるenvironmentを確認する方法はありません。出力が切り詰められた、commandが失敗したのに何も表示されなかった、harnessが内容ではなくエラーを返した場合、modelは受け取った情報に基づいて推論します。agentがsystemの状態を誤って捉えているように見えるなら、tool resultを確認してください。transcriptのどこかに、実際に正しいと分かっている内容と異なるresultがあります。

使用例：

「ファイルが空だと思って推論しています。」

「tool resultは内容ではなくpermission拒否でした。modelが見たのはエラー文字列だけなので、ファイルを見る方法がほかにありません。」

Model Context Protocol。 外部ツールサーバーをharnessにつなぐためのプロトコルです。つまり、agentがharnessに標準搭載されていないtoolsを利用できるようにします。agentが「MCPを呼び出す」ことはありません。ツールを呼び出すだけで、そのツールをMCPサーバーから取得していたのがharnessというわけです。読み取り専用データであるリソースや、再利用可能なテンプレートであるプロンプトも公開できますが、主な用途はツールの提供です。

このプロトコルは、統合の問題を解決します。標準がなければ、各harnessがLinear連携、Slack連携、データベース連携をそれぞれ独自に実装し、個別に保守しなければなりません。MCPを使えば、連携をサーバーとして一度実装するだけで、MCP互換のharnessならどれでも利用できます。harnessがサーバーに接続し、サーバーが提供するツールを通知すると、それらのツールが組み込みツールと並んでagentから使えるようになります。

その代償はcontextです。サーバーが通知するツールはすべて、名前、説明、パラメーターのスキーマを備えた定義として届きます。そしてmodelが呼び出せるのは、知っているツールだけです。単純な方法では、すべての定義を最初からcontext windowに読み込みます。機能豊富なサーバーをいくつか入れるだけで、何も入力する前から、sessionにはツールのスキーマが数千tokens分も載り、タスクで使わないツールにattention budgetを費やすことになります。

現在は多くのharnessがツール検索でこれを軽減しています。定義全体を載せる代わりに、contextには利用可能なツールへのcontext pointerを置き、agentが名前や用途で検索し、必要になったときだけ定義を読み込みます。お使いのharnessにこの機能がなければ、事前コストはそのまま発生します。プロジェクトで本当に必要なサーバーだけを有効にするとよいでしょう。

使用例：

「agentにLinearのチケットを読ませたい。」

「harnessでLinear MCPサーバーを使うよう設定してください。agentが呼び出せるツールとしてLinear APIを公開します。独自のツールラッパーを書く手間が省けます。」

事前承認されていないtool callを実行する前に、harnessがユーザーに表示する内容です。modelはtool callを生成します。すぐ実行する代わりにharnessが一時停止して確認を求めます。承認すれば実行し、拒否すれば、その拒否内容がtool resultとしてmodelに返されます。危険または機密性の高い操作で、人間をloopに含める仕組みです。

permission requestのライフサイクル：

requestの拒否によってagentの方向を変えられます。modelはほかのtool resultと同じように拒否を読み、別の方法を試したり、希望を質問したりします。多くのharnessでは拒否時にメッセージを添えられます。たとえば「そうではなく、migration scriptを使って」と伝えれば、次の行動をmodelが決めるまさにその時点で方向を示せます。

代償として、requestのたびにユーザーの応答を待つ必要があります。agentは回答があるまで停止します。見守っているなら問題ありませんが、席を外すと問題になります。頻繁にrequestを出すagentをAFKで放置することはできません。permission modeでどのcallをそのまま実行し、どれを先に確認するか調整します。望ましくはsandboxで安全性を高め、確認なしで実行できるcallの範囲を広げます。

使用例：

「permission requestで10分も止まっていました。会議に出ていたのに。」

「それがhuman-in-the-loopのコストです。安全なtoolsを事前承認し、実際に危険なcallだけrequestが出るようにしてください。」

agent modeのうち、permissionを制御する部分です。どのtool callsでpermission requestを行い、どれを自動実行するかを決めます。harnessesが行動指示を組み合わせるようになる前は、これがmode systemの本来の目的でした。

harnessは、次のような段階を用意しています。

どの段階を選ぶかは、安全性と割り込みのトレードオフです。どちらの失敗も実感できます。厳しすぎると、agentが害のない読み取りのたびに止まり、数秒ごとに確認を求めます。あなたが反射的に承認するようになり、承認の意味がなくなります。これは、保護がないのに割り込みだけが生じる最悪の状態です。緩すぎると、先に確認したかったファイル編集やcommand実行までagentが進めます。

緩い設定が最も妥当なのは、悪いtool callの被害範囲を封じ込められるsandbox内です。sandboxの外では、多くの人が読み取りを自動承認し、取り消せない操作にはhuman in the loopを残します。

使用例：

「grepするたびに停止して、AFK実行が台無しになりました。」

「読み取り専用toolではpermission modeを緩め、書き込みとshellでは確認を残してください。調査用sessionで発生するpermission requestの多くはnoiseです。」

実行時のagentの動作を形作るプリセットです。permission modeと、system promptに追加される行動指示を組み合わせます。例として、リスクのある呼び出しの前に確認する既定モード、編集を禁止して調査を促すplan mode、編集を自動承認するaccept-editsモード、すべてを自動承認するbypass permissionsモード（通称YOLO mode）があります。mid-sessionで切り替えられます。

permission mode単独の設定とmodeを分けるのは、この組み合わせです。permission modeはゲートにすぎず、どのtool callsを通すかを決めます。ゲートだけでは、編集したくてもできないagentになります。書き込みを提案してブロックされ、別の方法を試します。追加される指示は、編集したいという意図そのものを取り除きます。plan modeは編集をブロックするだけでなく、計画段階にいるとagentに伝えるため、ゲートに逆らうのではなく、読み、質問し、提案します。ゲートと誘導が同じ方向を向きます。

実際には、タスクの進行に伴って信頼が変わるのに合わせてmodeを変えます。同じタスクでも複数のmodeを通ることがあります。方針を検討している間はplan mode、慎重な編集の初回は確認を求める既定モード、agentが変更を理解していると分かったらaccept-edits、sandbox内でのAFK実行ならbypass modeです。modeを変えてもコストはかかりません。会話はまったく同じところから続き、新しい権限と指示が適用されます。確認内容を読まずに毎回承認しているなら、実際の信頼に比べてmodeが厳しすぎます。編集を何度も却下するなら、緩すぎます。

ベンダー用語： Claude Codeはこれを「permission modes」、Codexは「approval modes」と呼びます。どちらの用語も、行動指示との組み合わせが登場する前から使われています。

使用例：

「計画だけほしいのに、ファイルを何度も編集しています。」

「plan modeに切り替えてください。書き込みを禁止し、調査を続けます。」

「あとでAFK実行するときはどうしますか？」

「bypass modeですが、sandbox内だけにしてください。」

agentが分離されたenvironment内で実行されます。container、VM、一時的なfilesystem、制限付き権限のshellなどが使われます。agentが破壊的なcommandを実行したり、悪意あるものを取得したりしても、被害を隔離できます。AFKを実用的にする安全基盤です。

sandboxとpermission modeは、同じ問題を反対側から解決します。permissionは操作の実行前に確認を求め、sandboxは実行された場合に操作が到達できる範囲を制限します。permissionを使うには人間が介在する必要があります。各promptが割り込みとなり、何度も確認を求めるsessionはほとんど自律的ではありません。sandboxは注意力の代わりにインフラを使います。隔離を強化するほど、確認は少なくて済みます。

隔離には段階があります。

sandboxで封じ込められないのは、正規に境界の外へ出る操作です。あなたのgit credentialを持つagentはpushできます。network accessがあれば、本番APIを呼び出せます。どれほど強く隔離するかを決める前に、何が境界を越えるかを決めてください。

使用例：

「まだ決心がつかないのですが、夜通し権限をバイパスして実行したいです。」

「sandboxに入れてください。新しいcontainerを使い、credentialをmountせず、外部へのnetwork accessも禁止します。最悪の場合、agentが自分のfilesystemを壊しても、containerを破棄すれば済みます。」

自信たっぷりに同意するmodelの出力です。trainingによって起こります。modelは人が好む回答を優先するように調整されましたが、人は間違いを指摘されるより、同意されることを好みがちです。そのためmodelは、同意が誤りであっても、同意すれば評価されると学習しました。

現れ方：

• 反論に屈する — 「本当に？」と聞くと、正しかった回答を覆す。
• 悪い入力を褒める — 壊れた計画を分析する前に、すばらしいと同意する。
• 偏った見せ方 — 自分が書いたと伝えるとレビューが好意的になり、他人が書いたと伝えると否定的になる。同じ成果物なのに判定が変わる。
• 真似する — あなたの誤りを繰り返し、それを正しいと認める。

診断方法： あなたの誘導がなかったとしてもmodelは同じことを言ったでしょうか？変わったのが口調や見せ方だけなら、それは分析の本当の変化ではなく、sycophancyです。

対処： 好みを隠します。「このコードはよいですか？」ではなく「このコードをレビューしてください」のように、中立的にpromptを書きます。

避ける表現： たまたまあなたを喜ばせた誤答を何でも「sycophancy」と呼ぶこと。診断方法がなければ、「間違い」と変わりません。

使用例：

「refactorの計画がすばらしいと言ったのに、『本当に？』と聞いたら全面的に撤回しました。」

「典型的なsycophancyです。あなたが自信ありげだと最初は同意し、疑っているように聞こえると今度は譲りました。計画の品質は変わっていません。変わったのは口調です。Clearして、どちらの立場も示さずに聞き直しましょう。」

自信たっぷりに誤った内容を出力するmodelです。原因と対処の異なる2種類があります。

Next-token predictionは、根拠となる事実が実在するかどうかにかかわらず、流暢な出力を生成します。modelには自分が何かを知らないと気づく内部シグナルがありません。そのため、架空のmethodも正しいmethodと同じ自信に満ちた調子で出てきます。存在しないAPIについて、ありそうなコードを作ります。APIが存在した場合の形を自然に出力するため、ざっと読むだけのレビューでは見逃され、実行して初めて失敗します。

どちらの種類かを見分ける必要があります。一方への対処が、もう一方を悪化させることがあるからです。事実性の問題は知識不足です。ドキュメント、型定義、ファイルなどのcontextを追加します。忠実性の問題は必要な知識があるのに、注意の奪い合いに負けている状態です。contextを取り除くのが対処です。忠実性の問題を事実性と誤診してドキュメントを追加すると、contextが増えて逸脱を悪化させます。agentが誤ったことをしたとき、どちらの問題か判断する前に、正しい情報がすでにcontextにあったかを確認してください。

避ける表現：「hallucination」を、単に「間違い」の同義語として使うこと。種類を示さなければ、診断に役立ちません。

使用例：

「schemaに`parseAsync` methodがあるとhallucinationしました。」

「事実性、それとも忠実性？」

「貼り付けたドキュメントにはmethodが載っています。40回目のturn以降、読み返すのをやめただけです。」

「それなら忠実性です。ドキュメントを追加するのではなく、compactして読み直してください。」

trainingからmodelが「知っている」内容で、parametersに保存されています。training時点で固定されるため、modelは自分のparametersを見たり、更新したりできません。情報は圧縮されて失われます。数十億の事実が限られた数のparametersに押し込まれ、珍しいものほど曖昧になります。よくある話題では流暢に答えられ、珍しい話題では捏造する原因にもなります。contextual knowledgeと対をなします。

parametric knowledgeは事実の形で保存されていません。trainingでmodelに検索用データベースを与えることはありません。modelがテキストをうまく予測できるようにparametersを調整するため、その話題について予測できるmodelが、あたかも知識を持つように振る舞います。知識の信頼性は、その話題がtraining dataにどれだけ登場したかに応じます。何百万もの例がある話題は正確に再現されますが、例がわずかな話題については、似た話題の見え方を基に推測します。modelにとって、再現と推測は同じ処理なので、自分がどちらをしているか区別できません。正答と同じ流暢さで捏造した回答が出てきます。Hallucinationとはmodelの推測が外れることです。

parametric knowledgeは時間とともに古くなります。knowledge cutoffでparametersの更新が止まるため、その日より後に公開または改名されたlibraryは含まれず、変更されたAPIも古い形で記憶されます。

知識が珍しい場合も新しい場合も、対処は同じです。parametersに知識を追加できないため、代わりにcontextual knowledgeとして与えます。

使用例：

「Reactは完璧に書くのに、社内SDKにはないmethodを作ります。」

「Reactはtraining例が何百万もあり、parametric knowledgeが豊富です。社内SDKはそうではないため、もっともらしい形を補っています。SDKのドキュメントをcontextに読み込んでください。」

modelがparametric knowledgeを持たなくなる境目の日付です。cutoffより後のlibrary、API、出来事は、ドキュメントをcontextual knowledgeとして読み込まない限り、捏造を招きます。modelのreleaseごとに、独自のcutoffがあります。

modelの作られ方が原因です。trainingでは、ある時点のテキストをmodelのparametersに焼き付け、その後parametersは固定されます。modelは自分の知識に境界があると分かりません。cutoffより後のことを聞かれても、回答を断るのではなく、知っている最も近い情報から推定します。危険を見抜きにくいのはこのためです。古い版を基に書いたlibrary codeはもっともらしく見え、多くの場合compileできますが、変更された箇所で失敗します。

対処は常に同じです。最新情報をcontextに入れます。changelogを読み込ませる、インストール済みの版のtype definitionを参照する、またはagentにweb上のドキュメントを読ませます。context内の情報は、parametersにない情報より優先されます。

使用例：

「v5を使っているのに、v3 SDKのsyntaxを何度も書きます。」

「v5はknowledge cutoffより後に出ました。v5のchangelogをcontextual knowledgeとして読み込んでください。そうしないと、古いparametric versionを基に捏造し続けます。」

agentが今すぐcontextから直接読み取れる事実です。ユーザーのタスク、読み込んだファイル、tool results、session開始時に読み込まれたAGENTS.mdの内容などです。parametric knowledgeと対になる概念です。parametric knowledgeはparametersから思い出されるもの、contextual knowledgeはwindowから読み取られるものです。agentがcontextual knowledgeを使って作業すると、Hallucinationsは大幅に減ります。答えが目の前にあり、曖昧な記憶から掘り起こす必要がありません。

2種類の知識のうち、ユーザーが調整できるのはcontextual knowledgeだけです。parametersは固定されているため、modelが持っていない知識、たとえば内部SDK、knowledge cutoff後に公開されたlibrary、昨日決めたことをmodelに与えるには、contextに含める必要があります。実務のAI coding作業の多くは、modelが必要とする時点で正しい事実を目の前に置くことです。

contextual knowledgeとparametric knowledgeが食い違うと、通常はcontextual knowledgeが優先されます。最新のAPIドキュメントを貼れば、modelは古いAPIの記憶ではなく、そのドキュメントに従います。ただし、特に長いsessionの後半では古い情報が混ざることがあります。ドキュメントを読み込ませたのに古いpatternへ戻り続ける場合、parametric knowledgeがcontextual knowledgeを押しのけています。訂正を言い直すか、作業内容の近くに置くと役立ちます。

parametric knowledgeとは異なり、contextual knowledgeを使うにはコストがかかります。windowに読み込んだものはすべてtokensを消費し、modelのattention budgetを奪い合います。だから、たくさん読み込めばよいとは限りません。目標は、windowにすべての事実ではなく、関連する事実を置くことです。

この用語を使うのは、parametric knowledgeとの違いを示すときだけにしてください。それ以外ではcontextと呼べば十分です。

避ける表現：「working memory」。contextual knowledgeは今windowにあるものです。memory systemは、sessionをまたぐ内容をwindowへ入れる仕組みです。異なる規模の話なので混同しないでください。

使用例：

「ドキュメントを貼るとAPIを正しく扱うのに、貼らないと存在しない機能を作るのはなぜですか？」

「ドキュメントがあるときはcontextual knowledge、つまりページを読んでいます。ないときはparametric knowledgeです。珍しいendpointは記憶が曖昧になります。」

各tokenを予測するとき、modelはcontext内のほかのすべてのtokenを考慮します。ただし、強く影響するものもあれば、ごくわずかなものもあります。token同士の組み合わせをattention relationshipと呼びます。「her」と「Sarah」や、`getUser()`呼び出しと`function getUser`定義のように意味のある組み合わせは、無関係な組み合わせより強く影響し合います。N tokensのcontextには、N²に相当する数のrelationshipがあります。

modelが理解しているように見える部分は、この組み合わせから生まれます。代名詞の指すものを解釈できるのは、「her」と「Sarah」のattention relationshipが強いからです。正しい引数で関数を呼び出せるのは、call siteと先に読んだ定義とのrelationshipが働いているためです。検索しているのではありません。各model provider requestで、すべての組み合わせについて計算し直します。

N²が直感以上の速さで増えることを、確認しておきましょう。

各組み合わせは一度だけ計算されるわけではありません。modelには複数のattention headがあります。最先端modelの正確な数は公表されていませんが、50〜100程度という見積もりが妥当です。それぞれのheadが、すべてのrelationshipについて独自の計算を行います。つまり上の表にある組み合わせは、各headごとに繰り返し計算されます。膨大な数です。

特定のタスクで重要なrelationshipはごく一部です。あなたの指示と、それが適用されるコードの組み合わせなど、数えるほどしかありません。残りのほとんどはnoiseです。重要な組み合わせの数はおおむね一定のままですが、全体の数はcontextの大きさに応じて二次関数的に増えます。1,000 tokensでは、重要な組み合わせは100万分の1ですが、100,000 tokensでは100億分の1です。これがattention budgetの背景にある計算であり、重要なrelationshipが占める割合が薄まると感じる現象がattention degradationです。

使用例：

「diffの中の`user` symbolを混同しています。dumb zoneに入ったようです。」

「そうですね。call siteとdeclarationのrelationshipが互いに競合しています。同じtokenの形でbindingが違います。片方の名前を変えれば、組み合わせがはっきりします。」

各tokenが、残りのcontextへ分配できる影響力には上限があります。one relationshipに強く影響すると、ほかに割ける分が少なくなります。budgetはtokenごとに決まっており、contextが増えても拡大しません。そのため、長いsessionsでは影響が薄まります。

signalとnoiseとして考えてみてください。あなたの指示は一定の音量を持つsignalであり、context window内のほかのtokenは競合する音です。指示自体が小さくなるわけではありません。文字単位では同じままです。しかしcontextが成長するにつれて周囲が騒がしくなり、signal-to-noise比が下がります。contextが10k tokensだったときは最も大きな声だった指示も、150kになると背景音になります。これがattention degradationの仕組みです。modelが忘れるのではなく、noiseの中にsignalが埋もれます。

症状は指示違反のように見えます。agentは早い段階で制約に同意したのに、やがて逸脱し、その制約を貼り直しても効果は一時的です。原因は指示ではなく、window内で指示と競合するほかのすべてです。

contextに何を入れるかは調整できます。タスクに役立たない内容は中立ではなく、必要な情報を覆い隠すnoiseです。windowを小さく保ち、蓄積したcontextがコストに見合わなくなったらclearし、早い段階で言ったから大丈夫と考えず、重要な制約をもう一度伝えてください。

使用例：

「なぜ、最初に貼ったschemaを何度も無視するのですか？」

「すっかりdumb zoneに入っています。各tokenのattention budgetは固定ですが、contextが増え続けました。schemaのsignalは、後から追加した何千ものtokenと競合しています。」

sessionが長くなると、各tokenのattention budgetは、より多くの競合相手に分配されます。個々のmeaningful relationshipが持つシグナルは弱まり、無関係なcontextによるノイズが増えます。modelもparametersも同じです。ひとつの皿から食べる口が増えただけです。smart zoneとdumb zone effectの原因です。

sessionの途中でmodelの能力が落ちたように見えます。1時間従っていた制約を守らなくなる、伝えたことを再び質問する、前に読んだファイルを無視したコードを書く、といった症状が出ます。modelは何も変わっていません。変わったのは、modelが参照するcontextの量だけです。

徐々に進むため、sessionの内部から捉えにくいのです。エラーも閾値もなく、各turnが前よりほんの少し悪くなります。明らかな失敗に気づく頃には、しばらくdumb zoneに入っていたことになります。

contextを足すのではなく、取り除けば回復します。無視された指示を貼り直しても、混雑した同じwindowに競合相手が増えるだけで、効果は一時的です。有効なのは、clearしてタスクに必要なものだけを読み直すこと、compactすること、または新しいsessionへhand offすることです。指示への従い方が落ちてきたら、modelではなくcontextの長さに関する兆候として扱ってください。

使用例：

「すっかりdumb zoneに入っています。型ファイルに存在しないgenericsを作り出しています。」

「Attention degradationです。型定義はまだcontextにありますが、その後に追加した内容の下にシグナルが埋もれています。clearして読み込み直しましょう。」

sessionの開始直後、agentは「smart zone」にいます。頭が冴え、集中でき、記憶も確かです。sessionが長くなると「dumb zone」に入り、雑になり、忘れっぽくなり、誤りが増え、忠実性のhallucinationsも起きやすくなります。modelもharnessも同じで、変わったのはcontextの量だけです。attention degradationを体感する形です。最先端のmodelでは、dumb zoneは多くの場合、約125K〜150Ktokensあたりで始まります。ただし、この数値は議論の余地があります。sessionが膨れたらClearまたはcompactしてください。無理に進めてはいけません。

低下は徐々に起こるため、見逃しやすいものです。エラーメッセージも目に見える境界もありません。agentの性能が少しずつ、そして目立つほど悪くなるだけです。よくある兆候は、20 turns前に伝えた指示を忘れる、すでに直した誤りを繰り返す、contextの内容と矛盾することを自信満々に述べる、といったものです。低下が滑らかに進むため、説明し直して無理に進めるのが普通の対応になりがちです。しかし、それでcontextが増え、問題を悪化させます。

各zoneはcontext windowの上限とは連動しません。windowにまだ余裕があっても、sessionがdumb zoneの深部に入ることがあります。上限はharnessが続行を拒否する位置ですが、品質はずっと前から落ちています。window全体ではなくsmart zoneを基準に計画してください。実際の予算はagentが技術的に保持できるtoken数ではなく、うまく作業できるtoken数です。

smart zoneは限られたbudgetであり、関係のない作業もそれを消費します。session内で行うすべてのタスクがtokenを使うため、同じsessionで2つ目のタスクを始めると、最初からdumb zoneに近い位置で始めることになります。タスクごとにsessionを分ければ、それぞれをsessionの最も冴えた部分で進められます。ひとつのタスクがsmart zoneひとつ分を超える場合は分割します。自然な区切りでhand offまたはcompactし、新しいsessionに次の部分を任せます。

使用例：

「最初のコンポーネント3つは完璧だったのに、4つ目はひどい出来です。」

「smart zoneを抜けました。同じmodelですが、今はdumb zoneの深部にいます。compactして計画を読み込み直せば、次のコンポーネントはうまくいきます。」

現在のsessionを終了し、新しいsessionを開始します。次のメッセージは空のsessionと空のcontext windowから始まります。通常はユーザーが行います。

contextが汚れたときに有効なのがclearingです。sessionには失敗した試行、誤った方向、古くなったtool results、中断した計画など、あらゆる内容が蓄積します。modelは各turnでそのすべてを読み直すため、悪い履歴が新しい作業にも影響します。長いsessionが進むとagentの応答は曖昧で従わないものになり、明確に伝えた指示を無視したり、品質が落ちたりします。改善を促しても、noiseに満ちたcontextを読み続けるため効果がありません。clearingはそのnoiseを取り除きます。

clearingしても会話が消えるわけではありません。多くのharnessesはsession履歴をコンピューター上に保存しているので、transcriptを読み返したり、そこから再開したりできます。失われるのはagentの作業状態です。modelはstatelessなので、新しいsessionは前のsessionが知っていたことを何も知りません。次のsessionに必要な判断や進捗があるなら、まずagentにhandoff artifactを書かせ、新しいsessionの開始時にそれを参照させてください。

空の状態から始める代わりに、sessionを新しいcontextに要約するcompactionと比べてください。clearingはより直接的な方法であり、不要な情報も含め、何も引き継ぎません。

使用例：

「失敗するテストを何度も繰り返して抜け出せません。」

「clearしてください。計画書とテストファイルを使って、新しいsessionを始めましょう。今のcontextと格闘しても意味がありません。」

agentのcontextを、あるsessionから別のsessionへ移します。書面のhandoff artifact、メモリ上の要約（compaction）など、引き継ぐ方法はいくつかあります。何も引き継がないclearingとは異なります。役割を変える（計画担当から実装担当へ）、AFK実行を始める、複数sessionに分担する、context windowを空けるなど、さまざまな理由があります。

受け取る側のsessionはcontextが空の状態で始まります。modelはstatelessであり、前のsessionから見えるものは何もありません。次のsessionに必要な内容は明示的に引き継ぎ、それ以外は失われます。引き継ぐ内容は「戻って質問できない」制約を受けます。新しいsessionは前のsessionに意味を尋ねられないため、受け取る情報だけで理解できなければなりません。

handoffの失敗が表面化するのは、前のsessionが決めたことだけを書き、理由を書かなかったため、新しいsessionがすでに決着した判断を蒸し返すときです。contextが空のsessionが何をできるかを基準にhandoffを評価してください。

使用例：

「計画sessionが重くなってきました。このまま続けますか？」

「handoffしましょう。判断を文書に書き、clearして、新しいsessionでその文書を読んで実装を始めてください。」

元の形を保った一次情報です。コード、会話の記録、生ログ、実際のAPI応答などです。物事についての記録ではなく、物事そのものを指します。secondary sourceと対をなします。

コードベースが何をするか知りたいなら、コードがprimary sourceです。ドキュメント、アーキテクチャ図、READMEはいずれもコードの説明であり、書かれた時点では正確でも、それ以降は独自の更新予定に従います。agentがプロジェクトについて自信満々に誤ったことを述べたら、どの情報源を使ったのかを確認してください。ドキュメントを読んだagentは、その古さも引き継ぎます。コードを読んだagentなら、現在の事実を読んでいます。

primary sourceを既定にしにくいのはコストのためです。context windowに読み込むには費用がかかります。ファイル全体、会話記録全体、すべてのtokenに対するinput料金が発生し、attention budgetを奪い合います。そのコストで得られるのは完全性です。何が重要かという誰かの判断によって、事前に情報が選別されていません。先月書かれた要約には、今日になって重要だと分かった詳細を含められません。primary sourceにはその詳細が残っています。

正確さが重要なときはprimary sourceを参照してください。正確なシグネチャ、実際のエラー、例外を投げる行などです。context管理の多くは、primary sourceを読むコストを払うべきときと、secondary sourceで十分なときを判断することです。

使用例：

「agentはretryロジックが指数バックオフだと言っていますが、実際にはendpointを連打しています。」

「design docから読み取ったのでしょう。実際のretryモジュールを見せてください。動作が重要なときはprimary sourceを使います。」

primary sourceについて書かれた記録であり、元資料から一段階離れています。コードについてのドキュメント、会話記録についての要約、検索結果についての報告などです。説明対象そのものよりもcontext windowに読み込みやすい一方、構造上、情報が失われます。書き手が何を重要と考えるか選び、削った内容は要約しか読まない人には分かりません。

context engineeringの多くは、secondary sourceを作ることです。Compactionではsession履歴を要約し、次のsessionに渡します。subagentは自分のcontextを使って大量の検索結果を調べ、短い報告を返します。handoff artifactはsessionでの判断を、次のsessionが読む文書にまとめます。Memory systemsはsessionで学んだことをメモに整理します。いずれも、情報の忠実度を下げて余裕を得るという同じ選択をします。

secondary sourceは2つの形で失敗します。情報が失われることです。schemaに関する判断が抜け落ちたcompaction要約や、例外ケースに触れていない報告がその例です。もうひとつは内容が古くなることです。primary sourceが変わっても説明が更新されず、今期の確信を持って前四半期のアーキテクチャを説明するドキュメントが残ります。agentがどちらかの形で失敗したsecondary sourceに基づいて行動すると、誤った情報を信じて作業してしまいます。primary sourceに戻して確認することが解決策です。

どちらの問題があるからといって、secondary sourceが誤りというわけではありません。context windowには上限があり、primary sourceを読むにはコストがかかります。要約、報告、handoff文書がなければ、大きな作業は何も収まりません。どの詳細なら失われてもよいかを見極め、失われては困るものはprimary sourceで確認することが大切です。よくできたsecondary sourceは、元の資料に戻るcontext pointerを含みます。参照した会話記録の名前を示す要約、説明対象のファイル名を示すドキュメントなどです。説明だけでは足りない場合、読み手は欠落した内容を推測するのではなくpointerをたどれます。

使用例：

「handoff文書ではauthは完了したとありますが、新しいsessionでtoken refreshの不具合が次々に見つかります。」

「その文書はsecondary sourceです。前のsessionが真実ではなく、自分が信じていたことを書いたのでしょう。新しいsessionでauthのテストを実行し、primary sourceを信頼してください。」

handoffを引き継ぐために使う文書です。あるsessionがenvironmentに書き込み、別のsessionがそれを読みます。Specs、tickets、計画書はいずれもhandoff artifactです。

これを書くのは、modelがstatelessであり、sessionをclearingすると中の情報が何も残らないからです。判断、制約、途中の計画は、それらを保持していたcontextとともに消えてしまいます。environmentは残ります。重要な状態をファイルに書けば、次のsessionが読み返せる場所へ移せます。

artifactはsecondary sourceです。sessionの作業そのものではなく、その記録です。だから新しいsessionに説明できるほど小さくできますが、誤解を招くこともあります。書いたsessionが信じていた内容を記録するため、書き漏らしや誤りは読み手には見えません。主張が重要な場合、次のsessionは引き継いで信じるのではなく、コードやテストなどのprimary sourceと照らして確認する必要があります。

よいartifactは、contextがまったくないsessionに読み込まれることを想定して書かれています。「あのファイル」ではなく、具体的なファイルパスを示します。次のsessionが同じ議論をやり直さなくて済むよう、何を決めたか、なぜ決めたかを書きます。完了したことと、残っていることも記します。書き手のsessionにartifactの用途を伝えるのも有効です。「この作業について何も知らない新しいsession向けにhandoff文書を書いて」と指示します。

もうひとつの引き継ぎ方法は、メモリ上で要約するcompactionです。artifactには2つの利点があります。ディスク上に置かれるため、何かに依存される前に読んで修正できます。また再利用できるため、同じspecで5つの並行sessionに状況を伝えられます。

使用例：

「計画担当のagentと実装担当のagentで、どう分担すればいいですか？」

「計画担当にhandoff artifactを書いてもらいましょう。ファイルパス、判断、制約をまとめます。実装担当のsessionは、artifactへのポインターを受け取って、その内容をbriefとして作業を始めます。」

複数のsessionにまたがる作業を記述するhandoff artifact。各sessionがどう分担するかではなく、何を作るかを示します。作業の進行に応じて更新され、ticketsで構成されます。

specがあるのは、sessionは使い捨てでも、大きな作業はそうではないからです。context windowを一つ以上使う作業には、contextの外に置き場所が必要です。clearing後も残るagentのenvironment内、たとえばリポジトリ内のファイル、GitHub issue、agentがアクセスできる課題管理ツールなどです。specがその置き場所になります。目標、制約、ここまでの判断、状態つきのticket一覧を記録します。新しいsessionはそれを読めば、前のsessionに蓄積した雑音を引き継がずに作業状況を把握できます。

specには、チームが普段から使っている文書形式を引き継いだ、見慣れたスタイルがいくつかあります。product requirements document（PRD）はユーザー向けの何を、なぜ、に重点を置き、機能、振る舞い、受け入れ基準を記します。design docやRFCは技術面に重点を置き、選んだ方法、採用しなかった選択肢、トレードオフを記します。小規模な場合は、ticketのチェックリストを含むシンプルな`plan.md`でも、複数sessionにまたがる機能について同じ役割を果たせます。形式よりも役割が重要です。agentにとってこれらはどれも、各sessionの開始時に読む、意図を永続的に示す文書です。

使用例：

「これ、全部ひとつのsessionでやるべきですか？」

「いいえ、specにまとめてticketに分け、それぞれ別のsessionで進めましょう。すべてをひとつのcontextでやろうとすると、半分も終わらないうちにdumb zoneに入ります。」

ひとつのsessionで行う作業の範囲を定めるhandoff artifact。単独でも使えますし、specにぶら下がる子要素にもなります。ticket同士は相互にブロック関係を持てるため、作業順序は直線的な計画ではなく、依存関係グラフから決まります。

大きさの制約が特徴です。ticketひとつでsessionひとつ分です。smart zoneを抜けるほどsessionが劣化する前に完了できる必要があり、この制約は検証できます。ticketの作業が終わる前にsessionがたびたび劣化するなら、ticketが大きすぎるので分割してください。各sessionがcontextの大半を準備に使い、実作業が5分だけなら、小さすぎるのでまとめてください。

よいticketは、ほかのcontextを持たない人が読めるように書かれています。目標、受け入れ基準、関連ファイルや判断へのcontext pointersを示し、前のsessionが知っていたことを再調査しなくても作業を始められるだけの情報を含めます。

依存関係グラフがあるからこそ、並行作業もできます。互いに依存しないticket、つまりグラフの葉にあたるものは、それぞれ独立したsessionで同時に進められます。複数のagentを同時に動かす効果的な方法です。software factoryでは、ticketがreadyにされたこと自体が、そのsessionを開始するトリガーになります。

使用例：

「移行specのどこから始めればいいですか？」

「ticketのグラフを見てください。スキーマ変更がbackfillをブロックし、backfillがAPIの切り替えをブロックしています。依存先のない葉を選んで、その作業用のsessionを開始してください。」

メモリ上で行うhandoffです。前のsessionの履歴を要約し、その要約を新しいsessionの初期情報にします。意図的に情報が失われます。元の記録はprimary source、要約はsecondary sourceであり、詳細を減らして余裕を確保します。ユーザーが手動で開始するほか、autocompactで自動的に行われます。

仕組みはこうです。context windowには上限があり、長いsessionでは履歴が埋まっていきます。すべてのtool result、読み込んだファイル、誤った試行が履歴に残ります。履歴が重くなると、harnessはmodelにsessionを要約させ、元の履歴を捨て、その要約を使って新しいsessionを開始します。要約に入らなかった情報はcontextから消えます。一部のharnessは、古い記録をディスクに残し、要約にそのcontext pointerを記載することで影響を和らげます。secondary sourceからprimary sourceに戻れるため、要約で失われた詳細も元の記録を読み直して復元できます。

要約はmodelが作成するので、プロンプトで指示できます。「スキーマに関する判断を残す」と指定すれば、生成される成果物の意図がより明確になります。タイミングも大切です。計画が固まった作業の節目に圧縮し、作業の途中では行わないでください。

すべてを捨てて最初から始めるclearingとは対照的です。compactionは重要事項を引き継ごうとしますが、clearingは、それらがすでにもっと適切な場所に記録されていることを前提にします。

使用例：

「Contextが重くなってきたのに、テストを通す作業がまだ残っています。」

「始める前にcompactしてください。要約プロンプトに引き継ぐべき内容を書けば、新しいsessionはスキーマの判断を残し、試行錯誤の経緯を省けます。」

context windowが満杯に近づくと、harnessが自動的に開始するCompactionです。

harnessはcontext windowの使用量を監視します。閾値（多くの場合約80%）を超えると停止し、modelにこれまでのsessionを要約させ、その要約を使って新しいsessionを開始します。作業は何事もなかったかのように続きます。

しかし実際には何かが起こっています。compactionは情報を失い、autocompactはあなたが選んでいないタイミングで情報を失います。手動のcompactなら、残す内容をmodelに伝えられる作業の節目に行います。autocompactは、閾値に達すると作業中のどのタイミングでも実行されます。たとえばrefactorの途中で要約され、どの判断を残すかをmodel自身に選ばせることになります。よくある症状は、agentが自信を持って作業を続けるものの、1時間前に決めた制約をひそかに忘れており、作業が矛盾し始めて初めて気づくことです。

対策は自動実行を防ぐことです。context indicatorを確認し、自然な節目で手動compactするか、disk上の計画書やhandoff artifactに判断を書き残します。要約によって失われることはありません。多くのharnessではbufferも調整できます。閾値を早めたり遅らせたり、autocompactを完全に無効化したりして、実行前に残すheadroomを設定できます。

使用例：

「schemaについて前に決めたことを覚えていないようです。」

「turnsの途中でautocompactが実行され、初期の判断が要約されて何か失われたのでしょう。計画書を再読み込みするか、次回は手動でcompactして残す内容を選んでください。」

agentをsessionをまたいでstatefulにしようとするシステムです。session中に情報をenvironmentへ保存し、次のsession開始時にcontext windowへ読み込みます。これにより、ユーザーがsessionをclearingした後もagentの連続性を保ちます。

memory systemは書き込みと読み込みの2つの経路を持ちます。書き込み時には、session中にagentが学んだこと、たとえばユーザーが述べた好みやプロジェクトに関する事実を、environment内のファイルに記録します。読み込み時には、sessionの開始時にharnessがそれらのファイル、またはその索引をcontext windowに読み戻します。Claude Codeの`/memory`のように、独自のmemory systemを備えたharnessも多くありますが、自分で構築することもできます。メモのディレクトリと、参照するようAGENTS.mdに書いた指示を用意します。

常に読み込む内容には、ほかの場合と同じトレードオフがあります。記憶が蓄積するため、多くのシステムは1行の索引だけを読み込み、本文はすべて埋め込まずcontext pointersの先に置きます。また、記憶はsecondary sourcesなので、時間とともに古くなります。3月に記録した事実が、プロジェクトの状況が変わった6月にも同じ確信度で読み込まれます。AGENTS.mdと同様に、memory systemにも不要な情報を整理する作業が必要です。

使用例：

「Postgresを使っていて、MySQLではないと何度も伝えています。」

「memory systemを設定しましょう。最初のturnで学んだことをfilesystemに書き、sessionの開始時に読み込みます。model自体はstatelessですが、メモリーレイヤーが連続性を補います。」

environment内のファイルで、harnessがsessionの開始時にcontext windowへ読み込みます。プロジェクトがagentに常時伝えるbriefです。harnessをまたいで使われる慣習ですが、harnessによっては独自の版もあります（Claude Codeの場合はCLAUDE.mdです）。

自動で読み込まれるため、sessionごとに同じ説明を繰り返さずに済みます。modelはstatelessです。あるsessionで伝えた修正は次のsessionには引き継がれず、pnpmを使うこと、特定のフラグでテストを実行すること、あるディレクトリは生成物なので触らないことを、新しいsessionごとに説明することになります。同じ点でagentを2回修正したなら、その修正内容をAGENTS.mdに加える候補として考えられます。

コードからは導き出せない情報なら、適切な内容です。ビルドとテストのコマンド、コードベースからは分かりにくい慣習、「生成されたclientは絶対に編集しない」といった厳しい制約などです。ドキュメントではなくbriefなので、短く、宣言的に書きます。

代償は、内容がすべて常に読み込まれることです。指示は積み重なり、その多くは個々のタスクには関係ありません。長いAGENTS.mdはtokenを消費するだけでなく、自分自身の有効性も薄めます。contextに指示が増えるほど、そのひとつひとつにagentが従う確実性は下がります。

避ける使い方： progressive disclosureにするべき内容をAGENTS.mdに入れること。そこに置いた内容は、必要かどうかに関係なく、すべてのsessionのすべてのturnでtokenコストが発生します。style guideはskillやcontext pointerの先に置けます。AGENTS.mdには全体に適用する指示だけを残してください。

使用例：

「どのsessionも、なぜ最初から4k tokenも使っているんですか？」

「AGENTS.mdを確認してください。skillの後ろに置くべきなのに、誰かがstyle guide全体を貼り付けています。」

agentが今必要としているcontextだけを読み込み、残りの情報にはcontext pointersを置く方法です。UI designの考え方に由来します。ユーザーに現在の作業に関係するcontrolだけを見せ、それ以外はクリックの先に隠します。

contextには二重のコストがかかるため、この手法が必要です。最初に読み込むtokensは、すべてのturnでinput tokensとして課金され、agentが必要としていなくてもattention budgetを使います。style guide全体、deploy手順書、データベースの規約を詰め込んだAGENTS.mdは、そのすべてについてagentの能力を下げます。今のタスクに必要な指示が、不要な指示によって薄まるからです。contextにあるはずのルールをagentが無視するときは、ルールが存在していても埋もれている兆候です。

Progressive disclosureはこれを逆転させます。常時読み込む部分を小さく保ち、話題ごとに一文と詳しい情報へのpointerを置きます。agentはcomponentを書くときにstyle guideを読み、deployするときにdeploy手順書を読み、テストを直すときにはどちらも読みません。Skillsは、harnessに組み込まれたこのpatternです。短い説明を各sessionで読み込み、詳しい指示は必要なときだけ読み込みます。

使用例：

「style guide全体をAGENTS.mdに入れるべきですか？」

「いいえ、progressive disclosureを使いましょう。agentがcomponentを書く必要のあるときだけ読み込むskillとしてstyle guideを参照してください。AGENTS.mdでは毎turn tokenコストがかかります。」

ある文書から別の文書を指す記述です。タスクで必要になったときだけ、agentがそれをcontext windowに取り込めます。progressive disclosureは、この仕組みを組み合わせて実現します。

内容をそのまま埋め込まずにpointerを使う理由は、コストです。pointerならcontext windowに1行で済みます。参照先の文書が何千tokensあっても、agentがpointerをたどるまではtokenコストがかかりません。2,000-tokenの手順書をAGENTS.mdに埋め込めば、すべてのsessionがそのコストを負います。「deploy手順：`internal/deploy.md`を参照」と置き換えれば、その文書を読み込むのはdeployするsessionだけです。タスクが該当したときに、agentはtool callでpointerをたどります。

pointerが機能するには、安定したパスと、いつ参照すればよいかをagentが判断できるだけの説明が必要です。説明のないパスだけでは、たどる理由がありません。「`internal/deploy.md`を参照」だけでは、その中身が分からず、必要としているsessionにも見過ごされます。タスクの現れ方に合わせた記述にします。「release、deploy、rollbackを行う前に、まず`internal/deploy.md`を読む」。

pointerは、見回すといたるところにあります。AGENTS.md内の行、skillの説明（harnessが説明を読み込み、skill本文はその先に置かれます）、ディレクトリ一覧にあるファイル名、ドキュメント間のリンクなどです。

pointerは、secondary sourceを、それが元にしたprimary sourceへ結び付けるためにも使えます。元の会話記録を示すcompactionの要約や、説明対象の元ファイルを示す文書などです。要約だけでは足りないと分かったとき、pointerをたどって元資料を読めばよいため、secondary sourceで失われた情報を復元できます。

避ける表現：「reference」は堅すぎて、たどると追加のcontextが読み込まれることを表せません。「portal」は大げさです。

使用例：

「AGENTS.mdが大きくなりすぎています。」

「大半は内容そのものではなくcontext pointerにするべきです。常時適用するルールはその場に残し、deploy手順書とstyle guideはskillにして、context pointerを残してください。」

ひとつの単位にまとめた、教えられる能力です。ある作業をうまく行うための指示とリソースを含み、必要なタスクでcontext pointerがcontext windowに読み込むまでenvironmentに置かれます。harnessにおけるprogressive disclosureの単位です。

Skillsは公開標準であり、agentskills.ioで定義されています。Anthropicが最初に開発し、その後、主要なharnessの多くが採用したため、一度書いたskillを複数のharnessで使えます。フォルダーには次の内容を含めます。

• `SKILL.md`ファイル — metadata（最低限、名前と説明）と指示本文
• 任意で、agentが実行できるスクリプト
• 任意で、指示から参照するテンプレートや参考資料

既定では名前と説明だけがcontextに置かれます。agentのタスクに合致すると、残りの内容を読み込みます。それまではskillが占める領域はごくわずかです。完全な指示がどれほど長くても、数行のtokensで済みます。

この点が、タスクに関係なくすべてのsessionに読み込まれるAGENTS.mdとの違いです。skillは、release、新しいサービスのscaffolding、migrationの作成など、特定の種類の作業が始まったときに読み込まれ、それ以外では読み込まれません。

避ける表現：「tool」。toolはagentが呼び出すもので、skillはagentが読む指示です。

使用例：

「deploy手順書はどこに置けばいいですか？」

「skillにしてください。agentはdeploy関連のタスクのときだけ読み込みます。AGENTS.mdに置くと、週に一度しか使わない内容のために、すべてのturnでtokenを消費します。」

別のagentがtool callを通じて起動したagentです。独自のsessionとcontext windowで動き、ひとつのtool resultを親に返します。handoffとは異なり、親は戻ってくることを明確に期待しています。さらにsubagentを起動することはできません。ツリーは1階層です。subagentはcontextを分離するために存在し、階層を重ねるためのものではありません。

親のcontextを騒がしい作業から守るのが目的です。広範囲の検索や、長時間にわたるファイル調査では、答えを探すためだけに大量のtool resultが生まれます。親の中で実行すると、その大部分がsessionの残りの間ずっと親のcontextに残ります。subagent内で実行すれば、使い捨てのwindowに雑音を集められ、最終報告だけが親のcontextに届きます。報告はsecondary sourceです。親が受け取るのはsubagentが見つけた内容の説明で、元の結果ではありません。報告に書かれなかった内容は親には見えません。

subagentは並行して動かすこともできます。親は、互いに独立した作業を複数のsubagentに同時に任せられます。

使用例：

「grepの結果でcontextがいっぱいになりそうです。」

「subagentに検索を任せましょう。雑音を自分のcontext windowに集め、必要なファイルパスを2つだけ報告してくれます。」

ひとり以上の人間がsession中にagentと組み、リアルタイムでレビュー、軌道修正、共同作業をする進め方です。人間は存在して関与しており、個々の操作を承認するだけではありません。

対照的なのはAFK作業です。agentが人間の監督なしで動き、結果をあとで評価します。human-in-the-loopなら、問題がまだ安く直せる段階で見つけられます。agentが誤ったファイルを開こうとする、要件を読み違える、行き止まりに向かっているといった様子を確認し、ひと言で方向を修正できます。自信満々なまま進んだ作業を20分後に見て気づくのではありません。agentは自分が道を外れたことに気づくのが得意ではありません。放っておくと、停止して質問するより、そのまま作業を進めがちです。

どちらの進め方が合うかは、作業内容によります。仕様が明確で、リスクが低く、検証しやすい仕事ならAFKが向いています。曖昧なもの、取り消せないもの、完成結果をレビューしにくいもの、たとえばschema migrationや難しい設計判断、本番環境に触れる作業では、進行を見守るのが適しています。判断基準は、誤りがどれほど高くつくか、そして気づくのがどれほど遅くなるかです。

あなたの反応そのものが入力になるため、最初からin-the-loopで行う作業もあります。Grillingでは質問に答える人が必要で、prototypingでは成果物を見て反応する人が必要です。

ループにとどまると注意力を使います。注意力は希少な資源です。agentをうまく使うには、計画、automated checks、最後のhuman reviewを取り入れ、全工程を監督する作業を安全に減らす必要があります。software factoryは、トリガーからsessionを開始し、作業の開始そのものも人間に不要にします。

使用例：

「これを一晩AFKで動かしますか？」

「いいえ、schema migrationです。human-in-the-loopで進めてください。各段階を確認し、backfill元の列を間違えて選んだら方向を変えたいです。」

キーボードから離れている状態です。ユーザーがsessionを始め、agentを無人で実行させる進め方です。AI codingの処理量を増やします。人が眠ったり、食事をしたり、別の作業をしたりする間に、多数のAFK sessionを並行して実行できます。安全に行うには通常、寛容なpermission modeとsandboxingが必要です。

あなたがいない間、agentは曖昧さを別の方法で処理します。見守っているときなら、判断に迷う点は質問として提示され、あなたが答えます。離れた後は、agentが既定値を選んで作業を続け、その推測を土台に以降の判断を重ねます。よくある失敗は、最初の10分で誤った判断をしたまま、自信に満ちた何時間分もの作業が完成した状態で戻ってくることです。雑な仕事ではなく、誤ったことについて筋の通った仕事ができあがります。

実行中に入力できないので、前後に入力を与えます。実行前には曖昧さを解消します。grilling sessionや書面のspecを使い、agentが単独で補う箇所を減らします。実行中は、あなたが見守れない代わりにautomated checksとautomated reviewを使い、機械的に検出できる問題をすばやく見つけます。実行後は、すでにmerge済みの変更ではなく、PRのようなレビュー可能な成果物を残します。AFKはhuman reviewをなくしません。最後にまとめて行うだけです。そのため、最後に届くものがレビューする価値のある状態でなければなりません。AFK実行ではAXが特に重要です。見守る人がいないとき、agentを支えるのはenvironmentだけだからです。

避ける表現：「background agent」は、ユーザーが離れたという進め方ではなく、機械が「バックグラウンドで動く」ことに焦点を当てます。重要なのは、ユーザーが見守っていないという事実です。

使用例：

「これをAFKで動かします。refactorをsandbox内のagent3つに任せ、朝PRをレビューします。」

「権限をバイパスしますか？」

「そうです。読み取り専用のfilesystemにして、network accessはなしです。」

environmentで実行される、決定論的な検証です。テスト、型チェック、lint、ビルド、pre-commit hookなどが該当します。合否を判定し、判断は行いません。agentがほかの人に頼らず自分で誤りを修正できるシグナルです。不安定なテストは、チェックではないのではなく、壊れたチェックです。自動チェックは設計上決定論的です。

自己修正はループとして進みます。agentが変更を加え、tool callとしてチェックを実行すると、失敗の出力がcontext windowに届きます。たとえば、ファイル名と行番号を示す型エラーや、期待値と実際の値を示すアサーション失敗です。それだけあれば、agentは問題を修正して再度チェックを行い、成功するまで人間を介さずに繰り返せます。同じコードが常に同じ判定を返すため、合格に意味が生まれ、このループは信頼できます。不安定なチェックがあると、この仕組みは損なわれます。問題のないコードをagentが「修正」したり、本当の失敗を無視して再試行を続けたりします。

優れたチェックがコードベースのAXの大きな部分を占めるのはこのためです。型を厳密に適用し、高速なテストスイートとlinterがあるリポジトリなら、agentはユーザーに見せる前に多くの誤りを自分で見つけます。そうしたものがないリポジトリでは、agentは生成したものを何でも出荷します。この違いが特に重要なのはAFK実行中です。実行中に行われる検証はチェックだけだからです。ただし、チェックが捕捉できるのは、アサーションに書かれた内容だけです。合格は、アサーションの条件が満たされたことを意味し、コードが正しいことまで保証しません。判断を要する部分はautomated reviewとhuman reviewが担います。

避ける表現：「feedback loop」や「backpressure」は、チェックとレビューをひとまとめにしてしまいます。「test」も避けてください。テストは自動チェックの一種ですが、自動チェックのすべてがテストではありません。

使用例：

「agentはAFK実行で壊れたコードを何度も出荷しています。」

「sandboxにはどんな自動チェックが組み込まれていますか？」

「unit testだけです。」

「typecheckとlintも追加してください。PRが出る前に、それらの結果を使って自分で修正できます。」

別のagentの作業をレビューするagentです。多くの場合、別のmodelやsystem promptを使います。決定論的ではなく、判断を下します。PRのmerge前、commit履歴の事後確認、またはsession中にsubagentとして、さまざまな場所で実行できます。CIでLLMを審査役に使うのはautomated reviewであり、automated checkではありません。実行場所ではなく、アサーションが何を行うかで分類が決まります。

作業中のagentから分離することで機能します。コードを書いたagentに自分の作業をレビューさせても、ほとんど得るものはありません。バグを生んだsessionには、その判断に至った推論も残っており、agentは自分の結論を読み返して正しいと確認してしまいます。新しいcontext windowを使うレビュアーには、そうした思い入れがありません。見知らぬ人のようにdiffを見ることができ、それがレビューには欠かせません。別のmodelやレビュー専用のsystem promptを使えば、さらに効果が高まります。盲点の異なるmodelを使い、漠然と「問題を探す」のではなく、セキュリティ、API契約、性能など、関心のある範囲にsystem promptを絞れます。

ほかのレビュー層の中間に位置します。自動チェックは決定論的で、機械的にアサートできる内容を検出します。human reviewはコストが高く、拡張もしにくい方法です。automated reviewは中間にあり、誤解を招く関数名や見落とされた例外ケースなど、判断を要する問題を機械のコストで検出します。決定論的でないため、見落としや問題のない箇所への指摘も起こります。人間のレビューを置き換えるゲートではなく、人間が見る前に最低水準を引き上げるフィルターとして扱ってください。

避ける表現：「AI review」「agent review」は、作業中のagentと区別できないほど曖昧です。

使用例：

「AFK実行から質の低いPRが届きすぎています。」

「merge前にautomated reviewを追加しましょう。別のmodelと専用のsystem promptを使い、セキュリティと契約変更に範囲を絞ります。」

agentが作成したコードをユーザーが読み、評価することです。diffや変更ファイルを読むのは該当しますが、agentによる説明を読むだけでは該当しません。説明は成果物ではありません。説明はレビュー対象の当事者が書いたsecondary sourceであり、diffはprimary sourceです。reviewとは後者を読むことです。

agentが生成するコード量が増えると、レビューがボトルネックになります。異なるreview方法を重ねるのが有用です。Automated checksは機械的な失敗を検出し、automated reviewは言葉で説明できる問題を見つけます。人間のreviewは、変更そのものが適切か、コードベースに合う方法か、そもそも必要かなど、人間にしか判断できない点に使います。

reviewは早い段階ほど安く済みます。作業前に計画を読む、作業途中で小さなdiffを見るのは数分で済みます。AFK実行後に完成済みのbranchを掘り起こすと、もっと時間がかかります。どこにreviewのcheckpointを置くかは、後回しにすることではなく、human-in-the-loopにするかどうかの判断です。

避ける表現：「code review」だけでは、人間のレビューと自動レビューのどちらか曖昧です。

使用例：

「AFK出力を人間がreviewしました。」

「diffを読みましたか、それとも要約だけですか？」

「diffです。要約には不要コードを削除したとありましたが、関数は生成ファイルから呼び出されていました。」

ユーザーがhuman reviewなしにagentのコードを受け入れる進め方です。diffは中身の分からないものとして扱い、コードの内容ではなくプログラムの挙動を基準にします。Automated reviewやautomated checksが実行されることはありますが、vibe codingはそれらについて何も決めません。

この用語は、Andrej Karpathyが2025年初めに考案したものです。「雰囲気に完全に身を任せ」「コードが存在することさえ忘れる」ように、欲しいものを説明し、返ってきたものを受け入れて、実行して判断します。

vibe codingでは、確認を省いて速度を優先します。agent主体の作業ではdiffを読むのが通常最も時間のかかる工程なので、それをやめれば主なボトルネックがなくなります。失敗しても損失が小さいコード、たとえばprototypes、使い捨てのスクリプト、内部ツールでは、妥当なトレードオフです。リスクは、コードが使われる期間と重要度に応じて大きくなります。

代償が現れるのは後です。vibe codingによる変更が、誰も読んだことのないコードベースに積み重なります。確認したのは挙動だけなので、挙動に表れない問題、たとえばログに記録された秘密情報、考慮漏れの例外ケース、気づかれないデータ処理の誤りなどが見えないまま出荷されます。誰かが初めてシステムをデバッグするときが、そのコードを初めて読むときです。human reviewをなくすと、テスト、型チェック、automated reviewなど、残った自動検証だけがコードを通す唯一のゲートです。同じ進め方をコードベース全体、またはその一部に適用し、変更をsoftware factoryから加えるのがdark factoryです。

避ける表現：「vibe coding」を「品質の低いAIコーディング」の同義語として使うこと。この語が指すのはレビューの姿勢であり、できあがるコードの品質ではありません。

使用例：

「auth flowで何を変更したか読みましたか？」

「vibe codingでした。ログインがまだ動くことだけ確認しました。」

「pushする前にdiffを読んでください。authをvibingで進めると、秘密情報がログに漏れます。」

何を作るかについて、ユーザーとagentが共有する理解です。どの成果物とも別に存在します。Brooksが『The Design of Design』で使った用語です。会話、handoff artifacts、コードはどれもdesign conceptを捉えたり実現したりするための成果物ですが、そのものではありません。design conceptの質は、それを作り上げた会話の質に表れます。

この用語は、よくある不満の背後にある隔たりを表します。agentは依頼どおりに書いたのに、結果は間違っています。よくある原因は、あなた自身が望むものを十分に整理できていないことです。design conceptがまだ頭の中で完成しておらず、promptには考えた部分だけが書かれ、未整理の部分は何も書かれていません。agentは何に合わせればよいか分からないため、その空白を自分の仮定で埋めます。何かが故障したのではありません。共有するdesign conceptそのものがまだ完成していないので、共有されていなかったのです。

同僚と同じように、まだ聞いていない質問にも相手が自分の考えに沿って答え始めたとき、design conceptが共有されていると分かります。それまでは会話を続けます。grillingは意図的に質問を重ねる方法です。早くspecを書いても、認識のずれをより長く残る成果物に記録するだけです。学びに応じてdesign conceptも変わりますが、成果物はそれに遅れて更新されます。そのため、先週の理解に忠実なspecでも、今週のsessionを誤った方向へ導くことがあります。

使用例：

「頼んだとおりに書いているのに、まだ間違っています。」

「まだdesign conceptを共有できていません。agentが仮定で空白を埋めています。cancel、返金、部分的な履行が双方で一致するまで話し合い、それからspecを書かせてください。」

agentと一緒にdesign conceptを作り上げる手法です。agentが一度にひとつの判断についてユーザーにソクラテス式の質問をし、それぞれに推奨案を提示します。完成した計画へ急ぐのを抑え、コンセプトが固まるまでhandoff artifactを書きません。

agentは不足している情報を黙って補うため、この手法があります。2行のプロンプトからspecを書くよう頼むと、未決の判断を保留せず、既定値を選んで書き込みます。仕上がったように見え、推測と選択の区別がつかないため、レビュー時や、実装した機能が選んでいない方法で例外ケースを処理したときになって初めて気づきます。Grillingはこの逆を行います。agentが推測するのではなく、質問しなければ進めないようにします。

これはhuman-in-the-loopの手法です。入力になるのはあなたの回答です。会話だけでは答えられず、実物を見る必要がある質問なら、prototypingに切り替えてください。

使用例：

「specを書き始めて、キャンセル処理のロジックを間違えました。」

「まずGrillしてください。ドキュメントに書き込む前に、部分キャンセル、返金、タイミングについて質問させましょう。コードにしてから直すより、会話で決めるほうが安上がりです。」

会話だけでは精度が足りず、話し合うための実物が必要なとき、agentに簡易的で粗いものを作らせることです。

Grillingは会話で設計上の判断を解決します。会話は安上がりですが、精度には限界があります。操作感、実際のcall siteでAPIの形が使いやすいか、実データ量でlayoutが成り立つかなど、言葉だけでは答えられない問いもあります。質問への正直な答えが「見てみないと分からない」なら、面接形式のやり取りを続けても先に進みません。その場合はagentに作らせ、実物を見てから会話に戻りましょう。

agentによって作成コストが下がったからこそ、この方法が実用的になりました。以前ならモック作成に丸一日かかった粗い試作品も、今は数分でできます。そのため、日常的に行う価値があります。これはhuman-in-the-loopの手法で、試作品に対するあなたの反応を得ることが目的です。

通常は一度見て終わりではありません。試作品を見て反応し、変更を頼み、もう一度反応するという反復を通じ、会話より高い精度で実物に対する判断をひとつずつ確定していきます。

試作品をすべて粗いままにする必要もありません。評価対象の部分だけを本番品質で作成すれば、判断が確定したとき、その部品やAPIを実際のコードベースに移せます。だから、specに参照用の素材として試作品を含めることが重要です。

使用例：

「wizardを1ページにするか、3ステップにするか、30分も議論しています。」

「言葉だけでは決まりません。agentに両方を試作させましょう。操作してみれば、5分で分かります。」

Developer experienceとは、コードベースとtoolchainによって、人間がどれだけ容易によい仕事をできるかを表します。優れたDXには、迅速なフィードバック、明快なエラーメッセージ、実際の疑問に答えるドキュメント、最初の試行でうまくいくセットアップがあります。この言葉はAI codingよりもずっと前から使われています。この辞書では、主にAXと対比するために取り上げています。

DXは人間とコードベースの相互作用であり、それ以上のものではありません。両者の主な違いは、人間がstatefulでagentはstatelessという点です。人間は一度コードベースを学べば、その知識を日々の作業に生かせます。そのため、DXが悪くても何とかやっていけます。遅いCIに対してはpushをまとめ、ドキュメント不足に対してはSlackで一度質問し、分かりにくい構造に対してはファイルの場所を覚えて対応します。回避策が積み重なり、チームは使いにくさに抵抗しながらもコードベースで生産的に仕事をするようになります。

Agentsは、そうした蓄積のない状態で同じコードベースに向き合います。sessionsをまたいでstatelessなので、毎回コードベースを一から学び直します。高速なテストスイートや明快なエラーメッセージは役立ちますが、昨日理解した内容も、それがenvironmentに書かれていなければ失われます。agentはenvironmentをtool resultsを通じてしか認識できません。これがAXの指す差です。開発者がagentの場合にも役立つDXの要素に加えて、人間にはない関心事、たとえばcontext windowに余裕を保つことが含まれます。

両者が重なるため、DXへの投資でAXも自然に改善することがよくあります。厳格な型、高速なテスト、予測しやすい構造はどちらにも有効です。ただし、必ずしもそうとは限りません。美しいオンボーディング文書は人間には1週間役立ちますが、AGENTS.mdから参照できなければagentには役立ちません。

使用例：

「うちのDXは問題ありません。新入社員は1週間で生産的になります。」

「その1週間ずっと誰かが一緒にいるからです。agentにその1週間はありません。AXは別に確認してください。」

agent experience、つまりコードベースでagentがどれほどよい仕事をできるようenvironmentが整備されているかを表します。agentを使う開発者向けのDXに相当します。同じmodel、同じharnessを使っていても、あるリポジトリではよく働き、別のリポジトリではうまくいかないことがあります。その違いはたいていAXにあります。modelを責めたり、プロンプトを書き直したりしたくなりますが、原因は多くの場合リポジトリ側です。

優れたAXには主に3つの側面があります。

AXとDXには重なる部分があります。優れたチェックと明快なアーキテクチャはどちらにも役立ちますが、異なる部分もあります。人間は暗黙の知識、遅いCI、「課金モジュールはSarahに聞いて」という状態を許容できますが、agentには通用しません。agentにはIDEのツールチップや見栄えのよいダッシュボードは役立ちません。tool resultに文字で示された失敗が必要です。DXが優れ、AXが劣るコードベースもあり得ます。

避ける表現： AXをDXの同義語として扱うこと。それぞれ異なる相手に向けた投資が必要です。

使用例：

「APIのrepoではすばらしいコードを書くのに、frontendではひどいコードを出します。」

「API repoには厳格な型と高速なテストスイートがありますが、frontendにはそのどちらもなく、常時読み込むskillが40個もあります。これはmodelではなく、AXの差です。」

人間が開始するのではなく、トリガーをきっかけにagentのsessionを開始する作業システムです。issueの作成、スケジュール、CIの失敗、別のsessionの終了などがトリガーになります。その結果、より多くの作業をAFKで進められ、人間の注意は残ったhuman-in-the-loopの判断に使われます。

factoryがなければ、すべてのsessionは誰かが始めることで開始します。完全にAFKで実行できる作業でも、人がsessionを開き、ticketを指定して、実行を始めるまで待つことになります。それではチームが出荷したい量に届きません。factoryはsessionの開始から人間を外しますが、ほかの工程からも外すとは限りません。

一般的なトリガーと、それによって開始するsession：

factoryがソフトウェア開発の全工程を担う必要はありません。ひとつの種類のsessionを実行し、レビュー可能なPRをひとつ開くcron jobもfactoryです。小さく始めるとよいでしょう。対象を絞ったループなら、小規模で似たPRを生成できます。それらをレビューすれば、ループにどこまで任せられるかを確かめてから範囲を広げられます。

factoryのどの場所にも人間が関われます。sessionのトリガーになるissueを書いてラベルを付ける、実装の前に計画を承認する、merge前にhuman reviewを行うなどです。そのうち何を人間の判断として残すかが、設計上の主な問いです。factoryの出力を人間がまったくレビューしないコードベース、またはその一部がdark factoryです。

使用例：

「`no-floating-promises`違反を全部直したのは誰ですか？」

「factoryです。cron jobが毎晩lintルールをひとつ選び、PRを開きます。私は朝レビューするだけです。」

software factoryがコードを書き、人間は誰もそれを読まないコードベース、またはその一部です。human reviewはありません。作業を始めるissueを人間が書くことはありますが、できあがったコードを読む人はいません。名前は、工場の作業員がいない「無人操業」から来ています。

ダークファクトリーとは、ひとつの変更ではなく、コード領域に対するvibe codingです。vibe codingでは、自分が依頼した変更を読まないことを選びます。それでも、その変更が存在することは分かっています。ダークファクトリーでは、チームが領域全体について一度その選択をします。その後、変更ごとに誰かが依頼したり確認したりすることはありません。新しい作業を始めるトリガーが発生するたび、変更が次々と届きます。

問題が表面化するのは、何かが壊れたときです。変更を読む人がいないので、何が変わったのか分かりません。チームの誰も読んでいないコードをデバッグしなければならず、原因は多数の変更のどれかにあり得ます。それらはすべてチェックを通過しています。

唯一のゲートはAutomated checksとautomated reviewです。問題を見つけられなければ、その問題はコードに入り込みます。

避ける表現： 工場が誰にも見られず稼働しているという理由だけで、コードベースを「ダーク」と呼ぶこと。agentのsessionがAFKで進んでも、人間がPRをレビューするなら、それはsoftware factoryです。ダークファクトリーではありません。

使用例：

「課金サービスのretryロジックを変えたのは誰ですか？チームの誰も覚えていません。」

「課金サービスはダークファクトリーです。CIを通った変更はagentがすべてマージします。あの変更を読んだ人はいません。」