writing-for-agents

mattpocock/skills の skills/productivity/writing-for-agents/SKILL.md の 4ae2317 に含まれており、MIT ライセンスです（LICENSE）。以下の上流テキストに変更はありません。末尾の workflow-axa による調整は、矛盾する箇所において上流テキストに優先します。

エージェントが読み込むあらゆるドキュメント（スキル、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 の出力）。それを言い換える文書はキャッシュ、つまり参照情報のコピーです。参照にコストがかかる場合にのみ、読み込みコストに見合います。エージェントが調べても見つけられないこと、つまり書かれていない慣習、選択の理由、設定からは分からない落とし穴をキャッシュします。一つのファイルや一つのコマンドで調べられる情報は、古くならない環境に任せます。
• 各行の関連性を確認します。その行は、文書の役割に今も関係していますか？タスクに一度も関係しない（単なる説明や、開示すべき分岐）場合や、説明対象の挙動や状況の変化に伴って古くなった場合、その行は関連性を失います。文書は短いほど、関連性を保ちやすくなります。削減の規律がなければ、行き着く先は堆積です。追加するのは安全に思え、削除するのは危険に思えるため、古い層が積み重なり、今も有効な情報を見つけるには、深く掘り下げなければならなくなります。
• 一文ずつ、何もしない指示を探します。モデルがもともと従う指示は、何も言わないために読み込みコストを払わせます。判定基準（デフォルトの挙動と比べて行動が変わるか）は読者ではなくモデルに依存します。何もしない指示について二人の意見が分かれるなら、デフォルトの挙動について意見が異なっているのであり、議論ではなく文書を実行して確かめます。一文が基準を満たさない場合、言葉を削るのではなく文全体を削除します。この基準は先頭の語にも当てはまります。デフォルトに勝てない弱い語（エージェントがすでにある程度徹底している場合の be thorough など）は何もしない指示です。別の手法に変えるのではなく、より強い語（relentless など）に置き換えます。

---

workflow-axa への適用

• スキル、AGENTS.md／CLAUDE.md、その他のエージェント向け指示に使用します。人間向けのテキスト（計画、レポート、質問）には ../workflow/WRITING.md を使用します。
• このテキストで、別のスキルを使って Skill ツールを呼び出すよう指示している箇所では、このパッケージ内のコピー ../<skill>/SKILL.md を使用します。