hustyladislav/writing-for-agents

エージェントのための文書作成ガイド

エージェントが消費するあらゆる文書（スキル、AGENTS.md / CLAUDE.md、ポインタが指すドキュメント）の執筆リファレンスです。パッケージング方法は異なりますが、書き方は同じです。なぜなら、エージェントは毎回同じ出力を生成するのではなく、同じプロセスを辿るため、そのプロセスを予測可能にするためのレバー（操作手段）は共通だからです。

作成している文書がスキルである場合は、SKILL-MECHANICS.mdを読んで、フロントマター、起動方法の選択、ルータースキルについて確認してください。

コンテキストポインタ

コンテキストポインタとは、エージェントのコンテキスト内に保持される参照であり、コンテキスト外の素材を指名し、それに到達するための条件をエンコードしたものです。スキルの説明文もこれに該当し、AGENTS.md内のドキュメントを指名する行も同じオブジェクトです。エージェントがその素材に到達するかどうか、そしてその信頼性を決定するのは、ポインタの文言であり、対象（ターゲット）そのものではありません。必須のターゲットが弱い文言のポインタの背後にある場合、それはばらつきのバグです。まず文言を明確にし、それでもダメな場合にのみ素材をインライン化してください。

ポインタには2つの役割があります。素材が何であるかを示すことと、その素材に到達すべきブランチ（分岐）を列挙することです（ブランチとは、ドキュメントが処理する個別のケースであり、実行ごとに異なるパスを取ります）。常に読み込まれるポインタのすべての単語は毎ターンコストがかかるため、本文以上に厳しい刈り込みが必要です。

• 先頭単語を最前面に持ってくる：ポインタは、そこでトリガーとなる作業を行う場所です。
• ブランチごとにトリガーは1つ。単一のブランチに別名を付けることは、同じブランチを2回書いていることになります。それらを統合し、真に異なるブランチだけを残してください。
• 本文にすでに含まれている同一性は削除する。

2つの負荷

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

• コンテキスト負荷：常に読み込まれる素材がエージェントのウインドウに与えるコストです。AGENTS.mdの行、スキルの説明、毎ターンコンテキスト内に存在し、発動するかどうかに関わらずトークンとアテンションを消費するものすべてが該当します。
• 認知負荷：人間にかかるコストです。どのドキュメントが存在し、それぞれをいつ参照すべきか。人間こそがインデックス（索引）です。最小化すべきコストではなく、人間の主体性（エージェンシー）の代償です。人間の判断が重要な場面ではこれを費やし、そうでない場面では排除してください。

ポインタを介してのみ到達できる素材は、ポインタ自体の行のコストを支払うことでコンテキスト負荷を回避できます。ポインタがまったくない素材は、完全に認知負荷に依存します。

情報階層

ドキュメントは2つのコンテンツタイプから構成されます。ステップ（エージェントが実行する順序付けられたアクション）とリファレンス（必要に応じて参照される定義、ルール、事実）です。この2つは自由に混在します。すべてステップ（レシピ）、すべてリファレンス（レビューのルール、このスキル）、またはその両方。中心的な判断は、各要素を情報階層のどこに配置するかです。これは、エージェントがその素材を必要とする緊急度によってランク付けされた階層です。

1. ファイル内ステップ：主要な階層。エージェントが行うことを順序立てて記述します。
2. ファイル内リファレンス：必要に応じて参照されます。多くの場合、正当にフラットなピアセット（レビューのすべてのルールが同じ段にあるなど）であり、これは適切な配置であり、問題ではありません。
3. 開示リファレンス：別のファイルに押し出され、コンテキストポインタによって到達され、ポインタが発動したときにのみ読み込まれます。同じフォルダ内の兄弟ファイルから、任意の場所に存在し任意のドキュメントから指すことができる完全に外部のリファレンスまでを含みます。

あまりにも下に押し込みすぎるとトップが肥大化し、押し込みすぎるとエージェントが実際に必要とする素材が隠れてしまいます。この緊張関係こそが、判断のすべてです。

