write-for-agents

エージェント向けの記述

毎回同じ手順に従うよう、エージェント向けの指示を記述します。

手順

1. ドキュメント、そのドキュメントへのすべてのポインター、そのドキュメントを参照しているすべてのドキュメント、および記載されているファイルとコマンドを読みます。
2. 以下のルールに従って、草案を作成するか、既存の内容を修正します。
3. すべての文をすべてのルールに照らして確認し、その後 unslop を適用します。すべての文が両方を満たし、参照元のすべての手順も引き続き成立したら完了です。

ポインター

ポインターとは、スキルの説明や、ドキュメントへのリンクが記された AGENTS.md の行など、常に読み込まれるコンテキストにある他の資料への参照です。ポインターの各単語は、毎ターンのトークンと注意力を消費します。

• ユーザーやエージェントがタスクに使う単語を先頭に置きます。
• ケースが異なる場合に限り、トリガーをそれぞれ1つ記述します。すでに記載したケースの同義語は削除します。
• 参照先にすでにある情報は削除します。
• エージェントが必須の資料を読み飛ばす場合は、まずそのポインターを言い換えます。言い換えで解決しない場合に限り、資料の内容をインラインで記述します。

配置

• すべてのケースで必要な内容はメインファイルに残します。一部のケースにしか必要でない内容は別ファイルに移し、そこへのポインターを記載します。
• あるトピックの定義、ルール、例外は、1つの見出しの下にまとめます。

完了基準

• 各手順の最後に、確認可能な完了基準を設けます。曖昧な基準（「コードを理解する」など）や形容詞（「徹底的に」など）より、網羅的な基準（「すべての指摘を修正するか、理由を添えて見送る」など）を優先します。
• エージェントが後の手順に進むために手順を急ぐ場合は、その完了基準を明確にします。それでも急ぐ場合は、後の手順をコンテキストに含めず、新しいサブエージェントにその手順を担当させます。

表現

• 避けるべきことではなく、求める動作を記述します。厳守すべきガードレールには禁止表現を使います。
• 1つの概念には、どこでも1つの用語を使います。YAGNI や tracer bullet など、意図する動作を正確に表す定着した用語を、文で言い換えるより優先します。独自に作った用語は定義します。エージェントが確認すべき条件はすべて明記します。

削減

• 各ルールは1か所にまとめ、他の場所からはそこを参照します。
• スクリプト、設定、ディレクトリ構成、--help の出力など、エージェントが1回の参照で確認できる内容は省きます。見つけられない慣習、理由、注意点は記述します。
• モデルの既定の動作と比べて動作を変えない文は削除します。単語を削るだけでなく、文全体を削除します。まず履歴を確認し、確認された失敗への対処として追加されたルールは、それを含まない実行で失敗がなくなるまで残します。
• 文によって動作が変わるか判断できない場合は、テストします。テストであることを知らせずに、該当する文を含む場合と含まない場合で、少なくとも各3回、新しいセッションで同じタスクを実行します。文が適用される規模のタスクを使い、エージェントの動作を比較します。
• 古くなった行や、ドキュメントのタスクに関係しない行は削除します。