高品質な AGENTS.md ファイルを作成する

あなたはコード エージェントです。このリポジトリのルートに、https://agents.md/ の公開ガイダンスに従った、完全で正確な AGENTS.md を作成するタスクがあります。

AGENTS.md は、コーディング エージェントがプロジェクトで効果的に作業するために必要なコンテキストと指示を提供するために設計されたオープン形式です。

AGENTS.md とは？

AGENTS.md は、「エージェント向け README」として機能する Markdown ファイルです。AI コーディング エージェントがあなたのプロジェクトで作業できるよう支援するために、予測可能で専用の場所にコンテキストと指示を提供します。README.md を補完し、コーディング エージェントが必要としながらも人間向けの README では煩雑になるような詳細な技術コンテキストが含まれています。

重要な原則

• エージェント向け: 自動化ツール向けの詳細な技術指示が含まれている
• README.md を補完: 人間向けドキュメントに置き換わるのではなく、エージェント固有のコンテキストを追加
• 標準化された場所: リポジトリルート（マルチレポの場合はサブプロジェクトルート）に配置
• オープン形式: 標準的な Markdown を使用した柔軟な構造
• エコシステム互換性: 20 以上の異なる AI コーディングツールとエージェントで動作

ファイル構造とコンテンツのガイドライン

1. 必須セットアップ

• リポジトリルートに AGENTS.md としてファイルを作成
• 標準的な Markdown フォーマットを使用
• 必須フィールドなし - プロジェクトのニーズに基づく柔軟な構造

2. 含めるべき必須セクション

プロジェクト概要

• プロジェクトが何をするかの簡潔な説明
• 複雑な場合はアーキテクチャ概要
• 使用する主要なテクノロジーとフレームワーク

セットアップコマンド

• インストール手順
• 環境セットアップステップ
• 依存関係管理コマンド
• 該当する場合はデータベースセットアップ

開発ワークフロー

• 開発サーバーを開始する方法
• ビルドコマンド
• ウォッチ/ホットリロードセットアップ
• パッケージマネージャーの詳細（npm, pnpm, yarn など）

テスト手順

• テストを実行する方法（単体テスト、統合テスト、E2E）
• テストファイルの場所と命名規則
• カバレッジ要件
• 特定のテストパターンまたはフレームワーク
• テストのサブセットを実行するか特定の領域に焦点を当てる方法

コードスタイルガイドライン

• 言語固有の規則
• リンティングおよびフォーマットルール
• ファイル編成パターン
• 命名規則
• インポート/エクスポートパターン

ビルドとデプロイ

• ビルドコマンドと出力
• 環境設定
• デプロイメントステップと要件
• CI/CD パイプライン情報

3. オプションだが推奨されるセクション

セキュリティに関する考慮事項

• セキュリティテスト要件
• シークレット管理
• 認証パターン
• パーミッションモデル

マルチレポ指示（該当する場合）

• 複数パッケージで作業する方法
• パッケージ間の依存関係
• 選別ビルド/テスト
• パッケージ固有のコマンド

プルリクエストガイドライン

• タイトルフォーマット要件
• サブミッション前の必須チェック
• レビュープロセス
• コミットメッセージ規約

デバッグとトラブルシューティング

• 一般的な問題と解決策
• ロギングパターン
• デバッグ設定
• パフォーマンスに関する考慮事項

テンプレート例

これを開始テンプレートとして使用し、特定のプロジェクトに基づいてカスタマイズします：

# AGENTS.md

## プロジェクト概要

[プロジェクトの簡潔な説明、その目的、および主要なテクノロジー]

## セットアップコマンド

- 依存関係をインストール: `[パッケージマネージャー] install`
- 開発サーバーを開始: `[コマンド]`
- 本番ビルド: `[コマンド]`

## 開発ワークフロー

- [開発サーバー起動手順]
- [ホットリロード/ウォッチモード情報]
- [環境変数セットアップ]

## テスト手順

- すべてのテストを実行: `[コマンド]`
- 単体テストを実行: `[コマンド]`
- 統合テストを実行: `[コマンド]`
- テストカバレッジ: `[コマンド]`
- [特定のテストパターンまたは要件]

## コードスタイル

- [言語とフレームワークの規則]
- [リンティングルールとコマンド]
- [フォーマット要件]
- [ファイル編成パターン]

## ビルドとデプロイ

- [ビルドプロセスの詳細]
- [出力ディレクトリ]
- [環境固有のビルド]
- [デプロイメントコマンド]

## プルリクエストガイドライン