プログレッシブ・ディスクロージャー（段階的開示） とは、この階層を下る移動（メインファイルの外に出してポインタの背後に置くこと）であり、トップ部分を読みやすく保つためのものです。これは主にトークン最適化のためではなく、階層を保護するための方法です。ブランチ（分岐）は、最も明確な開示テストです。すべてのブランチが必要とするものはインライン化し、一部のブランチだけが到達するものはポインタの背後に押し出します。ドキュメントにステップがある場合、開示されるべきファイル内リファレンスがステップを埋もれさせ、ステップへの注意をコイントス（確率的なもの）にしてしまいます。これは単なる可読性の問題ではなく、ばらつきを生み出すレバーです。

コロケーション（共配置） は、ファイル内での補完的な考え方です。階層が「どれだけ下に」要素を置くかを決めるのに対し、コロケーションは「一度配置したらその隣に何を置くか」を決めます。ある概念の定義、ルール、注意点は、散らばらせずに一つの見出しの下にまとめてください。そうすることで、一部を読めば周辺も一緒に読めるようになります。テスト基準：ドキュメントは、エージェントのために書かれたドキュメンテーションのように読めるべきです。グループ化された素材はそのように読め、散在した素材はそうはなりません。（重複とは異なります。重複は一つの意味を複数の場所で繰り返すことですが、散在は一つの意味を多くの場所に断片化することです）。

スプロール（無秩序な拡散） は、ここでの失敗パターンです。すべての行が有効でユニークであっても、ドキュメントが単純に長すぎることです。過剰な部分にアテンションが分散し、余分な行はすべて、関連性を維持しなければならない負担が増えます。治療法は階層です。リファレンスをポインタの背後に開示し、ブランチやシーケンスで分割することで、各パスが必要なものだけを運ぶようにします。

ステップと完了基準

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

• 明確さ：エージェントは完了と未完了を区別できますか？ 曖昧な境界（「理解に達した」など）は早期完了を招きます。つまり、ステップが本当に完了する前に終了し、アテンションが「完了すること」そのものに滑り落ちてしまうのです。まだ見えている先のステップ（完了後ステップ）が引力として働き、完了基準の明確さが抵抗力となります。防御の順序：まず境界を明確にする（ローカルで安価な対策）。それがどうしても曖昧であり、かつ完了を急ぐ現象が観察される場合にのみ、シーケンスを分割して後続のステップを隠します。隠す効果があるのは、真のコンテキスト境界（ハンドオフやサブエージェントへのディスパッチ）を越えた場合のみです。インライン呼び出しでは後続のステップはコンテキスト内に残り、何もクリアされません。
• 要求度：どれだけのことを要求するか。「すべての変更モデルが説明された」は、「変更リストを作成する」よりも徹底した作業を強制します。要求度は本質的な作業（作業自体に内在する、エージェントが行う調査作業。独立したステップとして書かれるのではなく、文言に潜在的に含まれるもの）を駆動します。また、これはステップに限定されません。「すべてのルールが適用された」は、フラットなリファレンスの集合を拘束するのと同じように、シーケンスを拘束します。これは、リファレンスのみのドキュメントでも網羅性の基準を持つ方法です。

最も強力な基準は、チェック可能かつ網羅的であることです。

分割のタイミング

1つのドキュメントを2つに分割すると、2つの負荷のいずれかを消費します。したがって、分割がそのコストに見合う場合にのみ分割してください。

• シーケンスによる分割：後続の完了後ステップが、エージェントに現在のステップを急がせる誘惑となる場合、その一連のステップを分割します。後続のステップを見えなくすることで、現在のタスクにより多くの本質的な作業を促します。逆のパターンに注意：シーケンスをマージすると、各ステップの後続のステップが露出し、早期完了を招く可能性があります。
• 起動方法による分割（スキル固有）：SKILL-MECHANICS.mdを参照。

先行単語

先行単語とは、モデルの事前学習にすでに存在するコンパクトな概念であり、エージェントがドキュメントを実行中にそれを使って考えます（例：lesson（教訓）, fog of war（戦争の霧）, tracer bullets（トレーサー弾））。これを文ではなくトークンとして繰り返すことで、分散した定義が蓄積され、最小トークン数で行動の領域全体をアンカーします。モデルがすでに持つ事前知識（プライア）を活用するためです。独自に作った単語でも、明確に定義すれば機能しますが、作った単語には事前知識がないため、定義のトークンコストを事前学習済みの単語が無料で提供する分だけ支払うことになります。まず既存の単語を探してください。

