---
title: "AGENTS.mdは何をどう書かれているか｜OSS 25リポジトリ横断調査"
excerpt: "主要OSS 25リポジトリのAI向け設定ファイルを横断調査しました。採用率はノーコード系6/10、大手系14/15。CLAUDE.mdが「AGENTS.mdへの薄いリダイレクト」に収束する動きや、失敗ログを動的に蓄積する思想、AI生成PRのレッドフラグリストという逆方向の記述までをまとめています。"
author: "AI活編集部"
author_username: ai-katsu-editorial
published_at: 2026-05-04T00:00:00+00:00
verified_at: 2026-05-04T00:00:00+00:00
models: ["Claude Code", "OpenAI Codex"]
tools: ["GitHub"]
tasks: ["開発・エンジニアリング", "ツール検証"]
canonical_url: https://ai-katsu.jp/articles/agents-md-research-overview
---
# AGENTS.mdは何をどう書かれているか｜OSS 25リポジトリ横断調査

「AGENTS.md ベストプラクティス」として流通しているテンプレートは、どれも似た内容です。しかし**実際のプロダクトのリポジトリを開くと、テンプレートには載っていない工夫が入っています。**

この調査では、**主要OSS 25リポジトリを横断**し、公式ドキュメントには載らないが実コードベースでは採用されている設計を抽出しました。

## この調査の概要

| 項目 | 内容 |
| --- | --- |
| 調査日 | 2026年5月4日 |
| 調査対象 | **主要OSS 25リポジトリ**（ノーコード/ローコード/自動化系10 + 大手プロダクト15） |
| 目的 | 汎用テンプレートを超えて、**実プロダクトで採用されている応用・差別化された設計観点**を抽出する |
| 構成 | 本記事（全体像）＋深掘り3本 |

## 結論：採用率にはっきり差が出た

**ノーコード系 6/10、大手系 14/15。AIネイティブ製品ほど深い実装を持つ傾向**が確認できました。

「AI向け設定ファイルを置いているか」だけでなく、**どこまで作り込んでいるかに大きな幅があります。**1行のリダイレクトだけのものから、独自のプラグインマーケットプレイスを構築しているものまで存在します。

## トレンド①：AGENTS.md が事実上の業界標準に収束

**OpenAI Codex起源で、現在はLinux Foundation配下のAgentic AI Foundationが管理する規格**です。

複数のAIエージェントが共通で参照する**中立フォーマット**として浮上しました。特定のツールに紐づかない点が、標準化を後押ししています。

## トレンド②：CLAUDE.md は「薄いリダイレクト」に収束

これが最も実務的な発見です。

複数のリポジトリで、**CLAUDE.md が極端に小さいファイルになっています。**

-   あるリポジトリの `.claude/CLAUDE.md` は**「See agents.md in the repository root」の1行**
-   別のリポジトリのCLAUDE.mdは**280バイト**
-   **9バイトのファイル**を置いているものもある

**メンテナンスコストをAGENTS.mdに集約する戦略**です。同じ内容を2つのファイルで維持すると、必ずズレます。

**ツールごとにファイルを用意する必要があっても、実体は1つに寄せる**——これは自社で運用する際にもそのまま使える判断です。

## トレンド③：`.agents/` ディレクトリの出現

`.claude/` や `.cursor/` に加えて、**`.agents/` を設置するリポジトリが現れています。**

あるリポジトリでは `.agents/features/` に**46件**のファイル、加えて `.agents/rules/` と `.agents/skills/` を配置しています。

**ツール非依存の汎用エージェント設定の標準化が始まっている**という動きです。

## トレンド④：ignoreファイルの多元化

**`.claudeignore` / `.agentignore` / `.cursorignore` を並列管理**しているリポジトリがあります。

**エージェント別に除外設定を分離する運用**です。ツールによって読ませたくない範囲が違う、という実態を反映しています。

## トレンド⑤：失敗ログの動的蓄積

設計思想として最も注目すべき変化です。

**静的なベストプラクティスではなく、経験則ライブラリとして運用する**という考え方が広がっています。

-   あるリポジトリは `.cursor/lessons.md` に**ユーザーが訂正するたびに記録**
-   別のリポジトリは `.clinerules/` に**手動介入が必要だった時に書く**

