writing-for-agents

エージェントが消費するあらゆるドキュメントを書く際の参考資料です。スキル、AGENTS.md ／ CLAUDE.md、ポインターからたどるドキュメントが対象です。パッケージングの方法は異なりますが、書き方は同じです。エージェントは毎回同じ出力を生成するのではなく、同じ プロセス を実行するため、同じ工夫によってそれぞれの挙動を予測しやすくできます。

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

コンテキストポインター

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

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

• 先頭の語を前に出します。ポインターがアクセスを促す役割を果たすのは、その部分です。
• 分岐ごとにトリガーは1つにします。 1つの分岐を言い換えた類義語は、同じ分岐を二度書いているだけです。まとめて、本当に異なる分岐だけを残します。
• 本文ですでに示されている性質は削ります。

2種類の負荷

追加するドキュメントとポインターはすべて、次の2種類の負荷のいずれかを増やします。

• コンテキスト負荷とは、エージェントのウィンドウに常時読み込まれる資料のコストです。AGENTS.md の1行、スキルの説明文など、毎ターンのコンテキストに含まれるものが対象です。発動するかどうかにかかわらず、トークンと注意を消費します。
• 認知負荷とは、人間がどのドキュメントをいつ参照するかを把握するコストです。索引となるのは人間です。これは最小化すべきコストではなく、人間の主体性を保つために必要な代償です。人間の判断が重要なところには負荷をかけ、そうでないところからは取り除きます。

ポインター経由でのみ参照される資料は、ポインター自体の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行コメントを書く」など）を示せば、禁止したい行動を口にせずに済みます。禁止表現を使うのは、肯定形では表せない厳格なガードレールが必要な場合に限りましょう。その場合も、注意が実行すべきことに向くよう、目標とする行動を併記してください。

削減

• 各意味は唯一の信頼できる情報源に集約します。つまり、動作を変更するときに一か所だけ編集すればよい、権威ある場所です。重複（同じ意味が複数の場所にあること）は、保守コストとトークン数を増やし、その意味を実際の順位以上に重要なものとして階層内で目立たせます。（先頭に置く語を意図的に繰り返すことでトークンが重複しても、意味が重複するわけではありません。）
• 環境も信頼できる情報源です（package.json のスクリプト、設定ファイル、ディレクトリ構成、--help の出力）。これを文書に書き直したものはキャッシュ、つまり検索結果のコピーです。検索にコストがかかる場合に限り、読み込みコストを正当化できます。エージェントが見ただけでは見つけられない情報をキャッシュします。文書化されていない慣例、選択の理由、設定からは分からない落とし穴などです。1ファイル・1コマンドで確認できる情報は、古くならない環境側に任せます。
• 各行の関連性を確認します。その行は今も文書の目的に関係していますか？タスクに一度も関係しない（単なる解説、または開示すべき分岐）場合や、説明対象の動作や状況が変わって古くなった場合、その行の関連性は失われます。短い文書ほど、関連性を保ちやすくなります。削減を習慣化しなければ、行き着く先は堆積物です。追加は安全に感じられ、削除は危険に感じられるため、古い層が積み重なり、今も有効な情報を見つけるには、その下を掘り進めなければならなくなります。
• 文ごとに無効果な記述を探します。モデルがすでにデフォルトで従う指示は、何も伝えずに読み込みコストを発生させます。基準となるのは（デフォルトと比べて動作が変わるかどうか）であり、読者ではなくモデルに依存します。ある文が無効果かどうかで意見が分かれたら、デフォルトについて意見が異なっているのであり、議論ではなく文書を実行して確かめます。文が基準を満たさない場合は、語句を削るのではなく、文全体を削除します。この基準は先頭に置く語にも当てはまります。デフォルトに勝てないほど弱い語（エージェントがすでにそれなりに徹底しているのに be thorough と指示するなど）は無効果です。別の手法を使うのではなく、より強い語（relentless など）に置き換えます。