writing-for-agents

エージェント向けの文書作成

エージェントが読み込むあらゆる文書（スキル、AGENTS.md / CLAUDE.md、ポインターからたどるドキュメントなど）を書くための参考資料です。パッケージの形は異なりますが、文書の書き方は変わりません。エージェントは毎回同じ出力を生成するのではなく、同じ プロセス を実行するため、同じ工夫によってどの文書も予測しやすくなります。

作成する文書がスキルの場合は、フロントマター、呼び出し方法の選択、ルータースキルについて SKILL-MECHANICS.md をお読みください。

コンテキストポインター

コンテキストポインターとは、エージェントのコンテキストに保持される参照で、コンテキスト外の資料を指し、その資料にアクセスする条件を示すものです。スキルの説明もその一例です。AGENTS.md にドキュメント名を記した行も、同じオブジェクトです。資料にアクセスするタイミングと、その確実性を左右するのは、参照先ではなくポインターの 文言 です。重要な資料へのポインターの文言が曖昧なのは、ばらつきを招く不具合です。まず文言を明確にし、それでも解決しない場合に限り、資料を本文に含めます。

ポインターには2つの役割があります。資料の内容を示すことと、その資料にアクセスするきっかけとなる分岐を列挙することです（分岐とは、ドキュメントが扱う個別のケースのことで、実行ごとに異なる経路をたどります）。常に読み込まれるポインターの文言は、毎ターンのコストになるため、本文以上に徹底して削る必要があります。

• 先頭に最も重要な語を置く：ポインターがトリガーとして機能するのは、その部分です。
• 分岐ごとにトリガーを1つにする。 1つの分岐を言い換えた同義語は、同じ分岐を重複して書いているだけです。まとめて、本当に異なる分岐だけを残します。
• 本文ですでに示されている内容は削る。

2種類の負荷

追加する文書やポインターは、それぞれ次の2種類の予算のいずれかを消費します。

• コンテキスト負荷とは、エージェントのコンテキストウィンドウに常時読み込まれる資料（AGENTS.md の行、スキルの説明など）のコストです。毎ターンのコンテキストに含まれ、トークンと注意力を消費するため、必要かどうかにかかわらず負荷がかかります。
• 認知負荷とは、人間にかかるコストです。どのドキュメントが存在し、それぞれいつ参照するかを把握する負担を指します。索引の役割を担うのは人間です。これは最小化すべきコストではありません。人間の主体性を保つための代価であり、人間の判断が重要な場面では負担し、そうでない場面では取り除きます。

ポインターを通じてのみ参照される資料は、ポインター自体の1行分のコストを負う代わりに、コンテキスト負荷を免れます。ポインターがまったくない資料は、すべて認知負荷に委ねられます。

情報階層

ドキュメントは、2 種類のコンテンツで構成されます。エージェントが順に実行するアクションであるステップと、必要に応じて参照する定義、ルール、事実であるリファレンスです。この 2 つは自由に組み合わせられます。すべてステップ（レシピ）、すべてリファレンス（レビューのルール、このスキル）、またはその両方にできます。中心となる判断は、それぞれの要素を情報階層のどこに配置するかです。これは、エージェントがその情報をどれほどすぐに必要とするかに応じて順位づけされた階層です。

1. ファイル内ステップは最上位です。エージェントが順に実行する作業を記します。
2. ファイル内リファレンスは必要に応じて参照します。多くの場合、適切にフラットな同列項目の集合です（レビューのすべてのルールが同じ階層にあるなど）。これは問題のある状態ではなく、適切な構成です。
3. 開示リファレンスは別ファイルに移し、コンテキストポインターから参照して、そのポインターが呼び出されたときだけ読み込みます。同じフォルダー内の兄弟ファイルから、どこにあってもよく、どのドキュメントからでも参照できる完全に外部のリファレンスまで、さまざまな形があります。

下位に移す情報が少なすぎると最上位が肥大化し、多すぎるとエージェントが実際に必要とする情報まで隠れてしまいます。このバランスを取ることが、判断のすべてです。

