agentsmd-claudemd-generator

AGENTS.md & CLAUDE.md ジェネレーター

作成するもの

リポジトリ用に2 つのファイルを生成します。

1. AGENTS.md — オープン標準（https://agents.md）に準拠した、複数のツールで利用できるエージェント向けの指示書です。Claude Code、Cursor、Windsurf、Zed、GitHub Copilot、OpenAI Codex、Aider など、多くのツールでサポートされています。プロジェクトのコンテキスト、規約、ワークフローを記載する主要なファイルです。
2. CLAUDE.md — Claude Code 固有の設定ファイルです。@import を使って AGENTS.md を参照し、Claude 固有の指示を追加します。これにより、2 つのファイル間で内容が重複するのを防げます。

なぜ 2 つのファイルが必要なのですか？

• AGENTS.md は複数のツールで利用できる標準です。あらゆる AI コーディングツールが読み込みます。プロジェクトに関する知識は、すべてここに記載してください。
• CLAUDE.md は Claude Code 固有のファイルです。内容は最小限にし、AGENTS.md を参照したうえで、Claude 固有の情報だけを追加してください。
• これにより、ドキュメントを 1 か所（AGENTS.md）で管理でき、あらゆるツールで活用できます。

---

参考ドキュメント

内容をそのまま記載するより、以下のドキュメントをユーザーに案内してください。

• AGENTS.md 仕様: https://agents.md
• CLAUDE.md のメモリに関するドキュメント: https://code.claude.com/docs/en/memory
• CLAUDE.md ガイド（Builder.io）: https://www.builder.io/blog/claude-md-guide

---

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

1. 既存ファイルを確認する

   • リポジトリ内に既存の AGENTS.md、CLAUDE.md、CLAUDE.local.md、.claude/CLAUDE.md、.claude/rules/ があるか確認します。
   • ファイルがある場合は、上書きするのではなく、更新または拡張する計画を立てます。

2. 主要なドキュメントを読む

   • README.md、CONTRIBUTING.md、および docs/ ディレクトリがあれば、その内容をざっと確認します。
   • プロジェクトの理念、セットアップ手順、ワークフローを把握します。

3. プロジェクトの構成を調べる

   • 主なディレクトリ、言語、フレームワーク、所有者を特定します。
   • tree --gitignore -a -L 3 を実行して、ディレクトリの一覧を取得します。深さは上から 2～3 階層に絞ります。

4. ツールとコマンドを特定する

   • プロジェクトで実際に使用しているビルド、テスト、リント、フォーマット、デプロイのコマンドを調べます。
   • ランタイム、パッケージマネージャー、環境変数、.env.example ファイルなど、環境要件も記録します。

5. 既存のドキュメントを確認する

   • プロジェクトのドキュメントに、コードスタイル、規約、パターン、ベストプラクティス（例: docs/best_practices.md、CONTRIBUTING.md、スタイルガイド）がすでに記載されているか確認します。
   • これらのドキュメントが信頼できる情報源です。AGENTS.md で内容を重複させず、@import で参照してください。
   • ほとんどのコード変更に適用される主要なドキュメント（スタイルガイド、規約、パターン）には、常にコンテキストに読み込まれるよう @import を使用します。
   • ときどきしか必要にならないドキュメント（デプロイ、セットアップ）には、通常の Markdown リンクを使用します。
   • サイズに注意する: @import を推奨する前に、ファイルサイズを確認します。約 300 行（約 1,500 トークン）を超えるファイルがあれば、開発者に注意を促してください。サイズの大きな @import は、会話のたびにコンテキストウィンドウを消費します。最も重要なセクションだけをインポートするか、必要に応じて読む通常のリンクにするよう提案してください。

6. 不明点を解消する

   • 技術スタックを開発者に確認します。コードだけを見て、情報がすべて揃っていると判断しないでください（CI ツール、インフラストラクチャ、プラットフォーム固有の詳細は見落としやすいためです）。
   • 開発者が日常的に使う主要なコマンドを確認します。package.json や Makefile にあるコマンドをすべて列挙するだけでは不十分です。
   • 規約や所有者が不明な場合は、開発者に確認します。推測しないでください。

成果物: 構成、ツール、コマンド、テスト、規約、未解決の質問をまとめた構造化メモ。

---

フェーズ 2 · AGENTS.md を生成する

リポジトリのルートに配置します。一貫性を保つため、以下のセクション順にしてください。

# Agent Guidelines

Brief one-line project description.

Detailed docs live in @docs/... — reference them with @imports rather than duplicating here.

## Tech Stack

- **React** - Component framework
- **TypeScript** - Language (strict mode)
- **Relay** - GraphQL data fetching


## Common Commands

