writing-for-agents

エージェントが消費するあらゆるドキュメントを書くためのリファレンスです。スキル、AGENTS.md / CLAUDE.md、ポインターから到達するドキュメントが該当します。パッケージ方法は異なりますが、書き方は同じです。同じ工夫によって、エージェントは毎回同じ プロセス をたどるようになり、同じ出力を生成するのではなく、動作が予測可能になります。

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

コンテキストポインター

コンテキストポインターとは、エージェントのコンテキスト内に保持され、コンテキスト外の資料を指し示すとともに、その資料にアクセスする条件を示す参照です。スキルの説明も、ドキュメント名を示す AGENTS.md の一行も、同じものです。ポインターの_文面_が、参照先ではなく、エージェントがいつ資料にアクセスするか、そしてどれほど確実にアクセスするかを決めます。必須の参照先へのポインターの文面が不適切なのは、実行ごとのばらつきを招くバグです。まず文面を鋭くし、それでもうまくいかない場合にのみ、資料をインラインにしてください。

ポインターには2つの役割があります。資料の内容を示すことと、資料へのアクセスを引き起こすべき分岐を列挙することです（分岐とは、ドキュメントが扱う個別のケースであり、実行ごとに異なる経路をたどる原因になります）。常に読み込まれるポインターの各語は、ターンごとにコストがかかるため、本文以上に厳しく削る価値があります。

• 先頭の語で要点を先に伝える — ポインターは、アクセスを促す役割を果たす場所です。
• 分岐ごとにトリガーは1つ。 1つの分岐を別の語で言い換える同義語は、同じ分岐を二度書いていることになります。まとめて、本当に異なる分岐だけを残してください。
• 本文ですでに示されている内容は削ってください。

2つの負荷

追加するすべてのドキュメントとポインターは、次の2つの予算のいずれかを消費します。

• コンテキスト負荷 — エージェントのコンテキストウィンドウに常に読み込まれる資料のコストです。AGENTS.md の一行、スキルの説明など、各ターンでコンテキストにとどまり、必要かどうかにかかわらずトークンと注意を消費するものが該当します。
• 認知負荷 — 人間が負担するコストです。どのドキュメントが存在し、いつそれぞれにアクセスするかを把握する必要があります。人間がインデックスになります。これは最小化すべきコストではなく、人間の主体性に伴う代償です。人間の判断が重要なところに費やし、重要でないところでは取り除いてください。

ポインターからのみアクセスされる資料は、ポインター自体の一行分のコストを払う代わりに、コンテキスト負荷を免れます。ポインターのない資料は、全面的に認知負荷として人間に委ねられます。

情報階層

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

1. ファイル内のステップ — 最上位の段階です。エージェントが実行することを、順番に記載します。
2. ファイル内のリファレンス — 必要に応じて参照します。正当にフラットな同列セット（レビューのすべてのルールを同じ段階に置くなど）であることがよくあります。これは適切な配置であり、問題ではありません。
3. 開示されたリファレンス — 別のファイルに移し、コンテキストポインターからアクセスできるようにします。ポインターが機能したときだけ読み込まれます。同じフォルダー内の兄弟ファイルから、どこにあってもよく、どのドキュメントからでも参照できる完全に外部のリファレンスまで、さまざまな形があります。

下に移す量が少なすぎると、最上位が膨らみます。移しすぎると、エージェントが実際に必要とする情報が隠れてしまいます。この緊張関係にどう対処するかが、判断のすべてです。

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

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

肥大化は、ここでの失敗パターンです。すべての行に価値があり、重複がなくても、ドキュメントが長くなりすぎる状態を指します。情報が過剰になると注意力は低下し、行を1つ増やすごとに、その内容を関連性のある状態に保つ必要も生じます。解決策は階層です。リファレンスはポインターの先に開示し、分岐や手順に沿って分割して、それぞれの経路で必要な情報だけを扱えるようにします。

ステップと完了条件

各ステップには完了条件があります。これは、作業が終わったことをエージェントに知らせる条件です。次の2つの性質が、これを効果的なてこにします。

• 明確さ — エージェントは、完了と未完了を区別できますか？曖昧な境界（「理解に達した」など）は早すぎる完了を招きます。真に完了する前にステップを終わらせ、注意が 完了していること へと滑っていきます。まだ先に見えているステップ、つまり完了後のステップが引っ張る力となり、基準の明確さが抵抗力となります。次の順序で対処してください。まず境界を明確にする（局所的で低コストです）。基準がどうしても曖昧なまま_であり_、かつ急いでいる様子が見られる場合に限り、シーケンスを分割して後続のステップを隠します。ただし、隠すことが有効なのは、実際のコンテキスト境界を介する場合に限られます（引き継ぎやサブエージェントのディスパッチなどです。インライン呼び出しでは後続のステップがコンテキスト内に残り、何も解決しません）。
• 要求水準 — どれだけの作業が求められるかです。「変更したすべてのモデルを説明する」なら、細部まで丁寧な作業が必要になりますが、「変更点のリストを作成する」だけではそうなりません。要求水準は下調べ、つまり作業の中でエージェントが行う掘り下げを促します。これはステップ自体として書かれるのではなく、文面に潜在しています。また、特定のステップに限りません。「すべてのルールを適用する」は、フラットなリファレンス文書全体に要求水準を設けるのと同様に、「すべてのステップを完了する」はシーケンスに要求水準を設けます。そのため、リファレンスのみの文書にも網羅性の基準を持たせられます。

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