段階的開示とは、最上位を読みやすく保つために、情報を階層の下位へ移す（メインファイルから出し、ポインターの先に置く）ことです。主な目的はトークンの最適化ではなく、階層を守ることです。分岐は、開示する情報を判断する最も明快な基準です。すべての分岐で必要な情報はインラインに置き、一部の分岐でしか必要にならない情報はポインターの先に置きます。ドキュメントにステップがある場合、開示すべきファイル内リファレンスを埋め込むと、それらのステップが埋もれ、注意を向けるかどうかが運任せになります。これは読みやすさだけでなく、ばらつきにも影響する要因です。

同一箇所への配置は、ファイル内での補完的な考え方です。階層が要素を「どれだけ下位に置くか」を決めるのに対し、同一箇所への配置は、下位に置いた後で「何を隣り合わせるか」を決めます。ある概念の定義、ルール、注意事項は、あちこちに散らさず、1 つの見出しの下にまとめます。そうすれば、ある箇所を読むと、その関連情報も一緒に目に入ります。判断基準は、そのドキュメントがエージェント向けに書かれたドキュメントとして読めるかどうかです。情報がまとまっていればそう読めますが、散らばっているとそう読めません。（これは重複とは異なります。重複は 1 つの意味を 2 か所に記載することですが、分散は 1 つの意味を複数の箇所に分断することです。）

肥大化は、ここで起こりうる失敗です。すべての行が有効で固有の情報であっても、単にドキュメントが長すぎる状態を指します。情報が多すぎると注意が薄れ、行が増えるたびに、関連性を保つべき対象も増えます。解決策は階層を活用することです。リファレンスはポインターの先に移して開示し、分岐や手順ごとに分割して、それぞれの経路に必要な情報だけを持たせます。

ステップと完了基準

各ステップは完了基準で終わります。これは、作業が完了したと判断する条件です。次の 2 つの性質が、その基準を調整の要点にします。

• 明確さ：完了と未完了をエージェントが区別できますか？「理解に至る」のような曖昧な基準は、実際に終わる前にステップを終えてしまう早すぎる完了を招きます。注意が「作業を終えること」へと逸れてしまうのです。まだ残っている目に見えるステップ（完了後のステップ）が先へ進ませる力になり、基準の明確さがそれに対抗します。まず基準を明確にすることで対処します（その場で対応でき、コストも低いためです）。基準が本質的に曖昧で、かつ先を急ぐ様子が見られる場合に限り、手順を分割して後続のステップを隠します。隠す方法が機能するのは、実際のコンテキスト境界（引き継ぎやサブエージェントへの処理依頼）がある場合だけです。インラインの呼び出しでは後続のステップもコンテキスト内に残るため、何も解決しません。
• 要求の強さ：どれほどの作業を求めるかです。「変更したモデルをすべて説明する」は、「変更一覧を作成する」よりも徹底した作業を求めます。要求の強さは調査作業（作業の中でエージェントが行う掘り下げで、独立したステップとして書かれるのではなく、文言に暗に含まれるもの）を促します。また、要求の強さはステップだけに関係するものではありません。「すべてのルールを適用する」は、フラットなリファレンスの集合にも、「すべてのステップを完了する」が一連の手順に求めるのと同じように網羅性を求めます。そのため、リファレンスのみのドキュメントでも、網羅性の基準を保てます。

最も強力な完了基準は、確認可能であり、かつ網羅的です。

分割するタイミング

1つのドキュメントを2つに分割すると、2つのロード枠のうち1つを使うことになるため、分割する価値がある場合に限って分割します。

• 順序による分割：後続のステップが、その直前のステップをエージェントに急がせてしまうような一連のステップを分割します。後続を視界に入れないことで、現在のタスクに対してより多くの下準備を進められます。逆方向の影響にも注意してください。一連のステップを統合すると、各ステップの後続がその後に続く内容にさらされ、早まった完了を招きます。
• 呼び出しによる分割：スキル固有の方法については、SKILL-MECHANICS.md を参照してください。

先頭語

先頭語とは、モデルの事前学習にすでに組み込まれていて、ドキュメントを実行する際にエージェントが思考に用いる、簡潔な概念です（教訓、霧の中の戦場、トレーサー弾）。文ではなくトークンとして繰り返し使うことで、分散した定義が蓄積され、モデルがすでに持つ事前知識を呼び起こしながら、最小限のトークンで行動の領域全体を支えるようになります。明確に定義すれば独自の語を作ることもできますが、造語では事前知識を呼び起こせません。事前学習済みの語なら無料で得られる定義を、造語ではトークンを使って補うことになります。まず既存の語を探しましょう。

