writing-for-agents-wx

エージェント向けに書かれたあらゆるドキュメントのためのリファレンスです。skill、AGENTS.md / CLAUDE.md、ポインターで参照するドキュメントなどが該当します。パッケージ方法は異なっても、書き方は同じです。同じ一連のレバーによって、どのドキュメントも予測可能になります。つまり、エージェントが毎回実行するのは同じプロセスであり、同じ出力を生み出すことではありません。

ドキュメント自体が skill である場合、frontmatter、呼び出し方法の選択、ルーティング系 skill など、skill 固有の詳細については SKILL-MECHANICS.md を参照してください。この skill では、汎用的なライティングのレバーだけを扱います。

コンテキストポインター（context pointer）

コンテキストポインター（context pointer） とは、エージェントのコンテキスト内に残される参照の一文です。コンテキスト外にある資料を指し、その資料を「いつ読むか」という条件を示します。skill の description はポインターの一種ですし、AGENTS.md で特定のドキュメントを指す一行も同じものです。エージェントが資料にアクセスするタイミングを決めるのは、ポインターの参照先ではなく、その文言です。また、その信頼性も関係します。必ず参照しなければならない資料が弱い表現の一文の後ろに隠れているなら、それは variance bug（参照の不安定性に関する欠陥）です。まず文言を磨き、磨いてもまだ不十分な場合に限って、資料をメインコンテキストにインラインで記載します。

ポインターには二つの役割があります。資料の内容を説明することと、読むきっかけとなるべき**分岐（branch。ドキュメントが処理する個々の状況で、実行ごとに異なる経路をたどるもの）**を列挙することです。常駐ポインターの各語は毎回コストになるため、本文以上に厳しく削るべきです。

• 導入語を先頭に置く——ポインターがトリガーとして機能するのはこの部分です。
• 分岐ごとにトリガーは一つ。 同じ分岐をいくつかの同義語で言い換えるのは、一つの分岐を二度書くことです。まとめ、本当に異なる分岐だけを残してください。
• 本文にすでに含まれている識別情報は削る。

二つの負担（the two loads）

追加するドキュメントとポインターはそれぞれ、二種類の予算のどちらかを使います。

• コンテキスト負担（context load）——常駐資料がエージェントのコンテキストウィンドウにかけるコストです。一行の AGENTS.md、skill description、その他、毎回コンテキスト内に置かれ、トリガーされるかどうかにかかわらずトークンと注意力を消費するものが該当します。
• 認知負担（cognitive load）——人にかかるコストです。どのドキュメントがあり、いつどれを参照すべきかを把握する必要があります。インデックスとなるのは人です。これは最小化すべきコストではなく、人間の自律性に伴う代償です。人間の判断が本当に重要なところではコストをかけ、判断が重要でないところでは取り除きましょう。

ポインター経由でしかアクセスできない資料では、コンテキスト負担を抑える代わりに、ポインター自体の一行分のコストがかかります。ポインターのない資料は、認知負担に全面的に依存します。

情報階層（information hierarchy）

ドキュメントは二種類の内容で構成されます。**手順（steps。エージェントが順番に実行する一連の動作）とリファレンス（reference。必要に応じて参照する定義、ルール、事実）です。両者は自由に組み合わせられます。すべて手順（レシピなど）、すべてリファレンス（レビューのルール、つまりこの skill など）、またはその両方でもかまいません。重要なのは、それぞれの内容を情報階層（information hierarchy）**のどの段階に置くかです。これは、エージェントが資料を必要とする緊急度に沿って並んだ階段です。

1. ファイル内の手順（in-file step）——最上位：エージェントがすべきことを順番に記載します。
2. ファイル内のリファレンス（in-file reference）——必要に応じて参照します。合理的な並列項目の集まりであることがよくあります（レビューの各ルールが同じ階層にあるなど）。これは適切な配置であり、悪い兆候ではありません。
3. 外部リファレンス（disclosed reference）——独立したファイルに移し、コンテキストポインター経由で参照します。ポインターがトリガーされた場合にのみ読み込まれます。範囲は同じディレクトリ内の兄弟ファイルから、どこに置いてもよく、どのドキュメントからも参照できる完全な外部リファレンスまでさまざまです。

移動が不十分だと、ドキュメントの冒頭が膨らみます。移動しすぎると、エージェントが本当に必要とする資料を隠してしまいます。この緊張関係が、意思決定のすべてです。

