agents-md

このスキルでは、AI コーディングエージェントを導くためのオープン標準フォーマットである AGENTS.md ファイルの作成、検証、改善に関する専門的なガイダンスを提供します。

AGENTS.md とは？

AGENTS.md は、6 万以上のオープンソースプロジェクトで使われている、コーディングエージェントを導くためのシンプルなオープンフォーマットです。エージェント向けの README と考えてください。プロジェクトで作業する AI コーディングエージェントを支援するためのコンテキストや指示を提供する、専用のわかりやすい場所です。

重要な原則： README.md は人間向けですが、AGENTS.md には、コーディングエージェントが必要とする詳細な追加情報（ビルド手順、テスト、規約、README を煩雑にしかねない指示）が記載されます。

詳しくはこちら： https://agents.md/ | https://www.aihero.dev/a-complete-guide-to-agents-md

クイックスタート

ユーザーが AGENTS.md ファイルの作成を希望する場合

まず、次の確認事項について質問してください。

1. プロジェクトの種類： モノレポですか、それとも単一パッケージですか？
2. 技術スタック： どの言語やフレームワークを使っていますか？
3. パッケージマネージャー： npm、pnpm、yarn、bun、またはその他のどれですか？
4. ビルド／テストコマンド： 標準以外のコマンドはありますか？
5. 個別の懸念事項： 推奨したい、または避けたいパターンはありますか？

次に、以下のテンプレートに従って、最小限の AGENTS.md を作成してください。

ユーザーが既存の AGENTS.md の検証を希望する場合

検証チェックリスト（下記の検証を参照）に沿って確認してください。

ユーザーが既存の AGENTS.md の改善を希望する場合

ファイルを評価し、段階的開示を取り入れたリファクタリングを提案してください（下記の改善を参照）。

基本原則

1. ルートの AGENTS.md は最小限にする

ルートの AGENTS.md はできる限り小さくしてください。すべてのトークンが各リクエストで読み込まれるため、あらゆるタスクに必要な内容だけを含めます。

必須要素のみ：

• プロジェクトを説明する一文（役割に基づくプロンプトとして機能します）
• パッケージマネージャー（npm 以外の場合。警告には corepack を使います）
• 標準以外のビルド／型チェックコマンド
• 段階的開示用ファイルへのリンク

2. 段階的開示

AGENTS.md にすべてを詰め込むのではなく、エージェントにその時点で必要な情報だけを伝え、必要に応じて他のリソースを参照するようにします。

例 — これは避けてください：

## Code style

- Always use const instead of let
- Use interface instead of type when possible
- Prefer functional patterns
- No semicolons
- Single quotes only
- ... (50 more lines)

代わりに、次のようにします：

For TypeScript conventions, see docs/TYPESCRIPT.md

メリット：

• TypeScript のルールは、エージェントが TypeScript を書く場合にのみ読み込まれます
• 他のタスクでトークンを無駄にしません
• ファイルの内容が絞られ、モデルが変わってもそのまま使えます

3. ファイル構成ではなく、できることを記述する

ファイルパスは頻繁に変わります。構成を文書化すると情報が古くなり、コンテキストを損なう原因になります。

避ける例：

Authentication logic lives in src/auth/handlers.ts

推奨例：

Authentication uses JWT tokens with refresh token rotation.
Look for modules matching **/auth/**/*.ts for implementation.

4. モノレポでは AGENTS.md をネストする

サブディレクトリに AGENTS.md ファイルを配置すると、ルート階層の内容と統合されます。

階層	内容
ルート	モノレポの目的、ナビゲーション、共有ツール
パッケージ	パッケージの目的、技術スタック、固有の規約

ルートの AGENTS.md：

This is a monorepo containing web services and CLI tools.

Use pnpm workspaces to manage dependencies.

See each package's AGENTS.md for specific guidelines.

パッケージの AGENTS.md（packages/api/AGENTS.md）：

This package is a Node.js GraphQL API using Prisma.

Follow docs/API_CONVENTIONS.md for API design patterns.

コンテンツに関する推奨事項

AGENTS.md の内容を作成または改善する際は、コード品質を高めるプロジェクト固有のガイダンスを推奨してください。すべてのタスクに当てはまる場合のみルートファイルに記載し、それ以外は docs/QUALITY.md、docs/TYPESCRIPT.md、docs/TESTING.md、docs/ARCHITECTURE.md、docs/FRONTEND.md など、内容を絞った段階的開示用ファイルへのリンクを記載してください。