- タイトル形式: [コンポーネント] 簡潔な説明
- 必須チェック: `[lint コマンド]`, `[テストコマンド]`
- [レビュー要件]

## 追加ノート

- [プロジェクト固有のコンテキスト]
- [一般的な落とし穴またはトラブルシューティングのコツ]
- [パフォーマンスに関する考慮事項]

agents.md からの実例

agents.md ウェブサイトからの実際の例です：

# AGENTS.md ファイルのサンプル

## 開発環境のヒント

- `pnpm dlx turbo run where <project_name>` を使用して、`ls` でスキャンする代わりにパッケージにジャンプします。
- `pnpm install --filter <project_name>` を実行して、Vite、ESLint、TypeScript がそれを認識できるようにパッケージをワークスペースに追加します。
- `pnpm create vite@latest <project_name> -- --template react-ts` を使用して、TypeScript チェックの準備ができた新しい React + Vite パッケージをスピンアップします。
- 各パッケージの package.json 内の name フィールドを確認して正しい名前を確認してください。トップレベルのものはスキップしてください。

## テスト手順

- .github/workflows フォルダで CI プランを見つけます。
- `pnpm turbo run test --filter <project_name>` を実行して、そのパッケージに対して定義されたすべてのチェックを実行します。
- パッケージルートから `pnpm test` を呼び出すだけです。コミットはマージ前にすべてのテストに合格する必要があります。
- 1 つのステップに焦点を当てるには、Vitest パターンを追加します：`pnpm vitest run -t "<テスト名>"`。
- テストまたはタイプエラーが完全にグリーンになるまで修正します。
- ファイルを移動またはインポートを変更した後、`pnpm lint --filter <project_name>` を実行して、ESLint と TypeScript ルールがまだ通過することを確認します。
- 誰も求めていなくても、変更したコードのテストを追加または更新してください。

## PR 指示

- タイトル形式: [<project_name>] <タイトル>
- コミットする前に常に `pnpm lint` と `pnpm test` を実行してください。

実装ステップ

1. プロジェクト構造を分析して以下を理解します：

   • 使用されているプログラミング言語とフレームワーク
   • パッケージマネージャーとビルドツール
   • テストフレームワーク
   • プロジェクトアーキテクチャ（マルチレポ、単一パッケージなど）

2. 主要なワークフローを特定するために以下を確認します：

   • package.json スクリプト
   • Makefile またはその他のビルドファイル
   • CI/CD 設定ファイル
   • ドキュメントファイル

3. 包括的なセクションを作成して以下を対象とします：

   • すべての必須セットアップおよび開発コマンド
   • テスト戦略とコマンド
   • コードスタイルと規則
   • ビルドおよびデプロイメントプロセス

4. エージェントが直接実行できる具体的で実行可能なコマンドを含める

5. 指示をテストしてすべてのコマンドがドキュメント化されたとおりに動作することを確認

6. 焦点を保つエージェントが知る必要があることに集中し、一般的なプロジェクト情報ではない

ベストプラクティス

• 具体的に: 曖昧な説明ではなく、正確なコマンドを含める
• コードブロックを使用: コマンドをバッククォートで囲んで明確にする
• コンテキストを含める: 特定のステップが必要な理由を説明する
• 最新を保つ: プロジェクトが進化するにつれて更新する
• コマンドをテスト: 一覧にあるすべてのコマンドが実際に機能することを確認
• ネストされたファイルを検討: マルチレポの場合、サブプロジェクトディレクトリに AGENTS.md ファイルを作成することを検討

マルチレポの考慮事項

大規模なマルチレポの場合：

• リポジトリルートにメイン AGENTS.md を配置
• サブプロジェクトディレクトリに追加の AGENTS.md ファイルを作成
• 特定の場所に対して最も近い AGENTS.md ファイルが優先されます
• パッケージ/プロジェクト間のナビゲーションのヒントを含める

最終注釈

• AGENTS.md は Cursor、Aider、Gemini CLI、および多くの他のツールを含む 20 以上の AI コーディングツールで動作します
• このフォーマットは意図的に柔軟です - プロジェクトのニーズに合わせて適応させてください
• エージェントがコードベースを理解し、作業するのに役立つ実行可能な指示に焦点を当てます
• これはライブドキュメントです - プロジェクトが進化するにつれて更新してください

AGENTS.md ファイルを作成するときは、明確さ、完全性、および実行可能性を優先してください。目標は、追加の人間ガイダンスを必要とせずに、コーディング エージェントがプロジェクトに効果的に貢献できるように十分なコンテキストを提供することです。