**段階的開示（progressive disclosure）**とは、階段を下る動き、つまりメインファイルから内容を取り除き、ポインターの後ろに隠すことです。これにより、冒頭をすっきり読みやすく保てます。これは主にトークンの最適化ではありません。階層を守るための方法です。分岐は、開示の要否を判断する最も有効なテストです。すべての分岐で必要なものはインラインに置き、一部の分岐でしか参照しないものはポインターの後ろに移します。手順を含むドキュメントでは、本来開示すべきファイル内リファレンスが手順を埋もれさせ、「それらに注意を払う」ことを運任せにします。これは読みやすさだけの問題ではなく、variance を左右するレバーです。

co-locationはファイル内での配置に関する考え方です。階層が内容をどの程度下に置くかを決めるのに対し、co-location は配置した内容の隣に何を置くかを決めます。概念の定義、ルール、注意事項は一つの見出しの下にまとめ、分散させないようにします。そうすれば、いずれかを読んだときに、隣り合う内容も一緒に目に入ります。判断基準は、ドキュメントがエージェント向けに書かれたものとして読めるかどうかです。まとまっている内容はそのように読めますが、散らばった内容はそう読めません。（これは重複とは異なります。重複とは同じ意味を二か所で書き直すことです。分散とは、一つの意味を複数の場所に分けてしまうことです。）

sprawlは、ここで典型的に見られる失敗パターンです。すべての行が有効で固有の内容であっても、ドキュメントが長すぎる状態を指します。余分な長さによって注意力が薄まり、内容が一行増えるたびに、その一行も関連性を保たなければならなくなります。解決策は階段です。リファレンスを開示してポインターの後ろに移し、分岐や順序に沿って分割すれば、各経路に必要な内容だけを含められます。

手順と完了条件（steps and completion criteria）

各手順の最後には、作業が完了したとエージェントが判断する条件を示す**完了条件（completion criterion）**を置きます。次の二つの属性が、これをレバーとして機能させます。

• 明確さ（clarity）——エージェントは、完了と未完了を見分けられるでしょうか。境界が曖昧だと（「十分に理解する」など）、premature completion（早すぎる完了）を誘発します。本当に終わっていないのにこの手順を終了し、注意力が「もう完了した」という感覚に引き寄せられます。先に見える手順、つまり完了後の手順（post-completion steps）は引き戻す力となり、条件の明確さはそれに抗う力になります。順番に対処してください。まず境界を明確にする（局所的で低コストです）。本質的に曖昧で、かつ実際に早すぎる終了が観察された場合に限り、手順を分けて後続の手順を見えなくします。ただし、隠す効果があるのは実際のコンテキスト境界をまたぐ場合だけです（ハンドオフや子エージェントへの割り当てなど。インライン呼び出しでは後続の手順がコンテキスト内に残るため、何も隠されません）。
• 要求度（demand）——どれほどの作業を求めるかです。「変更したモデルを一つずつ詳しく説明する」は、「変更点を一覧にする」だけの場合よりも、徹底した作業を促します。要求度はlegworkを促します。これは、独立した手順として明記されてはいなくても、エージェントが作業の中で深く掘り下げる部分です。また、要求度は手順に限定されません。「すべてのルールを適用した」は、平行するリファレンス一式に紐づきます。「各手順を完了した」が一連の流れに紐づくのと同じです。そのため、すべてリファレンスから成るドキュメントにも、網羅性の基準が伴います。

最も効果的な条件は、確認可能であり、かつ網羅的です。

分割するタイミング（when to split）

ドキュメントを二つに分けると、二種類の負担のどちらかが生じます。そのため、分割する価値がある場合に限って分けてください。

• 順序による分割（by sequence）——一連の手順を分割します。完了後の手順が、エージェントに先行手順を急いで済ませるよう促してしまう場合に有効です。後続の手順を視界から外せば、現在の作業により深く取り組むよう促せます。逆にも注意が必要です。一連の手順をまとめると、各手順の後続ステップがその先の内容として見えるようになり、premature completion を誘発することがあります。
• 呼び出しによる分割（by invocation）——skill 固有です。詳細は SKILL-MECHANICS.md を参照してください。

引導語（leading words）

**引導語（leading word）**とは、モデルの事前学習にすでに組み込まれている簡潔な概念です。エージェントがこのドキュメントを実行する際に、その概念を使って思考します（lesson、fog of war、tracer bullets）。文としてではなくトークンとして繰り返し使うことで、分散した定義が積み重なり、モデルがすでに持つ事前知識を呼び起こして、最小限のトークンで一連の振る舞いを固定します。独自の言葉を作ってもかまいません。定義が明確であればよいのです。ただし、新しく作った言葉は事前知識を呼び起こせません。定義のためにトークンを使うより、事前学習済みの言葉なら無料で使えます。まずはすでにある言葉を探してください。

