AGENTS.md: инструкции для ИИ-агентов переезжают в репозиторий

Что изменилось

Год назад работа с ИИ-помощником по коду выглядела так: открыл чат, объяснил, какой у тебя фреймворк, какие соглашения, что нельзя трогать, и только потом попросил что-то сделать. На следующий день — то же самое с начала.

Теперь эти объяснения лежат в файле в корне репозитория. Агент читает его при старте и работает с учётом правил проекта. Файл называется по-разному — AGENTS.md, CLAUDE.md, .cursorrules, — но идея одна: контекст для машины хранится вместе с кодом и версионируется вместе с ним.

Что туда пишут

Обычный файл выглядит как памятка для нового разработчика, только без вежливости:

# Проект
Phoenix 1.8, LiveView, Tailwind 4, Postgres.

# Правила
- Перед коммитом запускай `mix precommit`.
- Для HTTP используй Req, не HTTPoison.
- Шаблоны только HEEx, никаких inline-скриптов.
- Не добавляй зависимости без причины.

# Тесты
- `mix test path/to/file.exs` для одного файла.
- Не используй Process.sleep в тестах.

Команды сборки и тестов, соглашения об именовании, запрещённые библиотеки, структура каталогов, чего не делать. Всё, что старший разработчик говорит джуну в первую неделю.

Почему это работает

Агент не помнит прошлых сессий, поэтому каждый раз ему нужен контекст. Файл в репозитории — самый дешёвый способ его дать: он всегда актуален, попадает в ревью вместе с кодом и одинаков для всех членов команды и всех инструментов.

Побочный эффект — такой файл полезен и людям. Он вынуждает записать то, что раньше жило в головах и чатах. Многие команды замечают, что онбординг новых сотрудников стал проще, потому что «правила для агента» — это и есть документация, которую никто не хотел писать.

Соглашения складываются

Вокруг файла появляется экосистема. Генераторы фреймворков кладут его в новый проект по умолчанию. Инструменты читают вложенные файлы в подкаталогах, чтобы у монорепозитория были свои правила для каждого пакета. Рядом появляются «навыки» — отдельные инструкции для типовых задач, которые агент подгружает по требованию.

Название пока не устоялось. AGENTS.md претендует на роль нейтрального стандарта, который понимают разные инструменты, но каждый вендор держит и своё имя файла.

Чего не стоит делать

Не превращайте файл в свалку. Тысяча строк правил работает хуже, чем пятьдесят: агент, как и человек, теряет главное в шуме. Не дублируйте то, что уже видно из кода. Не пишите противоречивых требований — их заметит только тот, кто нарушит одно из них.

Итог

Инструкции для агентов повторяют путь конфигов линтеров и форматтеров: сначала настройки жили у каждого на машине, потом переехали в репозиторий, и стало возможно договориться. Файл в корне — маленькая вещь, но она меняет отношение к ИИ-помощнику: из собеседника он становится частью проекта.