先頭語は2つの場所で支えになります。本文では、_実行_を支えます。同じ語が出てくるたびに、エージェントは同じ行動を選び、フラットなリファレンス内では、探すべき対象の種類に注意を集中させます。ポインターでは、_呼び出し_を支えます。同じ語がプロンプト、ドキュメント、コードベースにあれば、エージェントはその共通言語を資料に結び付け、より確実に参照するようになります。

先頭語を使ってリファクタリングできる箇所を探しましょう。3か所で説明されている三項の概念や、1つの考えを示すために1文を費やしているポインター。いずれも、1つのトークンにまとめる余地があります。

• 「速く、決定的で、オーバーヘッドが小さい」→ タイト（_タイト_なループ）。
• 「信頼できるループ」→ レッド。曖昧な判定を、観測可能な二値の状態に変えます（バグがあればループは_レッド_になり、なければなりません）。

2つの利点が得られます。トークン数が減り、エージェントが思考を結び付けるための、より明確な手掛かりになります。すべてのドキュメントには、先頭語によって不要になる言い換えが含まれていると考えましょう。見つけに行きましょう。

否定表現は、この手法に隣り合う落とし穴です。禁止によって誘導すると、禁じた行動がコンテキストに持ち込まれ、利用されやすくなるどころか、かえって利用されやすくなります。_ゾウを考えないでください_と言えば、頭にあるのはゾウだけです。強く活性化された概念に弱い修飾語である否定が負けてしまい、禁止がその行動を促す指示のように読まれてしまうからです。肯定形でプロンプトを書きましょう。目標とする行動（「1行コメントを書く」など）を示せば、禁止したい行動を口にせずに済みます。禁止表現を使うのは、肯定形では表せない厳格なガードレールが必要な場合に限りましょう。その場合も、注意が実行すべきことに向くよう、目標とする行動を併記してください。

削減

• それぞれの意味は、単一の信頼できる情報源に置きます。つまり、挙動を変えるときに一か所だけを編集すればよい、唯一の正式な記述場所です。重複（同じ意味が複数の場所にあること）は、保守コストとトークン数を増やし、その意味の重要度を実際の順位以上に引き上げます。（先頭に置く言葉を意図的に繰り返してトークンを重ねるのは、その逆の意図的な例であり、意味を繰り返すものではありません。）
• 環境も信頼できる情報源です（fxmanifest.lua、package.json のスクリプト、設定ファイル、server.cfg の convar、ディレクトリ構成、--help の出力など）。それを言い換えて記した文書はキャッシュです。検索にコストがかかる場合にのみ、その負荷に見合う価値があります。エージェントが見ただけでは見つけられない情報をキャッシュします。文書化されていない慣習、選択の理由、設定ファイルに記載されていない落とし穴などです。一つのファイルや一つのコマンドで調べられる情報は、古くなる心配のない環境に任せます。
• 各行の関連性を確認します。その行は、文書の役割に今も関係していますか？タスクにまったく関係しない場合（単なる説明、あるいは明記すべき分岐など）や、説明対象の挙動や状況が変わって古くなった場合、その行は関連性を失います。文書が短ければ、関連性を維持しやすくなります。削減の規律がなければ、行き着く先は堆積物です。追加は安全に感じられ、削除は危険に感じられるため、古い層が積み重なり、今も有効な情報を見つけるには、深く掘り進めなければならなくなります。
• 一文ずつ無意味な指示を探します。モデルが既定で従う指示は、何も言わないために負荷を使っています。判定基準（既定の挙動と比べて挙動が変わるかどうか）は読者ではなくモデルに依存します。無意味な指示かどうかで意見が分かれるのは、既定の挙動について意見が分かれているからです。議論ではなく、その文書を実行して判断します。文が基準を満たさない場合は、単語を削って短くするのではなく、文全体を削除します。この基準は、先頭に置く言葉にも当てはまります。既定の挙動に勝てない弱い言葉（エージェントがもともとある程度は徹底するのに「徹底すること」と指示するなど）は無意味です。異なる手法ではなく、より強い言葉（「容赦なく徹底する」など）で修正します。