AGENTS.md ファイル仕様
AGENTS.md ファイルは、各種 AI コード開発ツールにおいて AI エージェントの動作を設定するための標準化されたスキームを提供します。このファイルを通じて、開発者はプロジェクト固有の指示、コーディング標準、規範を定義し、AI エージェントがコードベースを処理する際に統一された要求に従うように指示できます。
AGENTS.md の定義
AGENTS.md は、ソフトウェアプロジェクトにおいて AI エージェントの動作パターンを設定するために使用されます。これはプロジェクトのルートディレクトリに配置される軽量な Markdown ファイルで、AI コードアシスタント向けの指示セットが含まれています。現在、この標準は複数の主要な AI コードツールでサポートされています。
AGENTS.md はAI エージェント向けの README ファイルと理解できます。特定のプロジェクトにどのように適応するか、どのコーディング規約に従うべきか、遵守すべき制約条件を AI エージェントに明確に伝えます。
AGENTS.md を使用するメリット
- クロスツール互換性： 修正なしで複数の AI コードツールで動作
- バージョン管理： プロジェクトコードと共にコードリポジトリに保存され、バージョン追跡が可能
- チームコラボレーションの一貫性： チーム全員の AI アシスタントが統一された規範に従うことを保証
- プロジェクトのカスタマイズ適応： プロジェクトの固有の要件とコーディング規約に基づいて設定可能
- シンプルな文法： 純粋な Markdown 形式で記述され、特殊な文法や設定ルールを習得する必要がない
ファイル命名と配置パス
プロジェクトレベルの AGENTS.md ファイル
AGENTS.md ファイルはプロジェクトのルートディレクトリに配置する必要があります。ディレクトリ構造の例は以下の通りです。
my-project/
├── AGENTS.md # メイン設定ファイル（推奨）
├── src/
├── package.json
└── README.mdファイル命名の優先度（認識順に並べられています）：
- AGENTS.md（大文字複数形、推奨）
- AGENT.md（大文字単数形、代替）
⚠️ ファイル名の大文字小文字ルール：
ファイル名はすべて大文字（AGENTS.md）である必要があり、小文字形式（agents.md）はサポートされていません。この設計により、異なるオペレーティングシステムや開発ツール間での一貫性が保証されます。
サブディレクトリレベルの AGENTS.md ファイル
開発者はサブディレクトリにも AGENTS.md ファイルを配置し、コンテキスト固有の指示を定義できます。ディレクトリ構造の例は以下の通りです。
my-project/
├── AGENTS.md # ルートディレクトリレベルのグローバル指示
├── src/
│ └── backend/
│ └── AGENTS.md # バックエンドモジュール固有の指示
└── docs/
└── AGENTS.md # ドキュメントモジュール固有の指示サブディレクトリで開発する場合、VJSP ツールはルートディレクトリの AGENTS.md と現在のサブディレクトリの AGENTS.md の両方を読み込みます。指示が競合した場合、サブディレクトリのファイルの指示が優先されます。
ファイル保護メカニズム
VJSP ツールでは、AGENTS.md と AGENT.md はいずれも書き込み保護ファイルです。具体的なルールは以下の通りです。
- ユーザーの明示的な許可なしに、AI エージェントはこれらのファイルを変更できません
- ツールは確認プロンプトを表示し、ファイルの変更操作を実行するにはユーザーの手動確認が必要です
- このメカニズムにより、AI エージェントの誤操作によるプロジェクトの AI 設定ファイルの改ざんを効果的に防止します
基本的な文法とファイル構造
AGENTS.md ファイルは標準的な Markdown 文法で記述され、強制的な構造はありません。ただし、見出しとリストでコンテンツを整理することで、AI モデルによる指示の解析効率と理解度が向上します。
推奨されるファイル構造
# プロジェクト名
プロジェクトの簡単な説明とコアな用途
## コーディングスタイル
- すべての新規ファイルは TypeScript で開発する
- ESLint の設定規範を厳格に遵守する
- インデントはスペース 2 つを使用する
## アーキテクチャ設計
- MVC デザインパターンに従う
- コンポーネントのコード行数は 200 行以内に制限する
- 依存性注入パターンを採用する
## テスト規範
- すべてのビジネスロジックコードにはユニットテストを作成する
- コードカバレッジは 80% 以上に維持する
- テストフレームワークは Jest を統一して使用する
## セキュリティ規範
- API キーや機密情報をコードリポジトリにコミットすることを厳禁する
- すべてのユーザー入力に対して正当性検証を実行する
- データベース操作にはパラメータ化クエリを使用する作成のベストプラクティス
- 指示の明確化： 「循環的複雑度の上限は 10」など具体的で定量化可能なルールを採用し、「高品質なコードを作成する」といった曖昧な表現を避ける
- 例の具体化： エラー処理、命名規則、アーキテクチャ設計の標準的なパターンを示すコード例を埋め込む
- 分類と構造化： 関連する規範を明確な見出し（コーディングスタイル、アーキテクチャ設計、テスト規範、セキュリティ規範など）の下にグループ化する
- コンテンツの簡潔化： 箇条書きと直接的な文を使用し、長い段落を避ける
- メンテナンスの常態化： プロジェクトのコーディング規約の進化に伴い、定期的にファイル内容をレビューおよび改訂する
VJSP における AGENTS.md の動作メカニズム
ファイル読み込みプロセス
VJSP で開発タスクを開始する際、ツールは以下の操作を実行します。
- プロジェクトのルートディレクトリに
AGENTS.mdまたはAGENT.mdファイルが存在するかを確認する - ファイルが検出された場合、その内容を読み込み、AI エージェントのコンテキスト環境に注入する
- AI エージェントは対話全体を通じてファイル内の指示に従う
- AGENTS.md ファイルを変更した後、新しいルールは新規タスクで有効になります（ツールの再起動が必要な場合があります）
他のルールシステムとの優先度関係
AGENTS.md は VJSP の他の設定システムと連携して動作し、優先度は高い順から低い順に以下の通りです。
| 設定の種類 | 範囲 | 配置パス | 主な用途 | 優先度 |
|---|---|---|---|---|
| モード固有のカスタムルール | プロジェクト | .vjsp/rules-{mode}/ | 特定の開発モード向けのルール制約 | 1（最高） |
| カスタムルール | プロジェクト | .vjsp/rules/ | VJSP ツール固有のルール設定 | 2 |
| AGENTS.md ルール | プロジェクト | ルートディレクトリ / サブディレクトリ | クロスツール互換のプロジェクトレベル規範 | 3 |
| グローバルカスタムルール | グローバル | ~/.vjsp/rules/ | VJSP ツールのグローバルルール設定 | 4 |
| カスタム指示 | グローバル | IDE 設定 | すべてのプロジェクトに適用される個人的な設定 | 5（最低） |
機能の有効化と無効化
VJSP では AGENTS.md 機能はデフォルトで有効になっています。無効にするには、settings.json 設定ファイルに以下のパラメータを追加してください。
{
"VJSP.useAgentRules": false
}