agentsmd-generator

エージェントコンテキスト生成ツール

実施内容

• 🔍 リポジトリの構造を調査し、.gitignore を考慮した tree の出力を取得して、自動化のエントリーポイントを記録します（利用可能な場合は just／make のタスクを優先します）
• 🧭 コーディング規約、ディレクトリの管理担当、テスト要件、レビューのワークフローを記録し、後続のエージェントが迷わず作業できるようにします
• 🧩 以下に示す推奨セクション順に従い、ネストしたディレクトリのスコープ規則を守って AGENTS.md ファイルを作成します
• ✅ 共通の作業完了タスクを盛り込みます。重要なコード変更後は README を更新し、変更内容を Conventional Commits に従って要約し、不明点があれば開発者に確認します

---

フェーズ 1 · リポジトリを把握する

1. 既存の AGENTS.md を確認する
   • find の代わりに glob またはリポジトリツリーを使って、既存のファイルを見つけます。スコープの継承関係を確認し、重複させずに更新または拡張できるか判断します。
2. 主要ドキュメントを読む
   • README.md、CONTRIBUTING.md、その他のオンボーディングドキュメントに目を通し、プロジェクトの理念、セットアップ、ワークフローを把握します。
   • docs/ または documentation/ がある場合は、記載すべきアーキテクチャやプロセスに関する情報を探します。
3. プロジェクトの構成を調査する
   • 主要なディレクトリ、言語、ビルドターゲット、管理担当（例："src/ui はフロントエンドチームが管理"）を確認します。
   • plans/、docs/、その他のナレッジディレクトリがあるか確認します。後で AGENTS.md に記載する、必読のファイル（ADR インデックス、アーキテクチャ概要、運用手順書など）を挙げます。
4. Git を考慮したツリーを作成する
   • tree コマンドで --gitignore フラグ（tree ≥ 2.0）を使い、無視対象のパスを非表示にします：tree --gitignore -a -L 3 > tmp/tree.txt。
   • 使用中の tree が --gitignore に対応していない場合は、tree -a -L 3 --prune を実行し、.gitignore に記載された無視対象のディレクトリを手動で除外するか、パッケージマネージャーで新しいバージョンをインストールします。
   • 出力を取得または簡潔に整理してから AGENTS.md に記載します（最上位から 2～3 階層を中心にし、簡潔さのために省略した場合はその旨を記します）。
5. 自動化ランナーを特定する
   • Justfile がある場合は、just --list（補足情報を表示するには just --list --unsorted）を実行します。
   • Makefile があり、just がない場合は、make help を実行するか、標準のタスクを確認するために phony ターゲットを調べます。
   • lint、テスト、ビルド、データ同期などに推奨されるコマンドを記録します。後で記載するため、メモに挙げた正式なタスク名へのリンクを含めます。
6. ツールと環境を一覧にする
   • 必要なランタイム、パッケージマネージャー、環境変数、シークレットの取り扱い、ローカルサービスを一覧にします。
   • エージェントが確認すべき .env.example、config/、シークレットのドキュメントがあれば記録します。
7. テストと品質ゲートを明確にする
   • テストスイート、カバレッジ要件、lint、フォーマット、CI ワークフローを特定します。
8. 曖昧な点を早めに解消する
   • 規約、管理担当、ワークフローが不明確な場合は、ガイドを作成する前に、焦点を絞った質問を開発者にします。
   • 既存の plans/ やドキュメントディレクトリが正式な情報源か、古くなっているかを明示的に確認し、参照すべき正本を明確にします。

成果物： 構成、ツール、コマンド、テスト、リリースプロセス、ドキュメントの参照先、未解決の質問、更新に関する要件をまとめた構造化されたメモ一覧。

フェーズ 2 · AGENTS.md の構成を計画する

ファイルの一貫性と見やすさを保つため、次の順序に従ってください。

1. ヘッダー — タイトルと簡潔な目的説明。
2. 基本情報 — 言語、パッケージマネージャー、主要なスクリプト、CI を表または箇条書きで要約します。
3. リポジトリ案内 — 役割と担当範囲のヒントを添えた、ディレクトリ構成の概要。
4. ツールとセットアップ — 必要なランタイム、パッケージマネージャー、環境変数、シークレット。
5. 一般的なタスク — Lint／テスト／ビルド／デプロイのコマンド。まず just のレシピ、次に make のターゲット、最後に生のコマンドを記載してください。
6. テストと品質 — テスト、Lint、フォーマット、カバレッジ、CI の期待事項を、実行するタイミングと方法とともに記載します。
7. ワークフローの方針 — ブランチモデル、レビューの慣例、機能フラグ、デプロイの頻度。
8. ドキュメントの更新 — README.md、アーキテクチャ図、その他のドキュメントを更新するタイミング。
9. タスクの完了 — エージェントがすべてのタスクで必ず実行する、作業終了時のチェックリスト。

