writing-for-agents

エージェントを作成する人が読むあらゆる文書のためのリファレンスです。スキル、AGENTS.md / CLAUDE.md、ポインターを介してアクセスする文書など、形式はさまざまですが、執筆ルールは共通です。同じ工夫によって、すべての文書を予測可能にできます。エージェントが実行のたびに行うのは、同じ出力を生成することではなく、同じプロセスをたどるからです。

作成中の文書がスキルの場合は、前提メタデータ、呼び出し方の選択、ルーティングスキルについて説明した SKILL-MECHANICS.md をお読みください。

コンテキストポインター

コンテキストポインター（context pointer） は、エージェントのコンテキスト内にある参照で、コンテキストの「外」にある資料を指し、その資料にアクセスする条件を定めています。スキルの description はその一例です。AGENTS.md にある文書への参照行も同じものです。エージェントがその資料にいつ、どの程度確実にアクセスするかを決めるのは、参照先ではなくポインターの文言です。本来アクセスされるべき資料が、曖昧な文言のポインターの背後に隠れているなら、それは分散のバグです。まず文言を磨き、それで解決しない場合にだけ資料を直接インライン化してください。

ポインターには二つの役割があります。その資料が何かを示し、アクセスを引き起こすべき分岐（branchはこの文書が扱う独立した状況であり、実行ごとに異なる経路へ進む可能性があります）を列挙します。常に読み込まれるポインターでは、そこにある一語一語が毎ターンコストになります。そのため、本文よりも厳しく簡潔にする必要があります。

• 「引導語」を前に出す：ポインターは、作業が実際に始まる場所です。
• 一つの分岐につき一つのトリガー語を使う。 同義語で同じ分岐を言い換えても、実質的には一つの分岐です。本当に異なる分岐だけを残し、まとめてください。
• 本文ですでに示されている概要情報を取り除く。

二種類の負荷

追加する文書やポインターは、二種類の負荷のいずれかを発生させます。

• コンテキスト負荷（Context load）：常に読み込まれる資料がエージェントのウィンドウを占有するコストです。AGENTS.md の一行、スキルの説明など、トリガーされるかどうかにかかわらず、コンテキスト内に常に残り、トークンと注意力を消費するものが該当します。
• 認知負荷（Cognitive load）：人間が負うコストです。どの文書が存在し、それぞれをいつ使うかを把握する負担です。人間がそのインデックスになります。これは最小化すべきコストではありません。人間の主体性を保つための代償です。人間の判断が必要な箇所に負荷をかけ、不要な箇所では取り除いてください。

ポインター経由でのみアクセスする資料は、ポインター自体の一行分を除いて、コンテキスト負荷を回避できます。ポインターがまったくない資料は、完全に認知負荷に依存します。

情報の階層

文書は二種類の内容で構成されます。エージェントが順番に実行する動作である手順（steps）と、必要に応じて参照する定義、ルール、事実であるリファレンス（reference）です。両者は自由に組み合わせられます。すべてが手順の文書（操作ガイド）、すべてがリファレンスの文書（このスキルのようなレビュールール）、またはその両方を含む文書があり得ます。重要なのは、それぞれの内容を情報の階層のどの段に置くかを決めることです。これは、エージェントが資料をどれほど差し迫って必要としているかに応じて並んだ梯子です。

1. ファイル内の手順（In-file step） は最上位の段です。エージェントが順番に実行する内容です。
2. ファイル内のリファレンス（In-file reference） は必要に応じて参照します。平坦な同階層の集合（各レビュールールが一段に相当するなど）が適切な場合も多く、問題ではありません。
3. 開示型リファレンス（Disclosed reference） は独立したファイルに移し、コンテキストポインター経由でアクセスします。そのポインターがトリガーされたときだけ読み込まれます。同じフォルダー内の隣接ファイルから、どこに置かれた完全に外部のリファレンスまで、範囲はさまざまです。どの文書からでも参照できます。

下位に移し足りないと最上位が膨らみ、移しすぎるとエージェントが本当に必要とする資料が隠れてしまいます。この緊張関係こそが、判断の要点です。