- `<lint command>` — run on changed files
- `<test command>` — run on changed files
- `<type-check command>` — verify types
- `<build command>` — production build

## Pre-Commit Verification

Before every commit, verify code quality on pending files:

\`\`\`sh
<type-check command>
<test command on changed files>
<lint command on changed files>
\`\`\`

Never commit code that fails these checks.

## Code Style & Common Patterns



@docs/best_practices.md



## File Organization


\`\`\`
src/
├── Apps/           # Sub-applications
├── Components/     # Shared across apps
└── System/         # Framework code
\`\`\`

## Workflow

- Branching model
- PR / review expectations
- Commit message format

## Gotchas

- Non-obvious project quirks
- Common pitfalls

## Further Documentation

- [Topic](docs/topic.md)
- And more in @docs

執筆ガイドライン

• 既存のドキュメントを重複させない — プロジェクトでコードスタイル、パターン、規約がすでにドキュメント化されている場合（best_practices.md、CONTRIBUTING.md、スタイルガイドなどのファイル）、内容を繰り返すのではなく、@import を使ってコンテキストに取り込んでください。エージェントが常に参照すべきドキュメント（規約、パターン、スタイルルール）には @import を使います。必要なときだけ参照すればよいドキュメントには、通常の Markdown リンクを使ってください。AGENTS.md は既存のドキュメントを補完するものであり、複製するものではありません。
• 大規模なインポートには注意を促す — @import を追加する前に、ファイルサイズを確認してください。ドキュメントが約 300 行を超える場合、会話のたびにコンテキストウィンドウを大きく消費することを開発者に伝え、全文をインポートするか、主要なセクションだけをインポートするか、通常のリンクとして残すかを尋ねてください。
• テックスタックと、主要なコマンドを開発者に確認してください。コードを調べただけで網羅できていると思い込まないでください。CI ツール、インフラストラクチャ、日常的に使うコマンドは、見落としたり過剰に含めたりしやすいものです。
• 実行可能な内容にしてください — エージェントが曖昧な指針を解釈するのではなく、指示にそのまま従えるようにします。
• 「用途ごとにツールを使い分ける」 — エージェントが適切なライブラリを選べるよう、ツールと用途を対応付けてください（既存のドキュメントで扱われていない場合のみ）。
• 正確なコマンド — 実行内容の説明ではなく、実際のシェルコマンドを記載してください。開発者が最もよく使うコマンドだけを記載し、package.json のスクリプト一覧をすべて載せないでください。
• コミット前のチェック — コミット前に実行するコマンドを記載した検証ブロックを必ず含めてください。
• 詳細なドキュメントを参照する — 内容を重複させるのではなく、詳細なドキュメントへのリンクには @imports を使ってください。
• ファイルツリーに注釈を付ける — tree の出力をそのまま載せず、説明を添えて必要な項目を選んでください。
• 300 行未満にしてください。プロジェクトに関連するセクションのみを含め、該当しないものは省略してください。

---

フェーズ 3 · CLAUDE.md を生成する

AGENTS.md と同じリポジトリルートに配置してください。このファイルは簡潔にし、AGENTS.md を参照する役割に徹します。ほとんどのプロジェクトでは、これだけで十分です。

# CLAUDE.md

See @AGENTS.md

これがファイル全体であることもよくあります。それで問題ありません。プロジェクトで Claude 専用の機能を実際に使っている場合にのみ、Claude 固有のセクションを追加してください。

• .claude/rules/ — プロジェクト内のモジュール式ルールファイルへの参照
• .claude/commands/ — プロジェクトで利用できるカスタムスラッシュコマンド
• .claude/agents/ — カスタムサブエージェント
• Claude の機能に関連する動作上の設定 — 例：「複雑なタスクではプランモードを使う」「並行調査にはサブエージェントを使う」
• ツールの権限に関するヒント — 例：「確認を求めずに npm test を実行してよい」

該当しない場合は、追加しないでください。Claude 固有のセクションが空のまま残るのは、セクション自体がないよりも望ましくありません。

Claude の追加メモリ機能

CLAUDE.local.md、.claude/rules/、@imports、/init、自動メモリなどの高度な機能について、開発者にドキュメント（https://code.claude.com/docs/en/memory）を案内してください。

---

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

1. 両方のファイルがリポジトリルートに存在する。
2. CLAUDE.md が See @AGENTS.md を使って AGENTS.md を参照している。
3. 重複がない — プロジェクトの知識は AGENTS.md のみに記載する。
4. コマンドが正確である — 記載したコマンドがすべて実際に動作する。
5. 簡潔である — 両方のファイルがざっと読める内容で、300 行未満である。
6. 引き継ぎの概要 — 追加した内容を開発者に伝え、未解決の質問があれば示し、高度な機能については公式ドキュメントを案内する。