writing-for-agents

エージェントが読み取るあらゆるドキュメント（スキル、AGENTS.md / CLAUDE.md、ポインターから参照されるドキュメントなど）を書くためのリファレンスです。パッケージ方法は異なっても、書き方は同じです。各ドキュメントを予測可能にする仕組みは共通しており、エージェントが毎回同じ出力を生成するのではなく、同じ プロセス をたどるようにします。

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

コンテキストポインター

コンテキストポインターとは、エージェントのコンテキストに保持される参照で、コンテキスト外の素材を示し、その素材にアクセスする条件を記述したものです。スキルの説明文がその一例であり、AGENTS.md 内でドキュメントを指す行も同じものです。素材にアクセスするタイミングと、そのアクセスの信頼性を決めるのは、参照先ではなくポインターの 文言 です。必須の参照先が曖昧な文言のポインターの先にある場合、それはばらつきの原因になります。まず文言を明確にし、それでもうまくいかない場合に限り、素材を本文に直接記載してください。

ポインターには2つの役割があります。素材の内容を示すことと、その素材へのアクセスを促す 分岐 を列挙することです（分岐とはドキュメントが扱う個別のケースであり、実行ごとに異なる経路をたどります）。常に読み込まれるポインターは、使われるかどうかにかかわらず、毎ターンのトークンと注意力を消費します。そのため、本文以上に厳しく削る必要があります。

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

2つの負荷

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

• コンテキスト負荷 — エージェントのコンテキストウィンドウに常に読み込まれる素材のコストです。AGENTS.md の1行、スキルの説明文、毎ターンコンテキスト内に置かれるあらゆるものが該当し、トリガーされるかどうかにかかわらず、トークンと注意力を消費します。
• 認知負荷 — 人間にとって、どのドキュメントが存在し、それぞれをいつ参照するかを把握するコストです。人間がインデックスの役割を担います。これは最小化すべきコストではなく、人間の主体性を保つための代価です。人間の判断が重要なところにかけ、そうでないところからは取り除いてください。

ポインター経由でのみ参照される素材は、ポインター自体の1行分のコストを支払う代わりに、コンテキスト負荷を回避します。ポインターのない素材は、すべて認知負荷に委ねられます。

情報階層

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

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

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

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

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

ここでの失敗パターンは肥大化です。すべての行に意味があり、重複がなくても、ドキュメントが単に長すぎる状態を指します。余分な内容が増えるほど注意が薄れ、行が増えるたびに関連性を保つべき情報も増えます。解決策は階層を活用することです。リファレンスはポインターの先に移し、分岐や順序ごとに分割して、それぞれの経路に必要な情報だけを持たせます。

ステップと完了基準

すべてのステップは完了基準で終わります。これは、作業が完了したことをエージェントに伝える条件です。これを効果的にする性質は 2 つあります。

• 明確さ — エージェントは完了と未完了を区別できますか？「理解に至る」のような曖昧な基準は、実際に完了する前にステップを終えてしまう早すぎる完了を招きます。注意が「終わらせること」にそれてしまうのです。目に見えて先にあるステップ、つまり完了後のステップが先へ進む力となり、基準の明確さがそれに対する抵抗になります。対処する順序は次のとおりです。まず基準を明確にする（その場で簡単にできます）。基準が本質的に曖昧で、かつ急いで終わらせようとする様子が見られる場合に限り、手順を分割して後続のステップを隠します。ただし、隠すことで効果があるのは、引き継ぎやサブエージェントへのディスパッチなど、実際にコンテキストが切り替わる場合だけです。インライン呼び出しでは後続のステップがコンテキスト内に残るため、何も解消されません。
• 要求水準 — どの程度の作業を求めるかです。「変更されたモデルをすべて確認する」は、「変更一覧を作成する」よりも徹底した作業を求めます。要求水準は掘り下げを促します。これは作業中にエージェントが行う調査であり、独立したステップとして明記されるのではなく、文言に暗黙に含まれます。また、要求水準はステップに限られません。「すべてのルールを適用する」は、フラットなリファレンス全体を対象とし、「すべてのステップを完了する」は手順全体を対象とします。これにより、リファレンスだけのドキュメントでも網羅性の基準を保てます。

最も優れた基準は、確認可能であり、かつ網羅的です。

分割するタイミング

1つの文書を2つに分割すると、2回分の読み込みのうち1回を消費するため、分割する価値がある場合に限って分割します。