（例：services/api/）などの下位ディレクトリでは、親の AGENTS 指示をどのように引き継ぐかを明確にする「Scope」注記を冒頭に追加してください。ディレクトリごとの AGENTS ファイルを新たに作成する前に、既存の指針と重複したり、不要な負担を生んだりしないよう、必ず開発者に確認してください。

---

フェーズ 3 · AGENTS.md を作成する

以下のテンプレートを使用し、プロジェクトに合わせて各セクションを調整してください。

# Project Agent Guide

> Scope: Root project (applies to all subdirectories unless overridden)

## Quick Facts
- **Primary language:**
- **Package manager:**
- **Entrypoints:**
- **CI/CD:**

## Repository Tour
- `path/` — description & owner

## Tooling & Setup
- Install instructions (per OS)
- Required environment variables (with purpose)
- Secrets management notes

## Common Tasks
- `just <task>` — what it does (preferred)
- `make <target>` — what it does
- Raw command fallback when automation missing

## Testing & Quality Gates
- Unit/integration test commands
- Lint/format commands
- Coverage expectations & thresholds
- CI status command or dashboard link

## Workflow Expectations
- Branch naming and review rules
- Feature toggles or release cadence
- Any approval or ticket linkage requirements

## Documentation Duties
- Update `README.md` when features, setup steps, or developer ergonomics change materially
- List other docs to refresh (architecture, ADRs, etc.)

## Finish the Task Checklist
- [ ] Update relevant docs (& `README.md` if significant changes landed)
- [ ] Summarize changes in conventional commit format (e.g., `feat: ...`, `fix: ...`)

サブディレクトリ用テンプレート（開発者の承認がある場合のみ使用）

# <Directory Name> Agent Guide

> Scope: ./path/to/directory (inherits root AGENTS.md unless noted)

## Purpose
- What lives here
- Who owns it (team/contact)

## Key Files
- `file_or_folder/` — why it matters

## Common Tasks
- `just <task>` / `make <target>` / command snippets scoped to this directory

## Testing & Quality
- Specific tests, linters, or data fixtures for this directory

## Hand-off Notes
- Docs or runbooks to reference
- Open questions captured during discovery

ディレクトリごとのガイドは、専用のコンテキストが必要な領域と、強調する情報について開発者に確認してから作成してください。

記述上の注意：

• 直接的で実行しやすい言葉で記述してください。エージェントはコマンドに記載されたとおりに実行できるようにします。
• 推奨する作業順序（例：「PR を開く前に、必ず just format を実行してください」）を記載してください。
• スクリプトを参照する際は、エージェントがすぐに移動できるよう相対パスを含めてください（例：scripts/bootstrap.sh）。
• tree --gitignore の要点を絞ったスナップショット（または保存済みの成果物へのリンク）を含め、読者が構成をすぐ把握できるようにしてください。
• 「リポジトリ案内」では、存在する場合、plans/、docs/、設計ドキュメント、ADR の場所を示してください。
• 未回答の質問があればアクション項目として記載し、ディレクトリごとの AGENTS オーバーレイを作成する前に開発者に確認してください。
• プロジェクトで複数の言語やプラットフォームを使用している場合は、コンポーネントごとのサブセクションを追加しつつ、全体に適用される指針を先に記載してください。

---

フェーズ 4 · 検証と仕上げ

1. セルフレビュー
   • ファイルは AGENTS のスコープルールに従っていますか？（継承または上書きについて記載していますか？）
   • 重要なコマンド、特に自動化のエントリーポイントはすべて記載されていますか？
   • README の更新について明確に説明されていますか？
   • ディレクトリごとの AGENTS ファイルを追加する前に開発者の承認を得ており、その承認が説明に反映されていますか？
   • 「タスクの完了」チェックリストに、Conventional Commits 形式のコミット概要に関するリマインダーが含まれていますか？
2. フォーマット
   • 見出しはタイトルケースにし、コマンドはバッククォートで囲み、箇条書きは簡潔にしてください。
   • セクションは、表のほうが適切な場合を除き、箇条書きを約 8 項目以内にしてください。
3. 引き継ぎ概要
   • AGENTS.md をユーザーに渡す際は、次の内容を含めてください。
     • 追加・更新した主なセクションの簡潔な概要。
     • README と Conventional Commits のリマインダーが含まれていることの確認。
     • 追加の提案（例：テストの不足、スクリプトの古さ）。

リポジトリに AGENTS のコンテキストがない場合や、既存の指示が不完全または古くなっている場合は、このスキルを使用してください。目的は、今後のエージェントがプロジェクト、ツール、責任を持ってタスクを完了するための方針を把握できる、信頼できる唯一の案内を残すことです。