agents-md

リポジトリの根拠に基づいて AGENTS.md を管理する

概要

コーディングエージェントがワークフローを一から調べ直さずにリポジトリを正しく変更できるよう、エージェント向けの指示を作成または改善します。リポジトリ固有のコマンド、パス、ルールはすべて、現在のチェックアウトにある根拠に基づいてください。

全面的な書き換えより、変更範囲を絞った差分を優先してください。すべてのリポジトリに共通する行数の上限、必須のセクション一覧、シンボリックリンクの構成、コミットの帰属方針はありません。リポジトリ固有のニーズとメンテナーの意図に従ってください。

使用する場面

• ユーザーが AGENTS.md の作成、更新、短縮、または監査を求めている場合。
• モノレポにルートの指示と、より限定的なパッケージ単位の指示が必要な場合。
• 既存のエージェント向け指示に、古いコマンド、重複した方針、または根拠のない主張が含まれている場合。
• ユーザーが AGENTS.md と CLAUDE.md、.github/copilot-instructions.md、その他のリポジトリ指示ファイルの整合を求めている場合。

タスクが @agents-generator に含まれる生成モード、アセット、またはバックアップワークフローを明確に必要としている場合は、代わりに @agents-generator を使用してください。メンテナーが読みやすく、根拠を重視した編集が主な目的である場合は、このスキルを使用してください。

仕組み

1. 既存の意図を保つ

