Зачем проектам файл для нейросетей, которые не умеют читать мысли

Пару лет назад я мог открыть любой чужой репозиторий и за полчаса понять, что там происходит. Структура папок, точка входа, пара классов, README по диагонали - и уже есть картинка в голове.

Сейчас в проект приходит не только новый разработчик. В него заходит нейросеть, которая умеет лазать по файлам, выцеплять зависимости и предлагать правки. Она может выполнить цепочку задач, которую я бы сам делал полдня.

И у нее есть одна большая проблема.

Она не знает моих правил.

Модель видит код, видит, как всё устроено на верхнем уровне. Но она не восстановит, почему я вынес логику в сервисный слой, а не засунул в контроллер. Не поймет, почему этот файл лучше не трогать. И не догадается, что перед тем как мутить миграции, нужно проверить, не сломается ли что-нибудь в продакшене.

Для нас, людей, эти вещи очевидны. У нас есть контекст, бэкграунд, мы помним обсуждения в чатах и баги, на которых обожглись.

AI всего этого лишен. Он угадывает. И часто ошибается.

Тут и появляется AGENTS.md.

Файл в корне репозитория, в котором команда один раз записывает внутренние договоренности. Не для людей - для машин.

Выглядит примерно так:

# Project rules

Laravel 13 / PHP 8.5

Architecture:
- Бизнес-логика - в app/Services.
- Контроллеры - тонкие. Исключения - по согласованию.
- Запросы к внешним API - не в контроллеры.

Testing:
- Перед тем как закончить - прогнать тесты.
- Перед коммитом - Laravel Pint.

Restrictions:
- Сгенерированные файлы не трогать без явного ОК.
- Миграции не переписывать без одобрения.

Коротко. Без воды. Только ограничения, в которых AI должен принимать решения.

Первые AI-помощники были проще. Ты пишешь «сделай функцию сортировки», получаешь код, проверяешь, правишь - и дальше. Тогда не нужен был контекст.

Сейчас Cursor, Claude Code или Codex заходят в проект глубже: переключаются между файлами, ищут зависимости, делают несколько шагов вперед.

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

Я видел это своими глазами: в Laravel-проекте AI засунул бизнес-логику в контроллер. Тесты проходили. Код работал. Но через пару месяцев команда получила кашу, которую никто не хотел поддерживать.

Для разработчика это очевидная архитектурная ошибка. Для модели - один из допустимых вариантов.

READМЕ для этого не подходит.

Он писался для людей: что за проект, как установить, где основная информация. Для AI этого мало.

Ему важно не только что делает приложение. А как с ним принято работать.

Где лежит бизнес-логика? Какие файлы неприкосновенны? Какие команды запускать перед тем, как сказать «всё готово»?

Обычно это знание сидит в головах старших разработчиков. Новичок впитывает его через обсуждения, код-ревью и собственные грабли.

AI не может пройти этот путь. Ему нужны четкие правила с самого начала.

У этого подхода есть неожиданный побочный эффект.

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

AGENTS.md становится не просто инструкцией. Он вскрывает проблемы, которые мы перестали замечать.

Разумеется, он не решит всё.

Даже с идеальным файлом AI может неправильно понять задачу, предложить неудачное решение или просто игнорировать правила. Поэтому инструкции не пишутся один раз и навсегда. Если меняется архитектура, меняется и файл. Он становится частью проекта - как тесты или документация.

Знаете, это напоминает мне историю с .editorconfig.

Когда он только появился, многие не понимали: зачем отдельный файл для настроек редактора? Разработчик сам выберет стиль, пробелы или табы. Но чем больше становилась команда, тем важнее оказывались единые правила.

Только теперь речь не о пробелах. Речь о том, как AI должен думать внутри твоего проекта.

Сегодня это маленький текстовый файл в корне репозитория. Я ставлю на то, что через пару лет он станет обязательной частью любого серьезного проекта.

Программирование меняется. Раньше мы писали инструкции только для людей. Теперь появился новый читатель - AI.

И возможно, мы скоро будем оценивать проекты не только по коду и тестам. А по тому, насколько хорошо они умеют объяснять свои внутренние правила тем, кто с ними работает.