Еще совсем недавно разработчики открывали чат с искусственным интеллектом, вставляли фрагмент кода и просили исправить ошибку, объяснить работу функции или написать новый модуль. AI выступал в роли помощника, который видел лишь небольшой кусок проекта и отвечал на конкретный вопрос. Сегодня ситуация изменилась. Современные инструменты вроде Claude Code, OpenAI Codex, Gemini CLI, Cursor, Windsurf и других уже способны самостоятельно исследовать репозиторий, изменять файлы, запускать тесты, искать ошибки и готовить изменения для отправки в систему контроля версий.
Фактически AI постепенно превращается из чат-бота в полноценного участника команды разработки. Однако вместе с новыми возможностями появилась и новая проблема: агент практически ничего не знает о вашем проекте.
Даже самые современные языковые модели не умеют «читать мысли» разработчиков. Они не знают, какую архитектуру вы используете, какие библиотеки считаются стандартом, какие решения запрещены внутри команды, как правильно запускать проект, какие тесты являются обязательными и каким должен быть стиль оформления кода.
Если подобных инструкций нет, агент начинает делать предположения. Он анализирует структуру каталогов, пытается угадать используемый стек технологий, ищет похожие примеры в интернете и самостоятельно принимает решения. Иногда это работает достаточно хорошо, но чем сложнее проект, тем выше вероятность ошибок.
Типичная ситуация выглядит знакомо многим разработчикам. AI предлагает библиотеку, которую в компании давно запретили использовать. Меняет архитектуру вместо локального исправления ошибки. Создает новый сервис там, где принято расширять существующий. Исправляет код, но забывает запустить тесты. Форматирует проект инструментом, отличным от принятого в команде. Или автоматически выполняет commit, хотя это запрещено внутренними правилами.
Подобные ошибки нельзя назвать недостатками самой модели. Чаще всего агент действует логично, но принимает решения на основе неполной информации. Для него каждый новый репозиторий — неизвестная территория, правила которой приходится угадывать.
Именно поэтому в последние два года разработчики начали создавать отдельный документ, содержащий инструкции не для людей, а специально для искусственного интеллекта. Так появился файл AGENTS.md.
По своей идее он напоминает привычный README.md, однако предназначен совершенно для другой аудитории. README объясняет человеку, что представляет собой проект, как его установить и использовать. AGENTS.md описывает, как должен работать AI-агент внутри этого проекта.
В таком документе можно указать архитектурные ограничения, правила изменения кода, обязательные проверки перед завершением работы, используемые инструменты, команды сборки, запуск тестов, требования к оформлению изменений и любые другие инструкции, которые помогут агенту принимать правильные решения без постоянных уточнений.
Можно сказать, что AGENTS.md становится своеобразной должностной инструкцией для цифрового сотрудника. Вместо того чтобы каждый раз писать длинный промпт в чате, разработчик один раз формулирует правила проекта, а затем любой совместимый AI-агент начинает работать, опираясь именно на них.
Появление подобных файлов уже нельзя назвать экспериментом отдельных энтузиастов. Осенью 2026 года было проведено исследование более трех тысяч популярных репозиториев GitHub. Оно показало, что файл AGENTS.md уже встречается почти в каждом пятом проекте, а его распространенность продолжает быстро расти. При этом многие проекты, ранее использовавшие специализированный CLAUDE.md, переходят именно на универсальный формат AGENTS.md, который не привязан к конкретной модели искусственного интеллекта.
Это очень важный сигнал для всей индустрии. Если раньше документация создавалась исключительно для людей, то теперь появляется новый класс документов — документация для AI. Более того, по мере развития автономных агентов именно такие файлы могут стать обязательной частью любого профессионального репозитория, подобно тому как сегодня практически невозможно представить серьезный проект без README.md, .gitignore или лицензии.
Хорошо составленный AGENTS.md приносит пользу не только искусственному интеллекту. Он помогает новым разработчикам быстрее разобраться в устройстве проекта, фиксирует внутренние правила команды и снижает вероятность того, что разные участники будут выполнять одну и ту же задачу по-разному. Получается единый источник знаний, которым одинаково эффективно пользуются и люди, и AI.
Именно поэтому сегодня стоит рассматривать AGENTS.md не как дополнительную возможность, а как новый этап эволюции проектной документации. В ближайшие годы качество этого файла будет напрямую влиять на эффективность работы AI-агентов, а значит — и на скорость разработки программного обеспечения.
Главная ошибка, которую совершают многие разработчики при создании AGENTS.md, — превращают его в копию README.md. Это кажется логичным: если в проекте уже есть документация, достаточно добавить несколько строк про AI. На практике такой подход почти не приносит пользы.
README отвечает на вопрос «что это за проект?». AGENTS.md отвечает на совершенно другой вопрос — «как агент должен работать внутри этого проекта?».
Представьте нового разработчика, который только что пришёл в команду. В первый день ему объясняют не только назначение проекта, но и множество внутренних правил: где лежит код, какие технологии используются, как запускать тесты, что запрещено изменять без согласования, как оформлять commit и pull request. Именно такую информацию должен получать и AI-агент.
Хороший AGENTS.md строится вокруг практических инструкций. Чем меньше агенту приходится делать предположений, тем выше качество его работы.
Первый раздел обычно посвящён краткому описанию проекта. Здесь не нужна длинная история компании или маркетинговое описание продукта. Достаточно нескольких предложений, объясняющих назначение системы, используемый стек технологий и общую архитектуру.
Проект: CRM для маркетплейсов.
Backend: FastAPI.
Frontend: React.
База данных: PostgreSQL.
Векторное хранилище: Qdrant.
Архитектура разделена на независимые сервисы.
Следующий важный раздел — структура проекта. Агент должен понимать, где находятся основные компоненты системы.
/backend
/frontend
/docker
/docs
/tests
/scripts
Если в репозитории десятки каталогов, имеет смысл кратко пояснить назначение каждого из них. Это избавит модель от необходимости самостоятельно анализировать структуру проекта и снизит вероятность ошибок.
После этого необходимо описать правила разработки. Именно здесь AGENTS.md начинает отличаться от обычной документации.
Например:
Использовать только FastAPI.
Не создавать новые сервисы без необходимости.
Предпочитать существующие классы расширению архитектуры.
Не изменять публичный API без явного запроса.
Все эти инструкции напрямую влияют на решения, которые будет принимать AI. Вместо поиска собственного пути агент начинает следовать правилам команды.
Следующий обязательный раздел — команды для запуска проекта. Даже опытная модель не всегда угадывает, используется ли Poetry, uv, npm, pnpm, Docker Compose или собственные скрипты автоматизации.
Запуск Backend
uv sync
uv run uvicorn app.main:app
Запуск Frontend
npm install
npm run dev
После запуска проекта необходимо указать команды проверки качества кода.
Перед завершением работы обязательно выполнить:
pytest
ruff check
ruff format
mypy
Этот раздел считается одним из самых важных. Если агент знает, какие проверки необходимо выполнить, вероятность получения рабочего результата значительно возрастает.
Далее имеет смысл описать соглашения по стилю кода. Причём речь идёт не только о форматировании.
Например:
- использовать type hints;
- не писать функции длиннее 50 строк;
- избегать вложенности более трёх уровней;
- отдавать предпочтение композиции перед наследованием;
- использовать асинхронные функции при работе с сетью.
Подобные требования невозможно автоматически вывести из существующего кода. Если они не описаны, AI будет руководствоваться собственными представлениями о хорошей архитектуре.
Отдельное внимание стоит уделить ограничениям. Это именно те действия, которые агент никогда не должен выполнять самостоятельно.
Не выполнять commit без явного запроса.
Не изменять схему базы данных.
Не удалять тесты.
Не изменять файлы CI/CD.
Не добавлять новые зависимости без объяснения причин.
Такие правила защищают проект даже в случае автономной работы AI. Чем ответственнее задачи выполняет агент, тем важнее заранее определить границы его полномочий.
Последний обязательный элемент — требования к результату работы. Вместо расплывчатой фразы «сделай всё качественно» лучше использовать конкретный чек-лист.
Перед завершением задачи агент обязан:
✓ выполнить тесты;
✓ убедиться, что проект собирается;
✓ проверить форматирование;
✓ убедиться в отсутствии новых предупреждений;
✓ кратко объяснить внесённые изменения.
Такой подход делает работу AI значительно более предсказуемой. Вместо универсальной модели, которая каждый раз принимает решения самостоятельно, вы получаете исполнителя, работающего по единым правилам проекта. Именно в этом и заключается главная задача AGENTS.md — не научить искусственный интеллект программировать, а помочь ему программировать именно так, как принято в вашей команде.
Когда структура документа определена, возникает следующий вопрос: как писать инструкции, чтобы AI действительно им следовал? Здесь действуют совсем другие правила, чем при написании документации для людей.
Разработчики часто используют слишком общие формулировки. Для человека они понятны, потому что он способен опираться на опыт и контекст. Искусственный интеллект воспринимает подобные рекомендации значительно буквальнее.
Например, инструкция:
Пишите качественный код.
практически бесполезна. Что означает «качественный»? Для одной модели это минимальное количество строк, для другой — максимальная читаемость, для третьей — использование современных возможностей языка. Такая рекомендация не содержит измеримых критериев.
Гораздо лучше написать:
Каждая новая функция должна сопровождаться type hints.
Используйте dataclass вместо обычных классов,
если объект предназначен только для хранения данных.
Не создавайте функции длиннее 50 строк.
Каждая публичная функция должна содержать docstring.
Подобные инструкции невозможно трактовать по-разному. Агент понимает, что именно от него требуется.
Это касается практически любого раздела AGENTS.md. Чем конкретнее правило, тем выше вероятность его соблюдения.
Ещё одна распространённая ошибка — попытка описать абсолютно всё. Некоторые файлы AGENTS.md занимают несколько сотен страниц, содержат повторяющиеся инструкции и превращаются в энциклопедию проекта. Это ухудшает качество работы модели.
Во-первых, агент тратит больше времени на чтение документа. Во-вторых, длинные инструкции чаще содержат противоречия. Если в начале файла сказано «использовать только асинхронные функции», а в конце встречается пример с синхронным кодом, модель вынуждена самостоятельно решать, какое правило считать главным.
Поэтому хороший AGENTS.md всегда строится по принципу «минимум слов — максимум смысла».
Полезно разделять инструкции по степени важности.
Например, обычные рекомендации можно писать простым текстом:
Предпочитайте существующие сервисы созданию новых.
Но действительно критичные требования стоит выделять явно:
MUST:
Перед завершением задачи обязательно запустите все тесты.
NEVER:
Не изменяйте схему базы данных без явного запроса.
IMPORTANT:
Если решение требует изменения архитектуры,
сначала объясните причины.
Таких директив не должно быть слишком много. Если каждый второй абзац начинается со слова MUST, документ перестаёт выделять действительно важные требования.
Ещё один полезный приём — объяснять не только правило, но и его причину. Современные модели значительно лучше соблюдают инструкции, когда понимают их смысл.
Например:
Не добавляйте новые зависимости,
поскольку проект используется в изолированной среде
без доступа к интернету.
или
Используйте существующий сервис авторизации.
Создание второго механизма приведёт
к дублированию логики.
Такие пояснения помогают модели выбирать правильное решение даже в нестандартных ситуациях.
Отдельное внимание стоит уделить примерам. Если проект придерживается определённого стиля, покажите агенту образец.
Правильно:
class UserService:
async def get_user(...):
Неправильно:
class user_service:
def GetUser(...):
Для языковых моделей примеры часто оказываются эффективнее длинных текстовых объяснений.
Не стоит забывать и о безопасности. AGENTS.md — это обычный текстовый файл, который почти всегда хранится в репозитории. Никогда не размещайте в нём API-ключи, пароли, внутренние токены, адреса закрытых сервисов или другую конфиденциальную информацию. Агенту достаточно знать, где получить необходимые переменные окружения, но не сами значения.
Наконец, важно помнить, что AGENTS.md — живой документ. Проект развивается: появляются новые сервисы, меняются правила, обновляются инструменты, внедряются другие процессы. Если файл не поддерживать в актуальном состоянии, очень быстро он начнёт вводить AI в заблуждение. В этом случае устаревшие инструкции окажутся даже опаснее, чем их полное отсутствие.
Хороший AGENTS.md редко создаётся за один вечер. Обычно он развивается вместе с проектом. После каждой ситуации, когда агент допустил ошибку или задал один и тот же вопрос повторно, стоит задуматься: возможно, этой информации просто не хватает в инструкции. Со временем документ становится своеобразной базой знаний команды, позволяющей любому AI-агенту включаться в работу практически так же быстро, как опытному разработчику.
По мере роста проекта одного файла AGENTS.md может оказаться недостаточно. Небольшое веб-приложение легко описать в нескольких десятках правил, но современные системы нередко состоят из десятков сервисов, нескольких языков программирования, отдельных мобильных клиентов, инфраструктуры и большого количества вспомогательных инструментов. В этом случае возникает вопрос: как организовать документацию так, чтобы AI не запутался?
Большинство современных AI-агентов поддерживают иерархию инструкций. Это означает, что файл AGENTS.md может находиться не только в корне репозитория, но и внутри отдельных каталогов. Когда агент начинает работать с определённой частью проекта, он читает как общие правила, так и локальные инструкции, относящиеся только к текущему модулю.
Например, в корне репозитория можно определить общие принципы разработки:
/AGENTS.md
/frontend/AGENTS.md
/backend/AGENTS.md
/mobile/AGENTS.md
/infrastructure/AGENTS.md
Корневой документ описывает правила, обязательные для всего проекта: стиль работы команды, требования к безопасности, оформление изменений, запуск тестов и общие архитектурные ограничения.
Локальные файлы содержат только ту информацию, которая относится к конкретной подсистеме. Например, инструкции для мобильного приложения совершенно не нужны агенту, который исправляет ошибку в серверной части.
Такой подход делает документацию компактнее и уменьшает объём контекста, который приходится анализировать модели. Вместо сотен страниц агент читает только действительно важные для текущей задачи инструкции.
Ещё один полезный принцип — разделять постоянные правила и временные ограничения.
Например, архитектурное требование использовать PostgreSQL вряд ли изменится в ближайшие годы. А вот информация о том, что сейчас идёт рефакторинг определённого модуля, актуальна лишь несколько недель.
Не стоит смешивать эти вещи в одном разделе. Постоянные правила должны оставаться стабильными, а временные инструкции лучше явно отмечать и своевременно удалять после завершения работы.
Не менее важно определить границы самостоятельности AI-агента. Современные модели способны выполнять довольно сложные действия без участия человека, однако далеко не каждое решение должно приниматься автоматически.
Полезно заранее описать, что агент может делать самостоятельно.
Разрешено:
исправлять ошибки;
рефакторить код без изменения поведения;
добавлять тесты;
обновлять документацию;
улучшать комментарии.
И отдельно перечислить действия, требующие подтверждения:
Требуется согласование:
изменение архитектуры;
изменение публичного API;
добавление зависимостей;
изменение структуры базы данных;
удаление функциональности.
Подобное разделение делает работу агента значительно безопаснее. Он понимает, где может действовать самостоятельно, а где обязан остановиться и запросить решение разработчика.
Особое внимание стоит уделить взаимодействию нескольких AI-инструментов. Сегодня многие команды используют сразу несколько моделей: одна отлично пишет код, другая сильнее в анализе архитектуры, третья эффективнее ищет ошибки или составляет документацию. Если в проекте применяется такой подход, это тоже стоит зафиксировать.
Используйте специализированные инструменты по назначению.
Для анализа архитектуры не изменяйте код.
После генерации изменений обязательно выполните проверку тестами.
Перед завершением задачи обновите документацию, если поведение системы изменилось.
Подобные инструкции помогают выстроить единый процесс разработки независимо от того, какой именно AI используется в данный момент.
И наконец, стоит помнить, что AGENTS.md не заменяет архитектурную документацию, техническое задание или описание бизнес-логики. Его задача значительно уже: объяснить агенту, как правильно работать внутри проекта. Чем лучше разделены эти виды документации, тем проще ориентироваться и человеку, и искусственному интеллекту.
Хороший AGENTS.md редко оказывается идеальным с первой версии. Обычно он развивается постепенно. После каждой успешно выполненной задачи становится понятно, каких инструкций оказалось достаточно, а после каждой ошибки — каких правил не хватило. Именно поэтому лучшие документы появляются не в результате долгого планирования, а как итог постоянной практической работы с AI.
Со временем такой файл превращается в своеобразную операционную систему проекта. Новый разработчик быстрее понимает внутренние процессы, AI-агенты реже совершают ошибки, а команда перестаёт повторять одни и те же объяснения. Именно в этом заключается главная ценность AGENTS.md — он сохраняет накопленный опыт команды и делает его доступным не только людям, но и искусственному интеллекту.
Теперь соберём всё вместе и посмотрим, как может выглядеть универсальный AGENTS.md. Это не жёсткий стандарт, а отправная точка, которую можно адаптировать практически под любой проект.
# AGENTS.md
## О проекте
Кратко опишите назначение системы, используемый стек
и основные принципы архитектуры.
## Структура проекта
Опишите основные каталоги и их назначение.
## Правила разработки
Какие технологии использовать.
Какие решения запрещены.
Какие архитектурные принципы необходимо соблюдать.
## Запуск проекта
Команды установки зависимостей.
Команды запуска.
Команды сборки.
## Проверка качества
Какие тесты необходимо запускать.
Какие линтеры использовать.
Какие проверки обязательны перед завершением работы.
## Ограничения
Что агент никогда не должен делать самостоятельно.
## Формат результата
Как описывать внесённые изменения.
Когда обновлять документацию.
Когда требуется согласование с разработчиком.
Это лишь каркас. В реальном проекте каждый раздел постепенно наполняется конкретными инструкциями. Не стремитесь написать идеальный документ с первой попытки. Гораздо эффективнее регулярно дополнять его по мере накопления опыта работы с AI.
Есть простой принцип, который помогает понять, чего не хватает в AGENTS.md. Если агент уже второй раз задаёт один и тот же вопрос или допускает одну и ту же ошибку, значит, соответствующее правило должно появиться в документе.
Например, если AI постоянно забывает запускать тесты, не нужно каждый раз напоминать об этом в чате. Достаточно один раз добавить соответствующую инструкцию в AGENTS.md.
Если модель регулярно предлагает библиотеку, которую команда не использует, это тоже повод обновить документ. Через несколько подобных итераций количество повторяющихся вопросов заметно сокращается, а качество работы становится значительно выше.
Полезно периодически пересматривать AGENTS.md так же, как пересматривают архитектурную документацию. Удаляйте устаревшие правила, уточняйте формулировки, добавляйте новые соглашения, если они стали частью процесса разработки. Документ должен отражать текущее состояние проекта, а не историю его развития.
Не менее важно помнить, что AGENTS.md не является заменой здравому смыслу. Даже самые подробные инструкции не смогут предусмотреть абсолютно все ситуации. Поэтому критически важные изменения — изменение архитектуры, удаление функциональности, миграции базы данных или внедрение новых зависимостей — по-прежнему должны проходить через человека.
В ближайшие годы роль подобных документов будет только расти. AI-агенты становятся всё более автономными: они уже умеют анализировать кодовую базу, выполнять сложные задачи, запускать тесты и самостоятельно исправлять ошибки. Следующим логичным шагом становится стандартизация способов взаимодействия между человеком и искусственным интеллектом.
Именно поэтому сегодня AGENTS.md перестаёт быть экспериментом отдельных энтузиастов. Он постепенно превращается в новую категорию проектной документации — документации, предназначенной не только для разработчиков, но и для AI.
Когда-то обязательным считалось наличие файла README.md. Затем появились CONTRIBUTING.md, CODE_OF_CONDUCT.md, файлы лицензий, шаблоны Pull Request и инструкции по развёртыванию. AGENTS.md вполне может стать следующим естественным элементом любого профессионального репозитория.
И дело здесь не в конкретной модели искусственного интеллекта. Claude, ChatGPT, Gemini, Cursor, Codex или другой инструмент могут меняться, но потребность объяснить цифровому помощнику правила работы останется. Чем раньше команда начнёт формировать такие инструкции, тем проще ей будет адаптироваться к новой эпохе разработки, где AI становится не просто инструментом, а полноценным участником инженерного процесса.
Главный вывод прост: хороший AGENTS.md — это инвестиция, которая окупается каждый раз, когда AI быстрее понимает проект, реже допускает ошибки и требует меньше уточняющих вопросов. Один раз потратив несколько часов на создание качественного документа, можно сэкономить десятки часов в дальнейшем и сделать совместную работу человека и искусственного интеллекта значительно эффективнее.
