ryonakae/agents-md-creator

AGENTS.md Creator

概要

リポジトリの構造、日常コマンド、検証方法、既存ドキュメントを調べて、短く実用的な AGENTS.md を作る。 生成後はいったん第三者目線で見直し、見つけた改善点を自分で直してから完成させる。 詳細が増えすぎる場合だけ docs/agents/*.md に分割し、ルートには必要最小限だけを残す。

基本原則

• 先に調査し、後から書く。AGENTS.md は推測ではなくリポジトリの事実を要約する。
• まず毎回使う情報を書く。低頻度の詳細や補足は references/best-practices.md の基準に従って外へ逃がす。
• 既存の README.md や docs/ を重複して要約しない。必要なら短い説明とリンクだけ残す。
• コマンド、パス、検証手順のような再現可能な情報を優先し、抽象的な心得だけで埋めない。
• ツール固有記法や特定エージェント専用構文に依存しない。プレーンな Markdown を使う。
• 既存文書の主言語に合わせる。判断材料がなければユーザーに確認する。
• 生成して終わらず、完成前に必ず客観レビューと自己修正を 1 パス入れる。
• レビュー結果は批評メモとして残すのではなく、原則として生成物へ反映する。

進め方

1. 既存の AGENTS.md, README.md, CONTRIBUTING.md, docs/, 主要設定ファイルを読んで、主言語、主要コマンド、検証方法、構造、制約を把握する。
2. references/best-practices.md を読み、ルートに残す内容と分割候補を切り分ける。
3. 高影響で未確定な点だけを短く確認する。例: 主要な開発コマンド、承認境界、必須チェック、生成対象の言語。
4. ルート AGENTS.md は次の順で組み立てる。
   • 一行概要
   • よく使うコマンド
   • 検証手順
   • 重要パスや構造
   • コーディング / テスト規約
   • ワークフロー上の注意
   • 追加ドキュメントへのリンク
5. 詳細が長くなる場合だけ docs/agents/*.md を作り、ルート側には短い説明付きリンクを残す。
6. 生成した内容を、いったん「自分が書いた文書」ではなく「他人が置いた draft」と見なして references/best-practices.md の rubric で客観レビューする。
7. レビューで見つけた問題を優先順位に従って自己修正する。未解決の高影響な曖昧さだけをユーザーに確認する。
8. 完成前に、コマンドの実在、パスの実在、重複、行数、古い記述の混入を再確認する。

生成後レビュー

• レビュー時は、自分の意図を弁護せず、初見のエージェントが読む前提で査読する。
• まず「削るべき情報」「外へ逃がすべき情報」がないかを見て、足りない情報より先に過積載を疑う。
• README.md や docs/ の要約を増やすより、読む順番とリンクの付け方を整える。
• レビューだけで止めず、修正可能な指摘はその場で反映する。
• 最終成果物はレビュー済みで修正済みの AGENTS.md とし、批評メモは補助情報に留める。

ルート AGENTS.md の推奨順序

• 最初に「何のリポジトリで、エージェントが最初に何を見るべきか」を短く書く。
• 次に日常的に使う install, dev, test, lint, build などのコマンドを書く。
• その後にディレクトリ構造、編集方針、レビュー観点、安全上の注意を書く。
• 最後にだけ、補助ドキュメントや低頻度タスクへのリンクを書く。

docs/agents/*.md へ分割する条件

• ルートに入れると流れが崩れる長い説明がある。
• 一部のタスクでしか使わない詳細手順がある。
• 特定のサブシステム、生成物、運用フローだけで必要な知識がある。
• 既存の docs/ と役割を分けた方が読みやすい。

分割した場合も、ルート AGENTS.md は入り口として単独で役立つ状態を保つ。

書かないこと

• 一般論だけのコーディング心得
• リポジトリから確認できない推測
• 既存 docs の焼き直し
• まれにしか使わない運用の詳細手順
• 全ファイル一覧や全スクリプト一覧
• 特定ツールでしか通じない独自構文

仕上げの確認

• ルート AGENTS.md が短く、上から順に読むだけで着手できるか確認する。
• docs/agents/*.md は本当に必要な場合だけ作る。
• 追加したコマンドとパスが実在するか確認する。
• 客観レビューで出た改善点を反映し終えたか確認する。
• 古い AGENTS.md を更新する場合は、残すべきルールと削るべき重複を分けて扱う。