モノレポ環境でAGENTS.md / CLAUDE.mdを階層化してうまく読み込ませる方法

はじめに

こんにちは、スケールアーキテクトチームです！

最近、Claude CodeやCursorをはじめとしたAIコーディングツールや、自律型AIエージェントを開発に導入しているチームも多いと思われます。

これらのツールでは、プロジェクトのルートディレクトリに AGENTS.md、CLAUDE.md などの設定ファイルを置くことで、 AIにプロジェクト固有のコーディング規約やコンテキストを理解させることができます。

しかし、複数のアプリやパッケージが同居するモノレポ構成の場合、

「フロントエンドとバックエンドでルールが違う」
「特定のパッケージ専用のルールを適用したい」

といったケースで、これらのファイルの管理方法や優先順位が問題になりがちです。

今回は、モノレポ環境において複数の AGENTS.mdを配置し、AIに意図した通りにルールを読み込ませるための工夫についてご紹介します。

はじめに
モノレポ環境におけるAGENTS.mdの課題
AGENTS.mdに階層を定義しておく
具体的なファイル構成と記述例
- 1. ルートディレクトリの AGENTS.md（全体ルール）
- 2. サブディレクトリの AGENTS.md（個別ルール）
まとめ

モノレポ環境における`AGENTS.md`の課題

以下のようなディレクトリ構成のモノレポ環境を例にします。

my-monorepo/
 ├─ apps/
 │   ├─ app-1/  (TypeScript)
 │   └─ app-2/  (TypeScript)
 ├─ packages/
 │   └─ package-1/  (共通UIコンポーネント)
 └─ AGENTS.md

このとき、ルートディレクトリにのみ AGENTS.md を置くとファイルが肥大化し、コンテキストが混ざってAIの精度が落ちてしまいます。

一方で、各サブディレクトリ（apps/app-1など）にそれぞれ AGENTS.md を配置するだけだとコーディングエージェントによって、

ルートの共通ルール（規約や全体指針など）が無視されてしまう
AIがどのファイルを読み込むべきか迷う（または一部しか読まない）

という差異が発生することがありました。

`AGENTS.md`に階層を定義しておく

この問題を解決するためには、「全体ルール」と「個別ルール」の階層構造をAIに明示的に伝える必要があります。

具体的なアプローチは以下の通りです。

ルートディレクトリ：リポジトリ全体に適用される共通の指示（Gitルール、PR作成ルール、全体の技術スタック概要など）を記載した AGENTS.md を配置する。
サブディレクトリ：アプリやライブラリ単位の固有ルールを記載した AGENTS.md を配置し、「まずルートのAGENTS.mdを読み込み、競合する場合はこちらのルールを優先する」という指示を明記する。

これにより、オブジェクト指向の「継承とオーバーライド」のような振る舞いをAIに期待することができます。

具体的なファイル構成と記述例

それでは、実際にどのように記述すればAIがうまく解釈してくれるのか、具体的な記載例を見ていきましょう。

1. ルートディレクトリの `AGENTS.md`（全体ルール）

ルートのファイルには、リポジトリ全体で守るべきルールを記述します。

また、サブディレクトリに個別のルールが存在することをAIに認識させる一文を入れておくのがポイントです。

# 開発ガイドライン (ルート)

あなたは優秀なシニアエンジニアです。このリポジトリはモノレポ構成で管理されています。
作業を開始する前に、以下の共通ルールを必ず確認してください。

## モノレポの構造とルールの探索
- 作業対象のディレクトリ（例: `apps/app-1`）に独自の `AGENTS.md` や `CLAUDE.md` が存在する場合は、**必ずそちらも読み込んでください**。
- サブディレクトリのルールが本ファイルのルールと競合する場合は、**サブディレクトリのルールを優先**してください。

## コード生成のルール
- 新規に作成する TypeScript の関数名は `snake_case` を使用してください。

2. サブディレクトリの `AGENTS.md`（個別ルール）

次に、サブディレクトリ（apps/app-1）のディレクトリに配置する AGENTS.md の例です。冒頭でルートのルールを参照しつつ、自身のルールを優先させるように指示します。

# 開発ガイドライン (apps/app-1)

ここは `apps/app-1` のディレクトリです。
以下のルールに従ってコードの生成・修正を行ってください。

## ルールの優先順位（重要）
- まず、リポジトリのルートディレクトリにある `AGENTS.md` を読み込み、全体のルールを把握してください。
- その後、このファイルのルールを適用します。**ルートのルールと本ファイルのルールが競合した場合は、いかなる場合でもこのファイルのルールを優先**してください。

## コード生成のルール
- 新規に作成する TypeScript の関数名は `camelCase` を使用してください。