audit-agents

エージェントの監査

AGENTS.md は、このプロジェクトに関わるすべての人が読む文書です。今後100年間にわたる次の1000人の貢献者を思い描いてください。すべてのファイル、ツール、依存関係が入れ替わった後も、その一文が正しく、行動を変えるものである場合にだけ、残す価値があります。

ワークフロー

1. AGENTS.md とルートの readme を読みます。これは文書の監査です。ビルドもテストも実行しません。
2. 以下の基準に基づいて、各行に判定を付けます。
   • 維持：すべての基準を満たす原則です。
   • 言い換え：長く有効な教訓を現在の仕組みに即して書いている場合、または行動に移すには曖昧すぎる場合です。
   • 移動：必要な詳細です。移動先として、readme、マニフェスト、スキル、仕様書のいずれかを明記します。
   • 削除：重複、歴史的な記述、または何も変えない一文です。
3. 以下の例と構成を照らし合わせます。
4. 影響の大きい順に調査結果を報告します。各行を引用し、判定と置き換え文を示し、重複はまとめます。引用できない指摘は報告しません。
5. ユーザーが書き直しを求めた場合に限り編集します。その場合は例をもとに書き始め、ファイルを書き込み、このセッションの経緯を知らない新人の立場で読み返します。

行の基準

• 100年後にも通用するか。 コマンド、フラグ、パス、ファイル名や関数名、依存関係の選択、調整済みの値、計画、状況、バグの経緯は残しません。教訓は残し、仕組みに関する詳細は所定の場所に移します。例外は、詳細を置くためのリンク先を示す参照（readme やスキル）です。
• 1000人に役立つか。 新人が、このセッション、この著者、今月の作業について知らなくても行動に移せます。
• 行動を変えるか。 能力のある貢献者がすでに実践していることを示す行は削除します。
• 平易で具体的か。 原則を抽象論にしてはいけません。「画像を見る」は有効ですが、「主張に合わせて検証方法を選ぶ」はそうではありません。短く、結果が明確な文を選び、一般的な名詞ではなくプロダクトの例を一つ使います。
• 反復の速度。 これは中核となる原則であり、明示しなければなりません。信頼できるフィードバックを得るまでの時間を最短にし、問いに答える最小範囲のチェックを実行し、仕様の実装が完了したら一度だけすべてを実行します。各反復に手順を追加するルール、コミット、マージ、プッシュ、機能の完成より前に全実行を求めるルール、またはその途中にチェックポイントを設けるルールは指摘します。次の作業の信頼性を確保するために必要な場合に限り、全実行を前倒しします。実際の受け入れ要件を、速度のために犠牲にしてはいけません。

構成

assets/example-agents.md はどのプロジェクトでも採用できる AGENTS.md であり、セクションの順序を定めています。構成を評価したり、書き直したりする前に読んでください。

採用する場合はコピーし、すべての <…> を置き換えます。プロジェクトのファイルに <…> が一つでも残っていてはいけません。

• <skill: name> は、このスキルが含まれるパック内のスキルを指します。プロジェクトでのインストール先にあるそのスキルへのリンクに置き換えます。プロジェクトにそのスキルがない場合は、参照を削除し、原則を残します。
• <skill: the project's own …> は、このプロジェクト専用のスキルを指します。リンクするか、その文を削除します。
• それ以外の <…> は、プロジェクトの readme の内容で埋めます。

プロジェクトに不要なセクションは削除し、ほかの場所に収まらない原則に限ってセクションを追加します。