• 順序による分割 — 完了後に続く手順が、エージェントに目の前の手順を急がせてしまう一連の手順を分割します。それらを視界から外しておくことで、現在のタスクに必要な下調べをより多く行うようになります。逆の場合には注意が必要です。一連の手順をまとめると、各手順の後続手順がその先にあるものにさらされ、早すぎる完了を促すことになります。
• 呼び出しによる分割 — スキル固有です。詳細は SKILL-MECHANICS.md を参照してください。

先導語

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

先導語は2つの面で定着させます。本文では、_実行_において、語が現れるたびにエージェントは同じ振る舞いを選び、平坦な参照資料の中では、注目すべき対象の種類に注意を向けます。ポインターでは、_呼び出し_において、同じ語がプロンプト、ドキュメント、コードベースに存在すると、エージェントはその共通言語を関連資料に結び付け、より確実に参照するようになります。

先導語を使ったリファクタリングの機会を探してください。3か所で明示された三つ組や、1つの考えを示すために1文を費やすポインターは、いずれも1つのトークンにまとめるべき箇所です。

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

2つの利点があります。トークンが減り、エージェントが思考を結び付けるための手掛かりがより明確になります。どの文書にも、先導語によって不要になる言い換えが含まれていると考え、それらを見つけてください。

否定表現は、この手法に隣接する失敗要因です。禁止によって誘導すると、禁じた振る舞いを文脈に引き込み、抑えるどころか、かえって想起しやすくなります。_ゾウのことを考えないでください_と言えば、そこにあるのはゾウだけです。強く活性化された概念を弱い修飾語である否定が覆せず、禁止がその行動を指示するものとして半ば読まれてしまいます。肯定的な表現で促してください。目標とする振る舞いを明示し（「1行のコメントを書く」など）、禁止する行動には触れないようにします。肯定的に表現できない厳格なガードレールとしてのみ、禁止表現を使う価値があります。その場合も、何をすべきかに注意が向くよう、肯定的な目標と併記してください。

削減

• それぞれの意味は、信頼できる唯一の情報源にまとめます。つまり、振る舞いを変える際に一か所だけ編集すればよい、権威ある場所を一つ設けます。重複、つまり同じ意味を複数の場所に記載することは、保守コストとトークン数を増やし、実際の順位を超えて、その意味を序列上で過度に目立たせます。（意図的にトークンを繰り返す先頭語の偶発的な逆効果は、意味を繰り返すことではありません。）
• 環境も信頼できる情報源です。package.json のスクリプト、設定ファイル、ディレクトリ構成、--help の出力などがそれに当たります。環境の内容をそのまま記載した文書はキャッシュです。検索にコストがかかる場合に限り、キャッシュは読み込みに値します。エージェントが見ただけでは見つけられない情報、つまり明文化されていない慣習、選択の理由、設定からは分からない落とし穴をキャッシュします。一つのファイルやコマンドだけで調べられる情報は、古くなることのない環境に任せます。
• すべての行が関連性を保っているか確認します。その文書の役割に今も関係しているでしょうか？タスクに一度も関係しない場合（単なる説明や、明示すべき分岐など）や、説明対象の振る舞いや状況が変わって内容が古くなった場合、その行は関連性を失います。文書は短いほど、関連性を保ちやすくなります。削減を習慣づけなければ、行き着く先は堆積物です。追加は安全に思え、削除は危険に思えるため、古い層が積み重なり、今も有効な内容を見つけるには掘り進めなければなりません。
• 文ごとに無意味な指示を探します。モデルがデフォルトで従う指示は、何も伝えないのに読み込みコストがかかります。判定基準は、デフォルトと比べて振る舞いが変わるかどうかです。これは読者ではなくモデルに依存します。ある指示が無意味かどうかで二人の意見が分かれるなら、デフォルトについて意見が異なるということです。議論ではなく、文書を実行して確かめます。文が基準を満たさない場合、言葉を削って整えるのではなく、文全体を削除します。この基準は先頭語の評価にも当てはまります。デフォルトに勝てないほど弱い語（エージェントがすでにある程度徹底しているときの be thorough など）は無意味です。別の手法ではなく、より強い語（relentless など）で改善します。

---

• mattpocock/skills を参考にしています。MIT © 2026 Matt Pocock。 このファイルをコピーする場合は、この行を残してください。*