段階的開示（Progressive disclosure） とは、最上位を明快で読みやすく保つために、この梯子を下りる（主文書から移し、ポインターの背後に隠す）ことです。主な目的はトークンの最適化ではありません。階層を守るための手段です。分岐は、開示すべきかを判断する最も明快な基準です。すべての分岐で必要となる内容はインライン化し、一部の分岐でしか参照されない内容はポインターの背後に移します。手順がある文書で、本来開示すべきファイル内リファレンスが手順に埋もれると、それに注意を向けるかどうかが運任せになります。これは分散に影響する工夫であり、単なる読みやすさの工夫ではありません。

同居（Co-location） は、同じファイル内における相補的な考え方です。階層は内容をどれほど深く置くかを決め、同居はその場所で何を一緒に置くかを決めます。概念の定義、ルール、注意事項をあちこちに散らさず、同じ見出しの下にまとめます。そうすれば、ある箇所を読むとき、その隣にある内容も目に入ります。文書はエージェント向けに書かれているように読めるべきです。まとまった資料はそう読めますが、散らばった資料はそう読めません。（これは「重複」とは異なります。重複は同じ意味を二度述べること、散在は一つの意味を複数の断片に分けることです。）

肥大化（Sprawl） は、ここでの失敗パターンです。各行に意味があり、独自の情報を含んでいても、文書が単純に長すぎる状態です。冗長さの中で注意力は薄れ、行が増えるたびに関連性を保つ保守負担も増します。対処法はこの梯子です。リファレンスをポインター経由で開示し、分岐または順序に沿って分割することで、各経路に必要な内容だけを含めます。

手順と完了基準

各手順は完了基準で締めくくります。エージェントに「作業完了」と知らせる条件です。これが効果を発揮する理由は、二つの性質にあります。

• 明確さ（Clarity）：エージェントは完了と未完了を区別できますか？「理解に至る」のような曖昧な境界は、早期完了を招きます。手順が本当に完了する前に終えてしまい、注意力が「完了した状態」へ滑っていきます。まだ見えている後続の手順（後続手順）は先へ進む力になりますが、完了基準の明確さはそれに抗う力です。順番に対処してください。まず境界を磨きます（局所的で低コストです）。境界そのものが本質的に曖昧で、かつ急いで進める傾向が観察された場合にのみ、順序を分割して後続手順を見えなくします。隠すことが有効なのは、本物のコンテキスト境界（引き継ぎやサブエージェントへの委任）をまたぐ場合だけです。インライン呼び出しでは後続手順がコンテキストに残り、何も取り除かれません。
• 要求度（Demand）：どれほどの作業を求めるかです。「変更されたモデルをすべて記録する」は「変更一覧を作成する」よりも、徹底的な作業を促します。要求度は**下調べ（legwork）**を促します。これは作業の中でエージェントが行う掘り下げであり、独立した手順として明記されるのではなく、文言に潜んでいます。また、下調べは手順だけに結びつくものではありません。「すべてのルールを適用する」は、平坦なリファレンス全体を拘束します。「すべての手順を完了する」が一連の手順を拘束するのと同じです。そのため、リファレンスだけの文書も「網羅性」の基準を担います。

最も強い完了基準は、検証可能であり、かつ網羅的です。

分割するタイミング

文書を二つに分けると、二種類の負荷のいずれかが発生します。そのため、分割が「見合う」場合にだけ分けてください。

• 順序による分割：手順の途中に後続の完了済みステップがあり、エージェントがその前の手順を急いで終えるよう誘発する場合に分けます。後続手順を見えなくすることで、現在の作業により多くの下調べをさせます。逆方向の操作には注意してください。手順を統合すると、各ステップの「後続手順」が次に起こることより前に見えるため、早期完了を誘発します。
• 呼び出し方による分割：スキル特有の分割方法です。詳細は SKILL-MECHANICS.md を参照してください。

引導語

