agents-md

AGENTS.md

概要

コーディングエージェントが常時読み込むプロジェクトコンテキストとして、簡潔で実行可能かつハーネスに依存しない AGENTS.md を作成または強化します。人間向けのオンボーディングではなく、エージェントの成功を最優先します（人間向けの説明は README.md に記載します）。

このスキルは、オープンな AGENTS.md 形式（プレーンな Markdown で、必須フィールドはありません）を対象とします。.github/agents/ に配置する GitHub Copilot のカスタムエージェントのペルソナ（フロントマターとペルソナファイル）と混同しないでください。コマンド、例、境界に関する指針は引き続き適用されますが、ペルソナに関する指針は適用されません。

モード

次から1つ選びます。

• 作成 — 使用可能な AGENTS.md がない場合（またはユーザーがひな形の作成を依頼した場合）。
• レビュー — 既存ファイルを品質基準に照らして監査し、依頼がない限り書き換えずに不足点を報告します。
• 改善 — 品質基準を満たすようにファイルを書き換えるか編集します。
• ネスト — モノレポ内のパッケージ／サブディレクトリにある AGENTS.md ファイルを追加または修正します。

判断がつかない場合は、作成、レビュー、改善、ネストのどれかを一度だけ尋ねます。

基本ルール

• ルートの AGENTS.md は1つにすることを優先します。サブツリーでコマンド、境界、規約が異なる場合にのみネストします。
• 必須： すべてのルート AGENTS.md に、references/communication.md の Communication（ASD-STE100）ブロックを含めます。そのまま貼り付けてください。ネストされたファイルでは、文体ルールを上書きしない限り不要です。
• 原則として必須： すべてのルート AGENTS.md に、references/testing.md の Testing（E2E と統合テストを優先）ブロックを含めます。リポジトリにすでに存在する E2E と統合テストのセットアップのみを記載し、新たに追加してはいけません。ユーザーが別のテスト方針に従うと明示した場合に限り、このブロックを省略します。
• AGENTS.md の編集の一環としてテストを削除してはいけません。シグナルの低い単体テストを整理する場合は、別途提案し、承認を待ってください。
• それ以外の各行にも、記載する価値が必要です。判断基準は「これを削除すると、エージェントがほかの場合には起こさないミスをするか」です。そうでなければ削除します。
• ルートファイルは 150行以下 を目標とします。小規模なリポジトリなら 30～50行 で十分です。それより長くなる場合は分割するか、索引を設けます。
• 実際に実行できる正確なコマンド（プロジェクトで使われているフラグやフィルターを含む）を冒頭近くに記載します。エージェントはこれらを再実行します。
• アーキテクチャに関する長い説明、スタイルガイド全文、README の複製を貼り付けるのではなく、参照先と概要表を優先します。
• エージェントが推測できない情報を記載します。パッケージマネージャー、特殊なディレクトリ構成、表に出ない不変条件、禁止パス、セキュリティ上の注意点、「先に確認が必要」な変更などです。
• 曖昧なスタイル説明の代わりに、具体例（短いスニペットや標準的なパス）を使います。
• 必要に応じて、境界を3段階で示します。常に行う／事前に確認する／決して行わない。
• ハーネスに依存しないようにします。特定の製品のツール名、UI、隠れた動作に依存してはいけません。オプション機能（プランモード、承認、サブエージェント）は、一般的な表現と手動での代替手段があれば記載できます。
• AGENTS.md に秘密情報、トークン、秘密鍵、実際の認証情報を記載してはいけません。
• ファイルは継続的に更新するドキュメントとして扱います。ユーザーからエージェントのミスが繰り返されていると報告されたら、修正内容をここ（またはリンク先のドキュメント）に反映します。
• package.json／Makefile／justfile／CI から、プロジェクトで実際に使われているパッケージマネージャーとスクリプトを優先します。コマンドを作り上げてはいけません。
• このスキルの例で bun／bunx を優先するのは、対象リポジトリがすでに Bun を使っている場合に限ります。それ以外では、そのリポジトリに合わせます。

品質基準（必ず満たすこと）

優れた AGENTS.md には、該当する場合、以下の項目が含まれています（該当しないセクションは省略し、内容を水増ししないでください）。ルートファイルではコミュニケーションが必須です。

