AGENTS.md — текстовый файл с правилами и сведениями о проекте, которые ИИ-агенту нужно учитывать при работе с кодом. Он помогает объяснить назначение сайта, структуру папок, команды для проверки и ограничения, которые нельзя нарушать. Ниже — практический способ подготовить такой файл, поддерживать его в актуальном состоянии и проверять, что агент действительно следует инструкциям. Это пригодится, если вы создаёте сайт с помощью вайбкодинга и возвращаетесь к проекту после перерывов.
Что записать в AGENTS.md для сайта
Начните с информации, без которой агент рискует неверно понять задачу. Коротко опишите, для чего нужен сайт, кто им пользуется и какие основные функции уже работают. Например: посетитель выбирает услугу, оставляет заявку, а владелец сайта получает её в панели управления. Пишите о фактическом проекте, а не о планах на будущее.
Затем опишите устройство кодовой базы. Назовите папки с интерфейсом, серверной частью и тестами, если они есть. Добавьте команды, которыми проект запускают, проверяют и собирают. Если команды отличаются для локальной разработки и публикации, подпишите каждую отдельно. Агенту легче выполнить конкретную инструкцию, чем угадывать назначение файлов по названиям.
- Назначение: что делает сайт и какие сценарии для него основные.
- Структура: где находятся страницы, общие компоненты, стили и тесты.
- Команды: как запустить проект и выполнить доступные проверки.
- Правила изменений: какие части нельзя переписывать без отдельного согласования.
- Готовность задачи: что проверить перед тем, как считать работу завершённой.
Ограничения формулируйте прямо: например, «не меняй адреса существующих страниц без отдельной просьбы» или «сохраняй текущий формат данных». Такая запись помогает агенту не трактовать важную особенность сайта как случайную деталь.
Как написать инструкции, которые агент сможет выполнить
Каждое правило должно отвечать на вопрос «что сделать?». Фраза «проект нужно поддерживать в хорошем состоянии» не задаёт действия. Лучше написать: «после изменения страницы запусти команду проверки, указанную ниже» и привести саму команду. Если нужной проверки пока нет, не придумывайте её: укажите, что автоматическая проверка отсутствует, и перечислите ручные действия.
Разделяйте постоянные правила и сведения о текущей задаче. В AGENTS.md уместны структура проекта, способы проверки и устойчивые ограничения. Временную просьбу вроде «измени текст на главной странице к пятнице» лучше передать агенту вместе с конкретной задачей: при следующем обращении она уже может потерять актуальность.
Добавьте короткий порядок работы: сначала изучить связанные файлы, затем внести ограниченное изменение, после этого выполнить проверку и сообщить, что именно проверено. Если агент должен сохранить существующий визуальный стиль или не затрагивать определённую функцию, запишите это рядом с инструкциями по соответствующей части проекта.
Как поддерживать файл в актуальном состоянии
AGENTS.md полезен только тогда, когда описывает нынешнее состояние проекта. После смены команды запуска, переезда папок или добавления тестов обновите соответствующий пункт. Устаревшая инструкция хуже отсутствующей: агент может уверенно следовать ей и тратить время на команду, которой уже нет.
Проверяйте файл при заметных изменениях проекта и перед задачей, которая затрагивает описанные в нём правила. Попросите агента сначала перечислить, какие инструкции относятся к запросу, а затем кратко объяснить план. Если он пропускает важное правило, уточните формулировку в файле и повторите задачу на небольшом изменении.
Ведите AGENTS.md как часть проекта: храните рядом с кодом и включайте в обычный просмотр изменений. Тогда владелец сайта увидит, когда агент или разработчик меняет правило. Не превращайте файл в журнал: удаляйте инструкции о давно завершённых экспериментах и оставляйте только то, что влияет на будущую работу.
Какие ошибки мешают AGENTS.md работать
- Слишком общие пожелания. «Делай качественно» не объясняет, что проверить. Назовите конкретную команду или сценарий.
- Инструкции противоречат друг другу. Если в одном месте запрещено менять интерфейс, а в другом предписана его переработка, укажите, какое правило важнее.
- Файл описывает желаемое, а не существующее. Сверьте названия папок и команды с проектом перед тем, как поручать агенту задачу.
- В AGENTS.md попадает всё подряд. Длинный список заметок затрудняет поиск нужного правила. Оставьте сведения, которые агенту действительно нужны.
- Результат считают проверенным без запуска тестов. Попросите агента назвать выполненные проверки и отдельно указать, что он проверить не смог.
Инструкции помогают агенту работать в заданных рамках, но сами по себе не подтверждают безопасность или качество готового сайта. Для отдельной проверки изменений пригодится чек-лист security review вайбкодинг-проекта: он помогает рассмотреть результат с точки зрения рисков, которые AGENTS.md может не охватывать.
Чтобы начать, создайте в корне проекта небольшой AGENTS.md: опишите назначение сайта, назовите важные папки и укажите реальные команды проверки. Затем попросите агента пересказать применимые правила и выполните с ним небольшую задачу. После этого поправьте только те инструкции, которые оказались непонятными или устаревшими.