分割するタイミング

文書を2つに分けると、2つある負荷のうち1つを消費するため、分割する価値がある場合に限って分けてください。

• シーケンス単位 — 後続のステップが目の前の作業を急がせる場合は、ステップの連続した流れを分割します。後続のステップを見えないようにすることで、現在のタスクにおける下調べを促します。逆の場合にも注意してください。シーケンスを統合すると、各ステップの後に続くステップが見えるようになり、早すぎる完了を招きます。
• 呼び出し単位 — スキルに固有の方法です。詳しくは SKILL-MECHANICS.md を参照してください。

リーディングワード

リーディングワードとは、ドキュメント（レッスン、fog of war、tracer bullets）を実行している間、エージェントが思考に使うモデルの事前学習にすでに根付いている、簡潔な概念です。フレーズではなくトークンとして繰り返すことで、分散した定義が蓄積され、最小限のトークンで行動全体の領域を支え、モデルがすでに持っている事前知識を呼び起こします。自分で言葉を作る場合も、明確に定義すれば機能しますが、造語では事前知識を呼び起こせません。事前学習済みの単語なら無料で得られるものを、定義のトークンで補うことになります。まずは既存の単語を使いましょう。

リーディングワードは二重に支えます。本文では_実行_を支えます。単語が出てくるたびにエージェントは同じ振る舞いを呼び起こし、reference flatの中では、探すべきものの種類に注意を向けます。ポインターでは_呼び出し_を支えます。同じ単語がプロンプト、ドキュメント、コードベースにあれば、エージェントは共有されたその言葉を素材に結び付け、より確実にたどり着けます。

リーディングワードを使ってリファクタリングできる機会を探しましょう。3か所に書かれた3つの形容、アイデアを示すために一文を費やすポインター。どちらも、ひとつのトークンに集約すべき箇所です。

• 「高速で、決定的で、オーバーヘッドが小さい」→ tight（_tight_なループ）。
• 「信頼できるループ」→ red。曖昧なゲートが、観測可能な二値状態に変わります（バグがあるとループは_red_になり、そうでなければなりません）。

トークンを減らせるうえ、エージェントが思考を掛けるための鋭いフックも得られます。どのドキュメントにも、リーディングワードで置き換えられる言い換えがあると考え、見つけていきましょう。

この手法に隣接する失敗モードは否定です。禁止によって行動を制御しようとすると、禁止した行動がコンテキストに持ち込まれ、抑えられるどころか、かえって_利用されやすく_なります。_象のことを考えないでください_と言えば、そこにあるのは象ばかりです。強く活性化された概念が弱い修飾語である否定を押しのけるため、禁止は、その行動をするよう指示しているように半分受け取られます。禁止したいことに触れずに済むよう、肯定的な形でプロンプトを書き、目標とする行動（「1行のコメントを書く」など）を指定しましょう。禁止を使うのは、肯定的な表現にできない厳格なガードレールの場合だけにしてください。その場合も、注意が何をすべきかに向くよう、肯定的な目標と組み合わせましょう。

削る

• それぞれの意味を唯一の信頼できる情報源に保ちます。つまり、挙動を変えるには一か所だけを編集すればよい、唯一の権威ある場所です。同じ意味が複数の場所にある重複は、保守コストとトークンを増やし、実際のランク以上に、その意味を階層の中で目立たせます。（意図的にトークンを繰り返す先頭語の偶然の逆転は、決して意味そのものではありません。）
• 環境も信頼できる情報源です。package.json のスクリプト、設定ファイル、ディレクトリ構成、--help の出力などがこれにあたります。それを言い直す文書はキャッシュ、つまり検索結果のコピーです。検索コストが高い場合にだけ、キャッシュを維持する価値があります。エージェントが見て探し出せない情報をキャッシュしましょう。書かれていない慣例、選択の理由、どの設定にも記されていない落とし穴などです。一ファイル、一コマンドで済む検索は、古くならないよう環境に任せます。
• 各行の関連性を確認します。その行は、依然として文書の役割に関係していますか？タスクに関係することが一度もない（単なる説明、または明示すべき分岐など）、あるいは挙動や記述対象の世界の変化に伴って古くなると、行は関連性を失います。短い文書ほど、関連性を保ちやすくなります。削る習慣がなければ、行き着く先は堆積物です。追加は安全に思え、削除は危険に思えるため、古い層が積もり、何がまだ有効かを見つけるために掘り進めなければならなくなります。
• 無操作を一文ずつ探します。モデルがすでにデフォルトで従う指示は、何も伝えないために負荷をかけています。判定基準は、デフォルトと比べて挙動が変わるかどうかです。これは読者ではなくモデルに依存します。無操作かどうかで意見が分かれる二人は、デフォルトについて意見が異なっているのであり、議論ではなく文書を実行して確かめます。文が基準を満たさなければ、言葉を削って整えるのではなく、文全体を削除します。この基準は先頭語の強さも見極めます。デフォルトを上回るほど強くない言葉（エージェントがすでにある程度細部に注意を払う場合の「細部に注意する」など）は無操作です。その場合、別の手法ではなく、より強い言葉（「徹底する」など）に置き換えます。