hierarchical-agents

階層型エージェントドキュメント生成ツール

目的

AI コーディングエージェントが最小限のトークン使用量で効率よく作業できる、階層型 AGENTS.md システムをコードベース向けに作成します。「最も近いものを優先する」原則に従い、ルートには軽量なドキュメントを、サブフォルダーには詳細なガイダンスを生成します。

使用する場面

• 新しいプロジェクト用の AGENTS.md ドキュメントを作成するとき
• モノレポ向けの AI エージェントガイダンスを設定するとき
• 既存のドキュメントをトークン効率のために最適化するとき
• JIT（ジャストインタイム）インデックスパターンを実装するとき

プロセス

以下のフェーズを順番に実施してください。詳細については、references/generation-process.md を参照してください。

フェーズ 1：リポジトリの分析

コードベースを分析します。

1. リポジトリの種類（モノレポ、複数パッケージ、シンプル）
2. 技術スタック（言語、フレームワーク、ツール）
3. 主要なディレクトリ（アプリ、サービス、パッケージ）
4. ビルドシステムとテストの設定
5. 主要なパターン、規約、アンチパターン

出力：ファイルを生成する前に、リポジトリの構造化マップを作成します。

フェーズ 2：ルート AGENTS.md の生成

ルートは軽量に保ちます。最大で約 100～200 行とし、普遍的なガイダンスのみを記載します。インデックスおよびナビゲーションハブとして機能させます。エージェントは編集対象ファイルに最も近い AGENTS.md を読み込みます。サブフォルダーのファイルはルートの内容を上書きします（最も近いものを優先）。

以下のセクションを含むルートファイルを作成します。

1. プロジェクトの概要（3～5 行）
   • リポジトリの種類
   • 主要な技術スタック
   • サブパッケージに AGENTS.md ファイルがあることを記載
2. ルートのセットアップコマンド（5～10 行）
   • 依存関係のインストール、全体のビルド、全体の型チェック、全体のテスト
3. 共通規約（5～10 行）
   • コードスタイル（TypeScript の strict モード？ Prettier？ ESLint？）
   • コミット形式（Conventional Commits？）
   • ブランチ戦略
   • PR の要件
4. 実装ルール（2～3 行）— 以下の例を参照
5. 開発ワークフロー（5～7 行）— 以下の例を参照
6. セキュリティとシークレット（3～5 行）
   • トークンを絶対にコミットしない
   • シークレットの保存場所（.env のパターン）
   • PII の取り扱い
7. JIT インデックス - ディレクトリマップ（10～20 行）— 以下の例を参照
   • 内容ではなくパスでファイルを参照
   • エージェントが実行できる検索コマンドを提示
8. 受け入れ基準（3～5 行）
   • PR 前のチェックリスト
   • 合格必須の項目

実装ルールの例：

## Implementation Rules

Before adding ANY external dependency (gems, npm packages, GitHub Actions, Docker images, APIs, CDN links):
- Use WebSearch to verify the latest stable version BEFORE implementation
- Never trust training data for version numbers

JIT インデックスの例：

## JIT Index (what to open, not what to paste)

### Package Structure
- Web UI: `apps/web/` -> [see apps/web/AGENTS.md](apps/web/AGENTS.md)
- API: `apps/api/` -> [see apps/api/AGENTS.md](apps/api/AGENTS.md)
- Shared packages: `packages/**/` -> [see packages/README.md]

### Quick Find Commands
- Search function: `rg -n "functionName" apps/** packages/**`
- Find component: `rg -n "export.*ComponentName" apps/web/src`
- Find API routes: `rg -n "export const (GET|POST)" apps/api`

開発ワークフローの例：

## Development Workflow

- Before coding -> describe approach -> wait for approval
- Ambiguous requirements -> ask first
- If task touches >3 files -> decompose first
- After coding -> list breakage risks + suggest tests
- Bug fix -> write failing test -> fix until green
- When corrected -> add lesson to .agents/lessons/

フェーズ 3：サブフォルダーの AGENTS.md ファイルを生成

サブフォルダーにはルートよりも詳しい情報を記載します。具体的なパターン、技術固有の規約、コードベース内の実際のファイルの例を含めます。

主要なパッケージ／ディレクトリごとに、詳細な AGENTS.md を作成します。

1. パッケージの概要（2～3 行）
2. セットアップと実行（5～10 行）
3. パターンと規約（10～20 行）— 最重要
4. 関連箇所／主要ファイル（5～10 行）
5. JIT インデックスのヒント（5～10 行）
6. よくある落とし穴（3～5 行）
7. PR 前のチェック（2～3 行）

重要：パターンと規約には、実際のファイルパスを使用した DO／DON'T の例を含めてください。

フェーズ 4：特別な考慮事項

特定のパッケージ種別（デザインシステム、データベース、API、テスト）に応じてテンプレートを調整します。 特化したテンプレートについては、references/generation-process.md を参照してください。

ディレクトリ構成

モノレポ

AGENTS.md                    # Root (lightweight)
apps/
  web/AGENTS.md             # Frontend details
  api/AGENTS.md             # Backend details
packages/
  ui/AGENTS.md              # Design system details
  shared/AGENTS.md          # Shared code details

シンプルなプロジェクト

AGENTS.md                    # Root (can be more detailed)
src/
  components/AGENTS.md      # Component patterns
  services/AGENTS.md        # Service patterns

品質チェックリスト

• ルートの AGENTS.md が 200 行未満である
• ルートからすべてのサブ AGENTS.md ファイルにリンクしている
• 各サブファイルに具体例（実際のファイルパス）がある
• コマンドをコピー＆ペーストして実行できる
• ルートとサブファイルで内容が重複していない
• すべての DO に実際のファイル例がある
• すべての DON'T が実際のアンチパターンを示している
• すべてのパスが相対パスで、実在することを確認済みである
• AGENTS.md があるのは主要なパッケージ／ドメインのみで、すべてのディレクトリには作成していない

メンテナンス

以下の場合に AGENTS.md を更新します。

• 新しいパッケージや主要なディレクトリを追加するとき
• ビルド／テストコマンドを変更するとき
• 新しい規約を定めるとき
• プロジェクト構成をリファクタリングするとき

関連リソース

• references/generation-process.md - テンプレートを含む、生成プロセスの完全な手順