writing-agents-md

AGENTS.md の作成

役立つ最短のリポジトリガイドを書きます。 作業を安全に完了するために必要なコンテキスト、制限、権限、根拠をエージェントに伝えます。

ワークフロー

• 対象ディレクトリと、そこに適用されるすべての AGENTS.md ファイルを探します。
  • リポジトリの指示よりも、ユーザーの明示的な指示を優先します。
  • 各ファイルは、そのディレクトリ配下に適用されるものとして扱います。適用範囲が最も狭いファイルを、親ディレクトリのファイルより先に参照します。
  • 共通のガイダンスは、適用範囲が最も狭い共通の親ディレクトリに置きます。
  • 既定ではルートにファイルを1つ置きます。
  • サブプロジェクトで異なるルールが必要な場合に限り、入れ子のファイルを追加します。
• 現在のガイダンス、人間向けのドキュメント、設定、タスクファイル、CI、関連するパッケージのドキュメントを確認します。
  • ツールで実行または読み取り可能なファイルから、コマンドとパスを検証します。
  • 生成されたファイルや、ほかの場所からコピーされたファイルを探します。
  • エージェントの作業方法に影響する、リスクのある移行、破壊的な手順、外部アクション、大量のデータ、所有権のルールを特定します。
• 正確で、プロジェクト固有のルールだけを残します。
  • 古くなった内容、重複した内容、推測、一般論、配置が不適切な内容を削除します。
  • 共通のルールは親ファイルに、ローカルな差異は子ファイルに残します。
• 指示の連鎖に矛盾がないか確認します。
  • 変更の規模とリスクに応じたチェックを実行します。
  • 差分を確認し、ルールの重複や適用範囲の拡大がないか調べます。
  • 検証できなかった事実には、その旨を明記します。
• レビューでは、まず誤ったコマンド、古いパス、適用範囲の矛盾、安全でない権限、不足しているチェックを確認します。
  • 各指摘に重大度、場所、根拠、修正案を示します。
  • 指摘が残っていない場合は、その旨を伝え、重要な未確認の根拠があれば明記します。

自動メンテナンス

AGENTS.md の編集を明示的に依頼された場合を除き、リポジトリの根拠によって、今後のエージェントの作業を変える永続的かつリポジトリ固有のルールであると証明できる場合に限り、ガイダンスを記録します。 タスクの履歴、一時的な状況、推測、一般的なアドバイス、秘密情報、権威あるドキュメントですでに管理されているガイダンスは記録しません。 AGENTS.md が存在しないという理由だけで、新たに作成してはいけません。 許可されたリポジトリの変更中に条件を満たすガイダンスが明らかになった場合は、該当する範囲が最も狭いディレクトリにファイルを更新または作成します。 回答、レビュー、診断、計画の作業中は、ファイルに書き込まず、候補となるルールを報告します。 ルールは該当する既存のセクションに記載します。根拠がある場合に限り、関連する既定のセクションを追加します。 自動で追加または大幅に書き換えるルールには、次のように [UNREVIEWED] を付けます。

- [UNREVIEWED] Run `pnpm test:web` after changing this package.

マークされたルールは有効な指示として扱います。このマーカーはユーザーによるレビュー状況を示すものであり、不確実性や権限の低さを示すものではありません。 ユーザーが明示的に指示した場合に限り、マーカーを削除します。 マークされたガイダンスを言い換えたり統合したりする場合もマーカーを維持し、ユーザーがすでに確認済みの同等のルールには追加しません。 重複するマーク済みのルールは、追加するのではなく統合または修正します。 付随的なメンテナンス中に、マークのないルールを黙って書き換えたり削除したりしてはいけません。ユーザーが AGENTS.md のメンテナンスを依頼していない場合は、矛盾する根拠を報告します。 編集後は、適用される指示の連鎖を読み直し、適用範囲、配置、重複の解消、マーカーの維持、機密情報やタスクログの内容が含まれていないことを確認します。 報告するのは、自動メンテナンスによって変更したルールだけです。

既定のセクション

AGENTS.md ファイルを作成または再構成するときは、これらのセクションをチェックリストとして使います。 マークのない各セクションを確認し、残すセクション間ではこの相対順序を維持します。 エージェントに必要な、検証済みのガイダンスがある場合に限り、セクションを含めます。 確認の結果、該当するガイダンスがない場合は、空のまま残したりルールを作り上げたりせず、そのセクションを省略します。 [Optional] マークの付いたセクションは、リポジトリに関連する場合に限り検討します。 [Optional] マーカーはテンプレート注釈です。最終ファイルに見出しを含める場合は、マーカーを削除します。

## [Optional] Communication
## Documentation
## Code style
## Commands
## Boundaries
## [Optional] Security
## Testing
## [Optional] Project overview
## [Optional] Repository structure
## [Optional] Git and commits

執筆ルール

• ルールは内容が分かる ## セクション見出しの下にまとめ、各ルールは簡潔で実行可能な1文の箇条書き項目として記述します。
• 成果、役立つ背景、厳格な制限、承認が必要な操作、成功基準を明記します。
• 順序が重要な場合に限り、手順を記述します。
• 各ルールは、それが適用される最小の範囲で一度だけ記述します。
• 直接的な表現を使い、正確なパス、コマンド、条件、根拠、停止点を明記します。
• エージェントに必要な範囲、コマンド、コードとテストの規約、セキュリティやデータの制限、コラボレーションやリリースのルールのみを含めます。
• 製品の説明や人向けの手順は、人向けドキュメントに記載します。
• 例や文体のルールは、プロジェクトの要件を示す場合、または実際に確認された誤りを防ぐ場合に限り含めます。
• 質問が必要な不明点を明記します。
• 安全なローカル作業に一律の承認を求めないでください。

操作ポリシーが必要な場合は、簡潔なブロックを1つにまとめます。

For answer, explanation, review, diagnosis, or planning requests, inspect the relevant materials and report the result.
Do not make changes unless the request asks for them.
For change, build, or fix requests, make the requested local changes and run relevant safe checks.
Ask before writing to external systems, taking destructive or costly actions, or greatly expanding the scope.

リポジトリ内の根拠に基づいてポリシーを調整します。 安全なローカル操作とプロジェクト固有の例外を明記します。 ポリシーをほかの箇所で繰り返さないでください。

自動化ルールは、リポジトリで使用しているワークフローに限って追加します。 小規模な自動化ワークフローでは、段階、使用可能なツール、必要な根拠、制限、停止点を定義します。 判断や承認が必要となるタイミングを明記します。