コード品質

• DRY を守り、ロジックを重複させず、既存のユーティリティ、コンポーネント、パターンを再利用してください。
• 車輪の再発明は避け、既存のプロジェクト依存関係やモジュールが適している場合は優先してください。
• 小さくまとまり、境界が明確な単位で構成する、モジュール型アーキテクチャを優先してください。
• 巨大なコンポーネント、関数、ファイルを作成しないでください。コードの把握が難しくなったら、責務を分割してください。
• 速度より品質を優先してください。回避できる設計、型、テストの負債が残っている場合、タスクは完了していません。

型安全性

• 型付き言語では、完全な型安全性を維持してください。
• any、as any、: any は使用せず、代わりに正確な型、ジェネリクス、判別可能なユニオン、またはスキーマから導出した型を使用してください。
• フレームワークが生成したファイルは、フレームワークが生成された型を管理する場合に限り対象外です。

検証とテスト

• 作業完了時には、型チェック、ビルド、関連するテストがすべて成功している必要があります。成功していない場合、作業は未完了です。
• 検証を実行できない場合は、その理由と未検証の項目を記録してください。
• エッジケースやリグレッションを含め、重要な動作については包括的なテストを推奨してください。
• ユーザーがすでに開発サーバーを実行している場合は、開発サーバーを起動しないでください。代わりにビルド、型チェック、テスト、静的チェックを使用してください。

フロントエンドアーキテクチャ

• 明確な責務を持つ小さな再利用可能コンポーネントでフロントエンド UI を構築し、それらを組み合わせて大きなセクションやページを作成してください。
• 大規模な単発コンポーネントよりも、再利用可能で役割が明確なコンポーネントを優先してください。
• フロントエンドアプリケーションにはグローバルエラーバウンダリーを含め、予期しない UI の障害が安全に処理されるようにしてください。

テンプレート

単一パッケージ向けの最小限の AGENTS.md

# AGENTS.md

[One-sentence description of what this project is]

## Package Manager

This project uses [pnpm/yarn/bun]. [Optional: brief note if workspaces/monorepo]

## Build & Test

- Build: `command here`
- Test: `command here`
- Typecheck: `command here` (if non-standard)

## Progressive Disclosure

- [Domain-specific]: [path/to/file.md]

モノレポのルート向けの最小限の AGENTS.md

# AGENTS.md

This is a monorepo containing [brief description of packages].

## Package Manager

Use [pnpm workspaces/yarn workspaces] to manage dependencies.

## Navigation

- Use `pnpm --filter <package_name>` to run commands in specific packages
- Each package has its own AGENTS.md with specific guidelines

## Packages

- [`package-name`](packages/package-name): [brief purpose]
- [`package-name`](packages/package-name): [brief purpose]

パッケージレベルの AGENTS.md（モノレポ）

# AGENTS.md

[One-sentence description of this package]

## Tech Stack

- [Framework]
- [Language]
- [Key libraries]

## Commands

- Build: `command here`
- Test: `command here`
- Dev: `command here`

## Progressive Disclosure

- [Domain]: [path/to/file.md]

検証

既存の AGENTS.md を検証する際は、次の問題がないか確認してください。

冗長さの指標

• ファイルが 50～75 行を超えている
• 別ファイルに記載すべき詳細なコーディングスタイルのルールが含まれている
• ファイルパスが詳細に記述されている
• ドキュメントに記載すべき詳細な例が含まれている
• CONTRIBUTING.md に記載すべき git ワークフローの説明が含まれている

矛盾の検出

矛盾する指示がないか確認してください。

• 「関数型のパターンを使う」と「X にはクラスを使う」
• 「合成を優先する」と「Y には継承を使う」
• 「常に X を使う」と「Y の場合は Z を使う」

古い情報のリスク

• 特定のファイルパス（特に src/ ディレクトリ）
• ファイルやモジュールの一覧
• バージョン固有のツールチェーンコマンド
• 古くなったアーキテクチャの説明

ベストプラクティスへの準拠

• プロジェクトを一文で説明している
• パッケージマネージャー（npm 以外の場合）を指定している
• 段階的に開示するファイルへのリンクがある
• 該当する場合、アーキテクチャ、型安全性、テスト、フロントエンドに関する期待事項を網羅するコード品質のガイダンスを含めるか、リンクしている
• 会話的な口調を使っている（「必ず」「絶対に」などの表現を避けている）
• 構成ではなく、できることを説明している

改善

冗長な AGENTS.md のリファクタリング

