AGENTS.md の管理
AGENTS.md はエージェント向けの正規ドキュメントです。最小限に保ってください。エージェントは有能であり、過剰な指示は不要です。目標は60行未満、最大でも100行を超えないようにしてください。ドキュメントが長くなるほど、指示に従う品質は低下します。
使用するタイミング
- ユーザーが
AGENTS.mdまたはCLAUDE.mdの作成、更新、監査を依頼した場合。 - プロジェクトに、実際のツールチェーンやリポジトリ構成に基づいた、簡潔で高シグナルなエージェント指示が必要な場合。
- 既存のエージェント用ドキュメントが長すぎたり、重複があったり、実際のプロジェクトの慣習から乖離している場合。
ファイルのセットアップ
- プロジェクトルートに
AGENTS.mdを作成 - シンボリックリンクを作成:
ln -s AGENTS.md CLAUDE.md
記述前の分析
ファイルに何を含めるべきか、プロジェクトを分析します:
- パッケージマネージャ — ロックファイルを確認 (
pnpm-lock.yaml,yarn.lock,package-lock.json,uv.lock,poetry.lock) - リンター/フォーマッター設定 —
.eslintrc,biome.json,ruff.toml,.prettierrcなどを確認 (これらを AGENTS.md に重複して書かない) - CI/ビルドコマンド —
Makefile,package.jsonのスクリプト, CI設定から正規のコマンドを確認 - モノレポの兆候 —
pnpm-workspace.yaml,nx.json, Cargo ワークスペース, サブディレクトリのpackage.jsonを確認 - 既存の慣習 — 既存の CONTRIBUTING.md, docs/, README のパターンを確認
記述ルール
- ヘッダー + 箇条書き — 段落は使わない
- コードブロック — コマンドやテンプレートに使用
- 参照、埋め込みはしない — 既存のドキュメントを参照: 「セットアップは
CONTRIBUTING.mdを参照」や「src/api/routes/のパターンに従う」 - 無駄な記述をしない — 導入、結論、挨拶は不要
- 能力を信頼する — 自明なコンテキストは省略
- ファイルスコープのコマンドを優先 — プロジェクト全体のビルドよりも、ファイル単位のテスト/リンター/型チェックコマンドを優先
- リンターを重複させない — コードスタイルはリンター設定に任せ、AGENTS.md には書かない
必須セクション
パッケージマネージャ
どのツールを使うかと、主要なコマンドのみ:
## パッケージマネージャ
**pnpm** を使用: `pnpm install`, `pnpm dev`, `pnpm test`
ファイルスコープのコマンド
ファイル単位のコマンドは、プロジェクト全体のビルドよりも高速で低コストです。利用可能な場合は必ず含めてください:
## ファイルスコープのコマンド
| タスク | コマンド |
|--------|----------|
| 型チェック | `pnpm tsc --noEmit path/to/file.ts` |
| リンター | `pnpm eslint path/to/file.ts` |
| テスト | `pnpm jest path/to/file.test.ts` |
コミット帰属
このセクションは必ず含めてください。エージェントは自身の ID を使用すべきです:
## コミット帰属
AI コミットには以下を含めること:
Co-Authored-By: (エージェントモデル名と帰属クレジット)
例: `Co-Authored-By: Claude Sonnet 4 <[email protected]>`
主要な規約
エージェントが従うべきプロジェクト固有のパターン。簡潔に保つ。
オプションセクション
本当に必要な場合のみ追加:
- API ルートのパターン (説明ではなくテンプレートを示す)
- CLI コマンド (表形式)
- ファイル命名規則
- プロジェクト構造のヒント (重要なファイルを指摘し、避けるべきレガシーコードを明示)
- モノレポの上書き (サブディレクトリの
AGENTS.mdがルートを上書き)
アンチパターン
以下は省略:
- 「ようこそ...」や「このドキュメントは...を説明します」
- 「あなたは...すべき」や「覚えておいて...」
- 設定ファイル (
eslintrc,biome.json,ruff.toml) に既にあるリンター/フォーマッターのルール - インストール済みのスキルやプラグインの一覧 (エージェントはこれらを自動的に検出します)
- プロジェクト全体のビルドコマンド (ファイルスコープの代替がある場合)
- 明らかな指示 (「テストを実行」「きれいなコードを書く」)
- 「なぜ」の説明 (「何を」だけ書く)
- 長い散文の段落
構造例
# エージェント指示
## パッケージマネージャ
**pnpm** を使用: `pnpm install`, `pnpm dev`
## コミット帰属
AI コミットには以下を含めること:
Co-Authored-By: (エージェントモデル名と帰属クレジット)
## ファイルスコープのコマンド
| タスク | コマンド |
|--------|----------|
| 型チェック | `pnpm tsc --noEmit path/to/file.ts` |
| リンター | `pnpm eslint path/to/file.ts` |
| テスト | `pnpm jest path/to/file.test.ts` |
## API ルート
[テンプレートコードブロック]
## CLI
| コマンド | 説明 |
|---------|------|
| `pnpm cli sync` | データを同期 |
制限事項
- このスキルは、上記で説明したタスクに明確に一致する場合にのみ使用してください。
- 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
- 必要な入力、権限、安全性の境界、成功基準が不足している場合は、停止して明確化を求めてください。