agents-md

AGENTS.md ビルダー

目標

主要なディレクトリ境界に AGENTS.md ファイルを配置し、AI エージェント（および人間）向けに、対象範囲を限定した簡潔なガイダンスを追加します。

• ルート：複数の領域にまたがるガイダンスとモジュールマップ（モノレポの場合）
• ネスト：各コンポーネント／モジュール向けの技術固有の指示
• 任意：モジュールレベルの機能マップ

簡潔で正確な指示（短い箇条書き、最小限の文章）を優先します。詳細はドキュメントへのリンクで補います。

（情報が不足している場合に）確認する入力事項

• モノレポ（個別にビルドされる複数のモジュール）ですか、それとも単一プロジェクトですか？
• リポジトリの構成：バックエンド、フロントエンド、ドキュメント、インフラがどこにあるか、主要なモジュール／サブプロジェクトの一覧。
• ドキュメント化する、領域をまたぐワークフロー（例：フロントエンドからバックエンド API を呼び出す、認証フロー、共有型、ローカル開発）。
• 機能マップが必要な場合：ユーザー向けの主要機能を上位 5～15 個（名称）と、それぞれを担当するモジュール。
• ルート AGENTS.md に記載する MCP の利用ルール（許可するサーバー／ツール、安全上の制約）。
• 厳守すべきルール（変更禁止の対象、必須コマンド、スタイルルールなど）。

AGENTS.md の配置場所（目安）

次の場所に AGENTS.md を作成します。

• リポジトリのルート（全体ルール、モジュールマップ、領域をまたぐワークフロー）
• 各主要コンポーネント／モジュールのルート（例：backend/、frontend/、docs/、infra/）
• 慣習、所有者、またはリスクが異なるサブディレクトリ（決済、認証、データ移行など）

実際の境界がない限り、AGENTS.md を深い階層に置くのは避けてください。ファイルが多すぎるとノイズになります。

ワークフロー（チェックリスト）

1. リポジトリの構成を調べる
   • トップレベルのディレクトリとビルドファイル（Gradle／Maven、Node／Next、ドキュメントサイト）を一覧にします。
   • 自然な「コンポーネントのルート」と、重要なサブモジュールを特定します。
2. ルート AGENTS.md を作成する
   • 全体ルール（どこでも適用される事項）のみを記載します。
   • モノレポの場合：モジュール／サブプロジェクトのマップ（機能マップではありません）と、各ネストした AGENTS.md へのリンクを追加します。
   • 技術固有の指示はルートに含めず、担当モジュールの AGENTS.md に記載します。
   • ドキュメント：依頼された場合、または必要な場合を除き、既定では docs/ を開いたり読んだりしないでください。
   • 領域をまたぐワークフロー（モジュール間の連携方法）を追加します。例：フロントエンドとバックエンド API の連携、認証／セッション、契約の配置場所（OpenAPI／GraphQL）、ローカル開発での「同時実行」。
   • リポジトリ横断の検証ガイダンスを追加します。モジュールごとの実行場所と前提条件、最初はログを抑えて実行すること、デバッグ時には失敗箇所を絞って詳細ログで再実行することを記載します。
3. コンポーネントごとにネストした AGENTS.md を作成する
   • 技術固有の指示は、それを担当するモジュールに記載します。
     • バックエンド：実行、テスト、DB の移行方法、主要なモジュールとエントリポイント。
     • フロントエンド：実行、ビルド、テストの方法、環境変数、主要なルート／領域。
     • ドキュメント：ドキュメントの構成、ADR／ランブックの追加先、ドキュメントのプレビュー／ビルド方法。
4. 必要に応じてマップを作成する
   • モノレポの場合：モジュールマップをルートに配置します（references/module-map-format.md を使用）。
   • 機能マップは担当モジュールの AGENTS.md に配置します（references/feature-map-format.md を使用）。
5. 一貫性を確認する
   • 親／子のスコープ間でガイダンスが矛盾しないようにします。
   • 各 AGENTS.md は簡潔で実用的な内容にし、長い詳細は docs/ 配下のドキュメントに移します。

テンプレート

次のテンプレートを使用します。

• ルートおよびモジュールの AGENTS.md：references/agents-template.md
• モジュールマップの形式：references/module-map-format.md
• 機能マップの表形式（モジュールごと）：references/feature-map-format.md
• 推奨する docs/ の構成（Spring + Next）：references/docs-structure.md

成果物

次のものを提供します。

• ルート AGENTS.md（依頼された場合）：モジュールマップと領域をまたぐワークフローを含むもの。
• コンポーネント／モジュールごとの、技術固有のガイダンスを含むネストした AGENTS.md。
• モジュールごとの任意の機能マップ表（依頼された場合）。
• 作成／更新したファイルの一覧と、未解決の質問。