引導語（leading word） とは、モデルの事前学習にすでに含まれている簡潔な概念であり、エージェントが文書を実行するときに思考のよりどころとする語です（lesson、fog of war、tracer bullets）。これは一つのトークンとして機能します。文ではなく、繰り返し使うことで、最小限のトークン数で分散的な定義を積み上げ、モデルがすでに持つ事前知識を呼び起こして、一連の振る舞いを方向づけます。新しい語を作ってもかまいませんが、明確に定義する必要があります。造語では既存の事前知識を呼び起こせません。事前学習済みの語なら無料で得られるものを、定義のトークンで支払わなければならないため、まずは既存の語を探してください。

引導語は二度、効果を発揮します。本文では、_実行_のために使います。その語が出てくるたびに、エージェントは同じ振る舞いを呼び起こします。平坦なリファレンスでは、探すべきものに注意を向けます。ポインターでは、_呼び出し_のために使います。同じ語がプロンプト、文書、コードベースに現れると、エージェントはその共通の言葉と資料を結びつけ、より確実にアクセスします。

引導語を使って再構成できる機会を積極的に探してください。三か所に展開されている三項の組み合わせや、ある考えを一文でほのめかすポインターなどです。どれも、一つのトークンに圧縮できる箇所です。

• 「fast, deterministic, low-overhead」→ tight（tight なループ）。
• 「a loop you believe in」→ red。曖昧なゲートを、二値で観察可能な状態に変えます（バグがあるとループが red になり、なければ red になりません）。

二つの成果が得られます。トークンが減り、エージェントの思考を留めるための、より鋭い「引っかかり」を与えられます。どの文書にも、引導語で置き換えられる言い換えが含まれていると考えてください。探してください。

**否定（Negation）**は、この工夫に隣接する失敗パターンです。禁止で方向づけると、禁止対象の振る舞いをコンテキストに引き込み、アクセスしにくくするどころか、しやすくしてしまいます。「象を考えるな」と言えば、象が浮かびます。否定は弱い修飾表現にすぎず、強く活性化された概念に押し負けて、禁止が「これを実行せよ」と半ば読み替えられるからです。肯定形で指示してください。目標とする振る舞い（たとえば「一行コメントを書く」）を述べれば、禁止対象について言及する必要がなくなります。禁止を肯定形にできない場合にのみ、禁止形が妥当です。その場合でも、肯定的な目標と組み合わせ、注意が「何をすべきか」に向くようにしてください。

修剪

• 让每一种含义只放在单一权威来源：一个权威之处，所以修改行为只改一处。重复（Duplication）（同一含义出现在不止一个地方）既消耗维护成本也消耗 token，并且把一个含义在层次结构上的显著度抬高，超过它真实的位次。（这是"引导词"的意外反面：引导词是有意重复一个 token、绝不重复含义。）
• 环境也是一种权威来源（package.json 脚本、配置文件、目录布局、--help 输出），而把环境复述一遍的文档就是一份缓存（cache）：一份"查找"的副本，只有当这次查找代价高昂时才赚得回来。缓存那些智能体通过查找得不到的东西：未被写下的惯例、选择背后的原因、配置不会坦白的小坑。把那些"一个文件、一条命令"就能查到的查找，交给环境本身，它永远不会过时。
• 逐行检查相关性：这一行还在支撑这份文档要做的事吗？一行会失去相关性，要么因为它从未真正承担过这个任务（只是说明、或者本应被披露的分支），要么因为它所描述的行为或世界已经变化，沦为陈旧。更短的文档更容易保持相关。没有修剪纪律，默认命运就是沉积（sediment）：陈旧的一层层积淀，因为"添加"感觉安全、"删除"感觉冒险，直到你不得不打穿它们去寻找还活着的东西。
• 逐句猎杀无操作（no-ops）：一条模型本来就默认遵守的指令，用负载只说了一句空话。检验标准（"这条指令相对默认行为是否改变了行为？"）是相对于模型的，而不是相对于读者的：两个关于 no-op 的人如果意见相左，他们其实是在对默认行为有分歧，而应当通过运行这份文档来解决，而不是靠争论。当一个句子失败时，删除整句，而不是从它里面挑几个词来削。检验标准同样用来评级引导词：一个弱到打不过默认行为的词（"要彻底"，而智能体本来就差不多彻底）就是一个 no-op，修正方法是换一个更强的词（relentless），而不是换一种技巧。