Монорепозиторий с десятком пакетов — фронтенд на Next.js, бэкенд на FastAPI, общая библиотека утилит — и вопрос, как объяснить AI-агенту специфику каждого пакета, не заставляя его каждый раз перечитывать одну гигантскую простыню инструкций с общими и частными правилами вперемешку.
Принцип nearest-file-wins
Спецификация AGENTS.md поддерживает несколько файлов внутри одного репозитория. Правило простое на словах: агент ищет ближайший к редактируемому файлу AGENTS.md, поднимаясь по дереву директорий от файла к корню, и использует первый найденный.
repo/
├── AGENTS.md (общие правила)
├── packages/
│ ├── frontend/
│ │ ├── AGENTS.md (специфика Next.js)
│ │ └── src/components/Button.tsx
│ └── backend/
│ └── api/
│ ├── AGENTS.md (специфика FastAPI)
│ └── routes/users.pyДля packages/frontend/src/components/Button.tsx применится packages/frontend/AGENTS.md, потому что это ближайший файл вверх по дереву. Для packages/backend/api/routes/users.py — соответственно packages/backend/api/AGENTS.md.
Замена, а не автоматическое слияние
Ключевая деталь, которая ловит многих: базовая спецификация построена вокруг замены, а не наследования. Найденный ближайший AGENTS.md применяется целиком сам по себе, корневой файл при этом не подмешивается автоматически. Если в пакете frontend нужны и общие правила проекта, и специфика Next.js, их стоит либо продублировать явно, либо сослаться на корневой файл текстом внутри пакетного.
| Сценарий | Что произойдёт |
|---|---|
| AGENTS.md есть только в корне | Применяется он для любого файла в репозитории |
| AGENTS.md есть в корне и в пакете | Для файлов внутри пакета применяется файл пакета, корневой игнорируется |
| AGENTS.md нет ни на одном уровне | Агент работает без специфичного контекста проекта |
Практический паттерн для монорепозитория
Разумное разделение: в корневой AGENTS.md — то, что действительно общее для всех пакетов (конвенции коммитов, общие команды тестирования верхнего уровня, границы дозволенного). В AGENTS.md конкретного пакета — только то, что специфично именно ему (особенности сборки фронтенда, конкретные команды миграций бэкенда), а не повторение общих правил.
Как проверить расстановку файлов, не гадая
В репозитории с десятком пакетов и разной глубиной вложенности предсказать на глаз, какой AGENTS.md реально применится для конкретного пути, не всегда очевидно. AGENTS.md Nearest-File-Wins Resolver принимает список расположений всех AGENTS.md и целевой путь, и явно показывает, какой файл победит.
Итоговый чеклист
Nearest-file-wins ищет ближайший AGENTS.md вверх по дереву директорий от редактируемого файла к корню репозитория.
Базовая спецификация — это замена, а не автоматическое наследование: найденный файл применяется целиком сам по себе, без подмешивания родительских уровней.
В корневой файл стоит выносить действительно общие правила, а специфику конкретного пакета — в его собственный AGENTS.md, чтобы избежать дублирования и расхождения со временем.