冗長な AGENTS.md をリファクタリングするには、次の手順を使ってください。

1. 矛盾を見つける：矛盾する指示を特定し、どれを残すか確認する
2. 要点を抽出する：ルートの AGENTS.md に含めるべき内容だけを残す
3. 残りを分類する：残りの指示を論理的なカテゴリに整理する
4. ファイル構造を作成する：段階的開示の階層を設定する
5. 削除対象を指定する：重複した指示、曖昧な指示、自明な指示を削除する

使用するプロンプトのテンプレート：

I want you to refactor my AGENTS.md file to follow progressive disclosure principles.

1. **Find contradictions**: Identify any instructions that conflict with each other.
   For each contradiction, ask me which version I want to keep.

2. **Identify the essentials**: Extract only what belongs in the root AGENTS.md:
   - One-sentence project description
   - Package manager (if not npm)
   - Non-standard build/typecheck commands
   - Anything truly relevant to every single task

3. **Group the rest**: Organize remaining instructions into logical categories
   (e.g., TypeScript conventions, testing patterns, API design, Git workflow).

4. **Create the file structure**: Output:
   - A minimal root AGENTS.md with markdown links to the separate files
   - Each separate file with its relevant instructions
   - A suggested docs/ folder structure

5. **Flag for deletion**: Identify any instructions that are:
   - Redundant (the agent already knows this)
   - Too vague to be actionable
   - Overly obvious (like "write clean code")

段階的開示ファイルの作成

推奨する構成：

docs/
├── QUALITY.md          # Cross-cutting code quality expectations
├── TYPESCRIPT.md       # TypeScript patterns and conventions
├── TESTING.md          # Testing strategies and frameworks
├── FRONTEND.md         # Component architecture, reuse, error boundaries
├── API_CONVENTIONS.md  # API design patterns (if applicable)
├── ARCHITECTURE.md     # High-level architecture (capabilities, not file paths)
└── Git workflow items → CONTRIBUTING.md

各ファイルの要件：

• 1 つの領域に焦点を当てる
• 関連ファイルへのリンクを設け、移動しやすくする
• 規定ではなく原則を説明する
• 役立つ場合は例を含める

よくある問題と解決策

問題	解決策
エージェントが誤ったパッケージマネージャーを使う	「このプロジェクトでは pnpm を使用します」と明示する
エージェントが誤ったコマンドを生成する	標準以外のビルド／テストコマンドを列挙する
ファイルが大きくなりすぎる	段階的開示を適用し、領域ごとのルールを別ファイルに移す
指示が矛盾している	矛盾がないか確認し、解決する
エージェントが誤った場所を参照する	ファイルパスではなく、できることを説明する
慣習が時間とともに混在する	AGENTS.md を継続的に更新するドキュメントとして扱い、定期的に見直す

AGENTS.md と CLAUDE.md

Claude Code は AGENTS.md ではなく CLAUDE.md を使用します。互換性を維持するには：

# Create a symlink from AGENTS.md to CLAUDE.md
ln -s AGENTS.md CLAUDE.md

どちらのファイルも同じ目的を持ち、リポジトリ内で AI コーディングエージェントがどのように動作するかをカスタマイズします。

AGENTS.md をサポートするツール

AGENTS.md は、多くのツールでサポートされているオープンスタンダードです。

• OpenAI Codex、Jules（Google）、Factory、Aider、goose、opencode
• VS Code、Devin（Cognition）、Cursor、RooCode、Gemini CLI
• GitHub Copilot coding agent、Windsurf（Cognition）など

一覧は https://agents.md/ をご覧ください。

アプローチ

1. 最小限から始める：まずは必要不可欠な情報だけを記載します
2. 段階的に開示する：ドメイン固有のルールは別ファイルに移します
3. ファイルパスを避ける：構成ではなく、機能について説明します
4. 会話調にする：厳格な命令ではなく、自然な言葉を使います
5. 定期的に見直す：常に更新されるドキュメントとして扱います
6. 入れ子のファイルを使う：モノレポでは、サブディレクトリに AGENTS.md を配置します
7. 重複を避けてリンクする：繰り返す代わりに、他のリソースを参照します

段階的な開示

特定のトピックを詳しく見る：

• 検証チェックリスト：VERIFICATION.md
• リファクタリングガイド：REFACTORING.md
• テンプレートギャラリー：TEMPLATES.md
• モノレポのパターン：MONOREPO.md
• よくあるアンチパターン：ANTI_PATTERNS.md