**「いつ書くか」のポリシーが決まっている**点が重要です。漫然と追記するのではなく、トリガーが定義されています。

## トレンド⑥：AI生成コードへの防衛的記述

逆説的な動きです。

あるリポジトリのコードレビュー用インストラクションには、**「AI生成PRのレッドフラグリスト」**が含まれています。

-   fabricated diffs（実在しない差分）
-   unrelated file changes（無関係なファイル変更）
-   empty descriptions（空の説明）

**エージェント向けのガイドが、エージェントの産物を人間がレビューするための指針も兼ねるという二重構造**になっています。

AIに書かせることと、AIが書いたものを疑うことが、同じファイルに同居しています。

## 採用ファイルの分布

調査では、リポジトリごとにどの種別のファイルを採用しているかをマトリクスで整理しました。

| ファイル種別 | 位置づけ |
| --- | --- |
| **AGENTS.md** | 中立フォーマット。階層構造を持つケースも |
| **CLAUDE.md** | 薄いリダイレクトに収束する傾向 |
| `.claude/` | プラグイン・hooks等の実装 |
| `.cursor/` | rules・lessons |
| copilot-instructions | レビュー特化で使われるケースあり |
| **独自ディレクトリ** | `.agents/`、`microagents/`、`ai_policy.md` など |

## 深掘り3本の内容

| 記事 | 扱う内容 |
| --- | --- |
| **プラグインアーキテクチャ** | 独自プラグインマーケットプレイスの構築、14スキルの分類、エージェント役割分離、フックによるテレメトリ送信 |
| **失敗ログ蓄積パターン** | 「いつ書くか」のポリシー、セルフインプルーブメントループ、tribal knowledgeの動的蓄積 |
| **セキュリティ・境界設計** | アーキテクチャ境界、エディション境界、SSRF対策、物理ブロック、AI自律性のガバナンス |

## この調査の使い方

自社でAIエージェント向けの設定を整備する際、次の順で参考にできます。

1.  **まずAGENTS.mdに集約する**——ツール別ファイルは薄いリダイレクトで済ませる
2.  **「いつ書くか」のトリガーを決める**——訂正されたとき、手動介入が必要だったとき
3.  **踏み越えてはいけない境界を明示する**——AIは最短経路を取ろうとする
4.  **AI生成物をレビューする側の指針も同じ場所に書く**

## よくある質問

### AGENTS.md と CLAUDE.md はどちらを書くべきですか？

**AGENTS.mdに集約し、CLAUDE.mdは薄いリダイレクトにするのが観測されたトレンドです。**実際に「See agents.md in the repository root」の1行だけ、あるいは数百バイトのファイルを置くリポジトリが複数あります。

### なぜ `.agents/` ディレクトリが増えているのですか？

**ツール非依存の汎用エージェント設定を標準化する動きです。**`.claude/` や `.cursor/` といったツール固有ディレクトリとは別に設置されています。

### 設定ファイルは書いたら終わりですか？

**動的に蓄積する運用が広がっています。**ユーザーが訂正したとき、手動介入が必要だったときに追記する——というトリガーを決めて運用するパターンが観測されました。

## まとめ

-   採用率は**ノーコード系6/10、大手系14/15**。AIネイティブ製品ほど実装が深い
-   **AGENTS.md が中立フォーマットとして業界標準に収束**
-   **CLAUDE.md は薄いリダイレクトに収束。**メンテコストを1箇所に集約する戦略
-   **`.agents/` の出現**——ツール非依存の設定標準化が始まっている
-   **ignoreファイルの多元化**——エージェント別に除外範囲を分ける運用
-   **失敗ログを動的に蓄積する思想**が広がっている。「いつ書くか」のトリガーが鍵
-   **AI生成PRのレッドフラグリスト**という逆方向の記述も登場している

設定ファイルの書き方は、テンプレートより実プロダクトの運用に学ぶほうが得るものが多くなります。何を書くかより、どう更新し続けるかに差が出ています。

株式会社AI棒では、こうしたAI活用の検証を日々行い、企業の開発体制へのAI導入を支援しています。ご相談は[お問い合わせフォーム](/contact)から、継続的な伴走支援については[AI参謀](/ai-sanbo)をご覧ください。