引導語は二つの場所で機能します。本文では、*実行（execution）*です。この言葉が出るたびに、エージェントは同じ一連の振る舞いを目指します。同じ階層にある参考情報の中では、探すべきものの種類に注意を集中させます。指針では、*呼び出し（invocation）*です。同じ言葉がプロンプト、ドキュメント、コードベースに存在すると、エージェントはその共通言語を資料に結びつけ、より確実に資料を参照できるようになります。

引導語で書き換えられる箇所を探してください。三か所に分けて説明されている三つ組や、一つの考えを指すのに一文を費やしている指針は、どれも一つのトークンにまとめられる可能性があります。

• 「fast, deterministic, low-overhead」→ tight（一つの tight loop）。
• 「信頼できる loop」→ red。曖昧なゲートが、二値の観測可能な状態に変わります（loop はバグがあると red になり、なければなりません）。

二つの利点が得られます。トークンが減り、エージェントが思考を結びつけるための、より明確な手がかりが生まれます。すべてのドキュメントには、引導語で置き換えられる言い換えが含まれていると考えて、見つけてください。

**否定（negation）**は、この手法に隣接する落とし穴です。禁止表現で誘導すると、禁止した振る舞いをコンテキストに持ち込み、使いにくくするどころか、かえって使いやすくしてしまいます。ゾウのことを考えないでと言うと、結局ゾウのことばかり考えてしまいます。否定は弱い修飾語であり、強く活性化された概念に押し流されるため、禁止表現は半ば「それを実行せよ」という指示として読まれます。肯定的に促してください。目標とする振る舞いを述べます（「一行コメントを書く」）。そうすれば、禁止したいことに触れずに済みます。肯定的な表現にできず、強固なガードレールとして必要な場合に限り、禁止表現を使う価値があります。その場合でも、注意を実行すべきことに向けられるよう、肯定的な目標を添えてください。

削減（pruning）

• それぞれの意味に**単一の信頼できる情報源（single source of truth）**を設けてください。振る舞いを変えるときに一か所だけ編集すれば済む、唯一の権威ある場所です。重複（duplication）、つまり同じ意味が複数の場所に現れることは、保守の手間とトークンを増やし、階層内での意味の重みを実際の順位以上に膨らませます（これは引導語とは正反対の意図しない結果です。引導語ではトークンを意図的に繰り返しますが、意味は重複させません）。
• **環境（environment）も情報源の一つです。package.json の scripts、設定ファイル、ディレクトリ構成、--help の出力などが該当します。それらを言い換えたドキュメントはキャッシュ（cache）**です。検索結果のコピーであり、検索にコストがかかる場合に限って、その負荷に見合う価値があります。エージェントのためにキャッシュしておくべきなのは、探しても見つからない情報です。書かれていない規約、ある選択の理由、設定からは分からない落とし穴などです。「一つのファイル、一つのコマンドで調べられる」情報は環境に任せてください。そうすれば古くなりません。
• **関連性（relevance）を一行ずつ確認してください。その行は、ドキュメントの目的に今も関係していますか？タスクに関係がない（純粋な前置き、または本来明示すべき分岐など）という理由で関連性を失うこともあれば、振る舞いや説明対象の状況が変わって古くなることもあります。短いドキュメントほど、関連性を保ちやすくなります。削減の規律がなければ、行き着く先は堆積（sediment）**です。「追加」は安全に思え、「削除」は危険に思えるために古い層が積み重なり、今も有効な情報を見つけるには、それらを掘り返さなければならなくなります。
• すべての文について、**no-op（空操作）**を探してください。モデルがデフォルトですでに守っている指示は、何も伝えず、負荷を無駄にします。確認するのは、「デフォルトと比べて振る舞いを変えるか」です。この判断は読者ではなくモデルに対する相対評価です。ある no-op について二人が意見を違えた場合、争点はデフォルトの振る舞いが何かであり、それは議論ではなく、このドキュメントを実行して確かめるべきです。文が古くなっていない場合は、単語だけを削るのではなく、文全体を削除してください。この基準は引導語の評価にも使えます。デフォルトに勝てない弱い言葉（エージェントがすでに十分 thorough なのに be thorough と書くなど）は no-op です。解決策は別のテクニックではなく、より強い言葉（relentless）を使うことです。