スターの多いOSSは、どのようなAGENTS.mdを記述しているのか調べてみました

はじめに

この記事は、freee Developers Advent Calendar 2025 の 13日目の記事です。
今回は freee支出管理を開発しているシバタがAGENTS.md(CLAUDE.md)に関しての記事を書きます。

弊社でも各々の開発しているサービスのリポジトリでCLAUDE.mdやAGENTS.mdを書いてます。
担当しているプロダクトを開発する際、Agentに事前に知ってほしい内容をどこまで書くべきか私自身悩むことがあり、一度会社のコンテキストから離れ、OSSではどのような内容が書かれているのか調査してみました。

調査結果

スターが多く、日頃開発者がお世話になっているだろうOSSにはCLAUDE.md や AGENTS.mdはありませんでした。以下、調べてみたOSSです。

名前	GitHub URL
React	https://github.com/facebook/react
Vue.js	https://github.com/vuejs/core
TensorFlow	https://github.com/tensorflow/tensorflow
Next.js	https://github.com/vercel/next.js
Go	https://github.com/golang/go
TypeScript	https://github.com/microsoft/TypeScript
Ruby on Rails	https://github.com/rails/rails

上記OSSの他に目視で確認してみても、CLAUDE.mdや AGENTS.mdが用意されているのは現状少なかったです。数少ない中でも以下のOSSはAGENTS.mdがありました。

名前	GitHub URL	AGENTS.md
Sentry	https://github.com/getsentry/sentry	バックエンド / フロントエンド
Apache Airflow	https://github.com/apache/airflow	バックエンド
Temporal	https://github.com/temporalio/temporal	バックエンド

以上のOSSの中でも、比較しやすそうなSentryとTemporalで見ていきたいと思います。前提として、Sentryはエラー監視・パフォーマンス監視ツール、Temporalは分散アプリケーション向けのワークフローエンジンで、技術スタックも異なります(SentryはPython/TypeScript、TemporalはGo)。

記述量

Sentryの場合、バックエンドは約800行、容量26KBの比較的巨大な内容でした。static配下には18KB規模のフロントエンドのファイルも別でAGENTS.mdがありました。対して、TemporalはGo・バックエンドのプロジェクトとして、100行前後の比較的コンパクトな分量でまとまってました。

プロジェクトの規模にもよりますが、最近読んだ How I Use Every Claude Code Feature から引用すると、

For my professional work, our monorepo’s CLAUDE.md is strictly maintained and currently sits at 13KB (I could easily see it growing to 25KB).

とあるので、行数が全てではないですが、比較的育ったプロダクトだと書いても数百行が適当なのではないかと思います。このことから、千行に到達すると、事前に与えるコンテキストとしては重いと言えるのではないかと考えました。別の記事である Writing a good CLAUDE.mdでも CLAUDE.md に書く分量は少ないほうがいいという意見があり、ここでも60-300行あたりが良さそうと言及されてます。
使用するAgentにもよりますが、もしClaude Codeをメインで使うプロジェクトの場合、数百行程度に抑えるのが良さそうです。

内容

Sentry

技術スタックや使用ミドルウェアまで細かく書いています。ここをどこまで書くかはチームや規模によって意見は分かれてきそうです。
API開発のユースケースにおける意思決定のガイドラインが書かれており参考になりました。もしClaude Codeを使った開発がメインのチームの場合はカスタムスラッシュコマンドに移せそうでした。
コメントの仕方はコードと同じ内容を書くなという指標が書かれており、これは冗長なAgentがコメント置いてくる対策に使えそうでした。
共通設定は色々書かれていますが、Agentからの出力内容に問題があれば適宜追加で良さそうでした。
データベースの守ってほしいガイドラインはデータベースに関わるプロジェクト、Pythonの記述のアンチパターン・セキュアコーディングはPythonのプロジェクトに使えそうな記述だと思いました。

Sentryは基本的なリポジトリの情報・守ってほしい・絶対にやってはいけないことを例を踏まえて詳細に書かれており、手厚いリファレンス的な印象を受けました。全部入りの指示をどこまでAgentが守った上で実装してくれるかは気になりました。

Temporal

You are an experienced developer working on the temporal project. Your task is to fix a bug or implement a new feature while adhering to the project's best practices and development guidelines. Your background is in distributed systems, database engines, and scalable platforms. Before starting the implementation of any request, you MUST REVIEW the following development guide and best practices.

というロールプロンプティングから始まり、開発ガイド・ベストプラクティスをまず読ませる構成になっていました。
Sentryと比較してシンプルな指示で、構造的にも優先度が高いもの(前提 => 絶対守ってほしい命令 => 開発ガイド => 実際のユースケース)順に書かれているようでした。

Development Guide の構成は開発中に項目を足したくなってきたら参考にできそうでした。

まとめ

Sentry: 詳細・網羅的なリファレンス型
Temporal: シンプル・構造化された指示型

という印象を受けました。 Claude Codeを使用する場合、トークン制限やAgentの指示の無視・希薄化を防ぐ観点から、/initで出てくる内容をそのまま使ったり、最初からすべてを網羅的に書くというよりは、開発の中で毎回指摘が必要となる部分を少しずつ追加していく運用が有効だと考えられます。
また、分量が多くなったときは各ディレクトリ配下にも配置できるので、必要に応じて分割していきたいです。