書き始める前に、対象パスに適用される指示ファイルをすべて読みます。既存の AGENTS.md と、CLAUDE.md、GEMINI.md、.github/copilot-instructions.md、.github/instructions/*.instructions.md など、関連するツール固有のファイルを含みます。

• 可能であれば、既存の AGENTS.md をその場で改善します。
• 正確なメンテナー作成のルールとリポジトリ固有の方針を維持します。
• ユーザーから依頼があり、リポジトリ内の根拠から同一内容にする意図が確認できる場合を除き、別ツールの指示ファイルをシンボリックリンクに置き換えないでください。
• 指示が矛盾している場合、どちらかを黙って選ばないでください。優先度の高い適用可能なルールに従うか、意図する方針をリポジトリから確認できない場合は質問してください。

2. 範囲を絞って根拠を調べる

実際の作業方法を把握するのに必要な範囲で、リポジトリを調べます。

1. README*、CONTRIBUTING*、関連ドキュメントなど、プロジェクトの概要とコントリビューションガイドを読みます。
2. マニフェスト、ロックファイル、ワークスペースファイル、タスクランナー、ビルド設定を読み、サポートされているツールと正確なコマンドを特定します。
3. CI ワークフローを読み、必須のチェックを把握します。CI やデプロイのすべてのジョブがローカルで安全または適切に実行できると決めつけないでください。
4. 代表的なソースファイルとテストファイルを調べ、命名、配置、テストの規約を確認します。
5. 生成ファイル、マイグレーション、ベンダーコード、大きなフィクスチャ、シークレットの境界、本番環境専用の操作を特定します。

利用可能であれば、探索には rg --files と rg を優先してください。根拠のない主張が最終ファイルに入らないよう、明白でない各コマンドやルールの出典を記録します。

3. 指示の適用範囲を決める

リポジトリ全体に関するガイダンスには、ルートの AGENTS.md を使用します。サブツリーでコマンド、アーキテクチャ、規約、安全上の境界が大きく異なる場合に限り、ネストした AGENTS.md を追加または改訂します。

共通ルールはルートに置き、ネストしたファイルには相違点のみを記載します。公開されている AGENTS.md 規約に対応するツールでは、対象ホストの優先順位に従い、ルートまたは祖先のガイダンスと、より限定的なサブツリーの指示を適用します。最も近いファイルが、無関係な祖先のルールを暗黙に無効にすることはありません。すべてのパッケージにルートファイル全体をコピーしないでください。

4. シグナルの強いガイダンスを書く

固定テンプレートを無理に当てはめるのではなく、リポジトリに適した見出しを選びます。 以下の項目は、根拠がある場合にのみ含めてください:

• リポジトリマップ: エージェントが知っておくべき少数のディレクトリと境界。
• セットアップとコマンド: 正確なインストール、開発、ビルド、lint、型チェック、 テストのコマンド。作業ディレクトリが自明でない場合はそれも示します。
• 焦点を絞った検証: 小さな変更に対する対象を絞ったチェックと、引き継ぎ前に 必要なより広範なチェック。
• 変更ルール: 生成ファイルの所有権、マイグレーション、スキーマ、API、 依存関係、パッケージ間の連携。
• 安全上の境界: シークレット、本番データ、破壊的なコマンド、 デプロイ、および明示的な承認を必要とする操作。
• コントリビューションルール: 実装や引き継ぎに影響する、リポジトリ固有の 命名、フォーマット、コミット、プルリクエストの要件。

直接的で検証可能な記述を書いてください。次のような表現を優先します:

- From the repository root, run `npm test -- path/to/file.test.ts` for a focused test.

次のような表現よりも:

- Make sure tests pass and follow best practices.

メンテナンスされているドキュメントをコピーするのではなく、リンクしてください。必須の チェックと、任意・低速・特権的・デプロイ専用のチェックを区別してください。

5. 引き継ぎ前に検証する

1. 変更した各 AGENTS.md を最初から最後まで読み直します。
2. 矛盾、重複するルール、プレースホルダー、古くなった記述を削除します。
3. 言及したすべてのファイルとディレクトリが存在することを確認します。
4. コマンドをマニフェストや CI と照合し、有用であれば安全で妥当な範囲の チェックを実行します。
5. ネストされたファイルを変更した場合は、それぞれがサブツリー固有のルールのみを 含み、ルートと意図せず競合していないことを確認します。
6. メンテナーの視点で差分をレビューします。追加したすべての行は、エージェントの 判断を変えるか、現実的なミスを防ぐものであるべきです。

変更したファイル、使用した根拠、実際に実行したチェック、未解決の不確実性を 報告してください。設定から読んだだけのコマンドを、テスト済みと決して言わないでください。

例

焦点を絞ったルートファイルを作成する

見つかった根拠:

• package-lock.json が npm を選択している。
• package.json が lint、typecheck、test スクリプトを定義している。
• CI がこれら 3 つのチェックをリポジトリのルートから実行している。
• src/generated/ は npm run generate によって生成される。

有用な結果には次のようなものが含まれるかもしれません:

# Agent instructions

## Commands
- Run commands from the repository root.
- Install with `npm ci`.
- For handoff, run `npm run lint`, `npm run typecheck`, and `npm test`.

## Generated code
- Do not edit `src/generated/` directly; update its source and run `npm run generate`.

根拠が確立していないパッケージマネージャー、コマンド、生成ファイルのルールを 追加しないでください。

ポリシーを消さずに修正する

既存のファイルに正確なリリース制限があるものの、テストコマンドが古い場合は、 古いコマンドとそれに直接影響される説明のみを変更します。 より短い置き換えのほうがすっきり見える場合でも、リリース制限は保持してください。

ベストプラクティス

• 指示はざっと目を通せる程度に簡潔にしつつ、長さはリポジトリの複雑さで 決めましょう。
• 一般的なエンジニアリングの助言よりも、リポジトリ固有の決定を優先しましょう。
• プロジェクトが対応している場合は、対象を絞ったコマンドを含めましょう。スイート 単位の実行しか対応していないツールに対して、ファイル単位の呼び出しをでっち上げないでください。
• コマンドをどこで実行するか、ファイルを変更するかどうかを明記しましょう。
• すべてのルールを言い直すのではなく、フォーマッターとリンターの設定を参照しましょう。
• セマンティクスが異なる場合は、ツール固有のファイルを追加的にしましょう。すべての エージェントがフォーマットや優先順位を同じように解釈すると仮定しないでください。

セキュリティと安全に関する注意

• これはリポジトリのファイルを編集する可能性があるため、状態を変更するスキルとして 扱ってください。引き継ぎ前に差分をレビューしてください。
• シークレット、認証情報、内部 URL、個人データ、ローカル環境の値を エージェントの指示に決して含めないでください。
• ドキュメントを検証するためだけに、デプロイ、公開、データベースの変更、履歴の 書き換え、その他の重大なコマンドを実行しないでください。
• リポジトリのポリシーにすでに存在する承認ゲートを保持してください。
• プライベートリポジトリの指示を第三者サービスにアップロードしないでください。リポジトリの コンテンツを外部に送信する前に、明示的な同意を求めてください。

よくある落とし穴

• コマンドを推測すること: ツールは人気度ではなく、マニフェストと CI から推測してください。
• 単一のレイアウトを強制すること: シンボリックリンクや固定のセクションリストは、ツール固有の、あるいはメンテナーが作成したガイダンスを消してしまう可能性があります。
• 既存のファイルを上書きすること: エビデンスに基づいた最小限の変更にとどめてください。
• README をコピーすること: エージェントの動作を変える情報だけを含めてください。
• ネストされたファイルを重複させること: 共有のガイダンスはルートに置き、ローカルの差分は関連するコードの近くに置いてください。
• 実行していない検証を主張すること: 引き継ぎでは、検査と実行を区別してください。

制限事項

• リポジトリのエビデンスは不完全であったり矛盾していたりする可能性があります。重要なポリシーの選択を安全に解決できない場合は、質問してください。
• 文書化されたコマンドであっても、ローカルで利用できない認証情報、サービス、またはオペレーティングシステムのサポートを必要とする場合があります。
• AGENTS.md のサポートと優先順位はコーディングツールによって異なります。相互運用性が重要な場合は、対象のツールを確認してください。
• このスキルは指示の品質を向上させますが、将来のすべてのエージェントがそのファイルに正しく従うことを証明するものではありません。

関連するスキルとツール

• @agents-generator - パッケージ化された生成、ドライラン、更新、バックアップの各モード。
• @folder-specific-claude-and-agents-md - スコープされた Claude/AGENTS 指示レイアウトに関するより詳細なガイダンス。
• agents.md - 公開フォーマットとスコープに関するガイダンス。