create-agentsmd

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

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

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

AGENTS.md とは？

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

主要な原則

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

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

1. 必須の設定

• ファイルをリポジトリのルートに AGENTS.md として作成します
• 標準的な Markdown 形式を使用します
• 必須フィールドはありません - プロジェクトのニーズに応じた柔軟な構造です

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

プロジェクト概要

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

セットアップコマンド

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

開発ワークフロー

• 開発サーバーの起動方法
• ビルドコマンド
• ウォッチ/ホットリロードのセットアップ
• パッケージマネージャー固有の事項（npm、pnpm、yarn など）

テストの指示

• テストの実行方法（ユニット、統合、e2e）
• テストファイルの場所と命名規則
• カバレッジの要件
• 使用されている特定のテストパターンやフレームワーク
• テストの一部を実行する方法、または特定の領域に焦点を当てる方法

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

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

ビルドとデプロイ

• ビルドコマンドと出力
• 環境設定
• デプロイの手順と要件
• CI/CD パイプラインの情報

3. 任意だが推奨されるセクション

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

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

モノレポの指示（該当する場合）

• 複数のパッケージを扱う方法
• パッケージ間の依存関係
• 選択的なビルド/テスト
• パッケージ固有のコマンド

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

• タイトル形式の要件
• 提出前に必要なチェック
• レビュープロセス
• コミットメッセージの規約

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

• よくある問題と解決策
• ログのパターン
• デバッグ設定
• パフォーマンスに関する考慮事項

テンプレートの例

これを出発点のテンプレートとして使用し、特定のプロジェクトに合わせてカスタマイズしてください:

# AGENTS.md

## Project Overview

[Brief description of the project, its purpose, and key technologies]

## Setup Commands

- Install dependencies: `[package manager] install`
- Start development server: `[command]`
- Build for production: `[command]`

## Development Workflow

- [Development server startup instructions]
- [Hot reload/watch mode information]
- [Environment variable setup]

## Testing Instructions

- Run all tests: `[command]`
- Run unit tests: `[command]`
- Run integration tests: `[command]`
- Test coverage: `[command]`
- [Specific testing patterns or requirements]

## Code Style

- [Language and framework conventions]
- [Linting rules and commands]
- [Formatting requirements]
- [File organization patterns]

## Build and Deployment

- [Build process details]
- [Output directories]
- [Environment-specific builds]
- [Deployment commands]

## Pull Request Guidelines

- Title format: [component] Brief description
- Required checks: `[lint command]`, `[test command]`
- [Review requirements]

## Additional Notes

- [Any project-specific context]
- [Common gotchas or troubleshooting tips]
- [Performance considerations]

agents.md からの実例

以下は agents.md ウェブサイトからの実際の例です:

# Sample AGENTS.md file

## Dev environment tips

- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions

- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions

- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

実装手順

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