これは2つの場面でアンカーとして機能します。本文では実行：単語が現れるたびにエージェントは同じ行動に到達し、フラットなリファレンス内では注目すべきクラスのものに注意を集中させます。ポインタでは起動：同じ単語がプロンプト、ドキュメント、コードベースに存在する場合、エージェントはその共有言語を素材にリンクし、より確実に到達します。

先行単語でリファクタリングできる機会を探してください。3つの場所で綴られた三語句、一つのアイデアを指し示すのに一文を費やすポインタ。これらはすべて、一つのトークンに凝縮されるのを待っている箇所です。

• 「高速、決定論的、低オーバーヘッド」→ tight（タイトなループ）
• 「あなたが信じるループ」→ red（バグでループが red になるかどうか、という二値の観測可能な状態に変換）

2つの効果があります。トークンが減り、エージェントが思考を掛けるためのより鋭いフックが得られます。すべてのドキュメントは、先行単語が不要にする言い換えを抱えていると想定してください。それらを見つけに行きましょう。

否定は、このレバーの隣にある失敗モードです。禁止によって誘導しようとすると、禁止された行動がコンテキストに引きずり込まれ、利用しやすくなります。 _「象のことを考えるな」_と言えば、頭の中は象でいっぱいになります。否定は弱い修飾子であり、強く活性化された概念に上書きされます。そのため、禁止は半分、その行為をする命令として読まれます。肯定的に目標の行動を促してください（「一行コメントを書け」）そうすれば、禁止された行動は決して口に出されません。禁止が役割を果たすのは、どうしても肯定的に表現できないハードガードレールとしてのみです。その場合でも、注意が「何をすべきか」に向くように、肯定的な目標とペアにしてください。

プルーニング（刈り込み）

• 各意味は単一の情報源に保持する。つまり、動作の変更が一箇所の編集で済むようにします。重複（同じ意味が複数の場所にあること）は、メンテナンスコストとトークンコストがかかり、階層におけるその意味の重要性を実際よりも高く見せます。（これは、トークンを意図的に繰り返す先行単語の偶発的な逆です。先行単語は意味を決して繰り返しません。）
• 環境も情報源です（package.jsonのスクリプト、設定ファイル、ディレクトリ構成、--help出力）。環境を言い換えたドキュメントはキャッシュです。つまり、ルックアップのコピーであり、ルックアップが高コストな場合にのみ、その負荷に見合う価値があります。エージェントが調べても見つけられないもの（文書化されていない慣習、選択の背後にある理由、どの設定ファイルも告白しない落とし穴）をキャッシュしてください。ファイル一つ、コマンド一つのルックアップは環境に任せ、そこで古くなるリスクを負わせないでください。
• すべての行を関連性についてチェックする。それは未だにドキュメントの目的に貢献していますか？ タスクに関係のない行（単なる説明文、開示されるべきブランチ）や、説明する動作や世界が変化して古くなった行は、関連性を失います。短いドキュメントほど、関連性を維持しやすくなります。プルーニングの規律がなければ、デフォルトの運命は堆積です。つまり、追加が安全に感じられ削除が危険に感じられるために、古い層が堆積し、最終的にはまだ有効なものを見つけるためにそれらを掘り下げなければならなくなります。
• ノーオペレーション（無効果命令） を文単位で探す。モデルがデフォルトですでに従っている命令は、何も言わないために負荷を支払っています。テストは（デフォルトと比較して動作を変えるか？）であり、読者相対ではなくモデル相対です。ノーオペレーションについて意見が分かれる2人は、デフォルトについて意見が分かれているのであり、議論ではなくドキュメントを実行して解決してください。文が不合格になった場合は、単語を削るのではなく、文全体を削除してください。このテストは先行単語も評価します。デフォルトを上回るのに弱すぎる単語（エージェントがすでにそこそこ徹底している場合の「徹底的にやれ」）はノーオペレーションであり、修正は異なるテクニックではなく、より強力な単語（「執拗に」）です。