1. スタック — 言語、フレームワーク、主要ライブラリ。一般的でない場合はバージョンも記載します。
2. コマンド — インストール、開発、テスト、lint／型チェック、ビルド。モノレポではスコープを限定したコマンドも記載します。
3. コミュニケーション — references/communication.md の ASD-STE100 ブロック（ルートファイルでは必須）。
4. レイアウト — ソース、テスト、設定、生成物の配置場所（標準的でない場合のみ）。
5. 規約 — エージェントが間違えやすい、プロジェクト固有のスタイルやアーキテクチャのルール。それ以外は lint／フォーマットの設定にリンクします。
6. テスト — references/testing.md のブロック。実在する E2E および統合テストの環境と、実際に使えるコマンドのみを記載します。
7. Git／PR — デフォルトと異なるコミット／PR の規約（タイトル形式、必須チェック）。
8. 境界 — 常に実施してよいこと／事前確認が必要なこと／禁止事項（シークレット、ベンダーディレクトリ、本番設定、スキーマ、依存関係）。
9. インデックス — アーキテクチャ、ADR、セキュリティモデルなど、詳細ドキュメントへのリンクまたは表。内容を直接記載するのではなく、参照先を示します。

チェックリスト全文：references/quality-bar.md。

ワークフロー

1. リポジトリを調査する

作成前に、以下を確認します。

• 既存の AGENTS.md、README.md、CONTRIBUTING.md、CI ワークフロー、パッケージスクリプトを読みます。
• パッケージマネージャー、テストランナー、lint／フォーマットツール、モノレポの構成、安全でない領域を把握します。
• 既存のエージェント向け指示ファイル（CLAUDE.md、.cursor/rules、GEMINI.md など）に目を通し、独自の内容を移行します。内容をそのまま重複させないでください。

2. 下書きまたは編集を行う

• 出発点として references/template.md を使い、不要なセクションは削除します。
• references/communication.md の Communication ブロックを、必ずルートファイルに貼り付けます。
• Communication の後に、references/testing.md の Testing ブロックを貼り付けます。実際のスクリプトに基づいて環境設定の行を記入し、リポジトリにない環境の行は削除します。
• 使用頻度の高いコマンドを上部に記載します。次に Communication、続いて Testing を記載します。
• プロジェクト固有の制約だけを記載します。エージェントがすでに把握している一般的なアドバイスは削除します。Communication と Testing は削除しないでください。
• モノレポでは、references/nesting.md に従います。

3. 検証する

以下に照らして確認します。

• 上記の品質基準と references/quality-bar.md。
• Communication ブロックが変更されずに含まれていること：references/communication.md。
• Testing ブロックが含まれ、ルールが緩和されておらず、プレースホルダーが埋められ、実在する環境のみが記載されていること：references/testing.md。
• references/anti-patterns.md のアンチパターン。
• references/examples.md の良い例と悪い例。

リンク先のパスがすべて存在することを確認します。コマンドがスクリプト／CI と一致することを確認します。シークレットが含まれていないことを確認します。

4. 納品する

• 作成／改善／ネスト：合意したパス（通常はリポジトリのルートにある AGENTS.md）にファイルを作成します。
• レビュー：合格項目、不合格項目、修正案を簡潔に報告します。依頼がない限り、書き換えは行いません。
• 最後に、行数、含まれるセクション、意図的に省略した項目を簡潔に記載します。

競合と優先順位に関する注意事項

必要に応じて、メンテナー向けに以下を記載します（すべてのファイルで説明する必要はありません）。

• エージェントが競合を解決する際にこの方法を採用する場合、編集対象のファイルに最も近いネストされた AGENTS.md が、親のガイダンスより優先されます。ユーザーとのチャットでの指示は常にファイルより優先されます。
• エージェントによっては、ルートから現在の作業ディレクトリまでのファイルを連結します（後にある、より具体的な内容が優先されます）。ネストされたファイルは追加情報として記述し、上書きする内容を明示します。
• 一部のツールには、ソフトなサイズ上限（たとえば Codex のプロジェクトドキュメントのバイト数上限）があります。巨大なルートファイルを作るより、分割またはネストを優先します。
• 必要に応じて Claude Code との互換性を保つには、@AGENTS.md を読み込む簡潔な CLAUDE.md に Claude 固有の追加事項を記載すると、ガイド全体の重複を避けられます。

対象外

• ユーザーがファイルパターンごとの細かなルールを求めている場合に、パス単位のIDEルールシステム（たとえば、globを使った .cursor/rules）を置き換えること — AGENTS.md はシンプルで移植性の高いデフォルトです。
• ユーザーから明示的に依頼されない限り、.github/agents/ に Copilot のカスタムエージェント用ペルソナパックを作成すること。
• 人間向けの README 全体を AGENTS.md にコピーすること。