AGENTS.md: единый источник истины для ИИ-агентов
Коротко: AGENTS.md — это главная шпаргалка для ИИ-помощника в проекте. В ней пишем простыми словами: куда можно лезть, куда нельзя, как у нас всё устроено. Новичку или агенту хватает 5–10 минут чтения — и он уже не ломает проект.
Самые простые шаблоны AGENTS.md
Я почти всегда начинаю с шаблона. Когда проект новый, я просто беру заготовку, меняю пару строк под свой стек — и можно работать.
Сейчас у меня есть три варианта. Они закрывают самые частые случаи: от простого сайта до более сложного бэкенда с данными и интеграциями.
Важно: эти шаблоны не «универсальное решение». Я показываю их как примеры из своих проектов — чтобы было от чего оттолкнуться, а не чтобы копировать вслепую.
AGENTS.md я пишу не в самом начале. Сначала должен появиться хоть какой-то план проекта — обычно он рождается прямо в диалоге с ИИ: что делаем, зачем, в каком порядке.
И только когда этот план становится понятным, я фиксирую его в AGENTS.md. По сути, это способ сохранить договорённость: как мы решили делать этот проект и где нельзя начинать «умничать».
В конце я как раз написал, как собрать AGENTS.md под свой проект, уже исходя из готового плана, а не из абстрактных правил.
Шаблон 1 — для лёгкого веб-проекта (лендинг, блог, Next.js без лишнего)
AGENTS.md — наши простые правила
Проект: сайт для показа контента, без сложных фич.
Вайб: быстро, читаемо, для новичков.
Стек:
- frontend: Next.js, Tailwind CSS
- backend: если нужен — Express.js
Что можно:
- добавлять страницы в app/ или components/
- менять стили в Tailwind
- писать простые API-роуты в api/
Что нельзя без моего ок:
- добавлять новые библиотеки вроде Zustand или Redux
- создавать глобальный стейт — только useState
- менять навигацию на что-то кроме Next Link
- писать console.log — только в dev, и то редко
Файлы держим короткими: до 200 строк.
Если идея кажется сложной — спроси: «это ещё просто или уже overkill?»Шаблон 2 — для мобильного или Telegram-бота (WebApp с UI и логикой)
AGENTS.md — как мы работаем с ботом
Проект: Telegram WebApp с экранами и данными.
Вайб: плавно, без лагов, легко понять.
Стек:
- client: JavaScript, возможно React
- src: Node.js для API и бота
Переключение экранов:
- только через наш NavigationManager
- рендер страниц: RenderManager с проверкой токена
Прокрутка:
- только в #mainContent, body не трогать
Логи:
- никаких console.log — только logger.js
Что можно:
- добавлять кнопки и формы в существующие страницы
- звать API через ApiClient
- трекать события в analytics/track
Что нельзя:
- обходить NavigationManager
- добавлять прямые DOM-изменения
- вводить новые слои вроде middleware без причины
Если не уверен — спроси: «это не сломает жест назад или рендер?»Шаблон 3 — для data-проекта (анализ данных, скрипты на Python)
AGENTS.md — правила для данных
Проект: скрипты для обработки данных, графики, отчёты.
Вайб: чисто, воспроизводимо, без лишних зависимостей.
Стек:
- Python с Pandas, Matplotlib
- если ML — Scikit-learn, ничего сложного
Что можно:
- читать данные из CSV/Excel через Pandas
- строить графики в Matplotlib
- писать функции для расчётов
Что нельзя без ок:
- добавлять новые пакеты вроде TensorFlow
- менять структуру данных на сложные классы
- писать циклы вместо векторных операций
- игнорировать ошибки — всегда обрабатывать
Файлы: один скрипт = одна задача, до 300 строк.
Спроси, если сомневаешься: «это ещё эффективно или уже медленно?»Шаблон 4 — для бэкенда с API (сервер, интеграции, как в e-commerce)
AGENTS.md — backend правила
Проект: API-сервер с роутами, платежами, вебхуками.
Вайб: безопасно, минимально, без хаков.
Стек:
- Node.js, Express
- роуты в src/routes/
Ключевые зоны:
- auth: только в auth.router.js
- payments: в payments.js, не трогать без тестов
- webhooks: yookassa/bitrix в webhooks.js
Что можно:
- добавлять роуты в существующие файлы
- обновлять модели в db/
- логировать через logger
Что нельзя:
- хардкодить ключи или env
- обходить middleware
- вводить новые базы без обсуждения
- менять production без деплоя
Все изменения — с обновлением docs/.
Если идея рискованная — спроси: «это безопасно для продакшена?»А если я новичок?
Даже если ты совсем не знаешь React, Next.js, навигацию, роутеры и прочие технические слова — AGENTS.md всё равно можно сделать.
Просто пиши то, что тебе важно на человеческом языке: «хочу быстро», «не усложнять», «чтобы потом не запутаться».
ИИ сам поймёт и превратит твои простые желания в понятные правила для себя.
Самый простой способ — рассказать ИИ, что ты хочешь чувствовать
Ты не обязан знать термины. Просто скажи агенту примерно так:
«Я новичок в программировании.
Хочу сделать Telegram-бот или простое приложение в телеграме.
Мне важно, чтобы:
- всё было просто и понятно
- код не становился огромным и запутанным
- я мог сам разобраться через месяц
- ты не предлагал сложные штуки, которые я не понимаю
- не добавлял кучу новых библиотек без моего разрешения
Напиши мне файл AGENTS.md простыми словами, как будто пишешь другу-новичку.
Чтобы ты сам потом по нему работал и не усложнял мне жизнь.»
ИИ почти всегда выдаст нормальный файл. Вот что обычно получается после такого запроса.
Пример AGENTS.md, который делает ИИ, когда ты говоришь «я новичок, всё просто»
AGENTS.md — наши простые договорённости
Мы делаем проект для меня-новичка
Главное желание:
- быстро увидеть результат
- код короткий и понятный
- чтобы я мог сам потом поменять что-то без страха
Что можно делать:
- добавлять новые кнопки, текст, картинки
- менять цвета и надписи
- исправлять ошибки, которые я вижу
- писать комментарии, чтобы было понятно, что делает каждая часть
Что лучше не делать без моего «да»:
- добавлять новые библиотеки и пакеты
- создавать много новых файлов и папок
- писать очень длинные функции (больше 30–40 строк — уже спрашивай)
- придумывать сложную систему логинов, если я не просил
- менять всё сразу (лучше по чуть-чуть)
Если ты думаешь, что можно сделать красивее или быстрее — сначала спроси:
«Хочешь, я сделаю вот так? Это будет проще или сложнее для тебя?»
Если сомневаешься — лучше спроси, чем потом переделывать.Ещё один вариант — когда ты уже устал от предложений «а давай добавим …»
Скажи агенту вот это:
«Я не знаю, что такое Zustand, Redux, Context и прочее.
Каждый раз, когда ты предлагаешь такие вещи — мне страшно и непонятно.
Напиши AGENTS.md, в котором будет написано, что мы используем только самые простые способы.
И если что-то кажется сложным — ты обязан спросить меня сначала.
Сделай текст очень простым, без технических слов.»
Получится примерно так:
AGENTS.md — правила для новичка
Мы договорились: всё максимально просто!
Запрещено предлагать:
- Zustand
- Redux
- Context API
- useReducer
- любые слова, которые я не понимаю
Разрешено:
- обычный useState для хранения данных
- передавать данные через props
- если данных много — спроси у меня, прежде чем придумывать решение
Если тебе хочется сделать что-то «по-взрослому» — пиши:
«Я знаю способ получше, но он чуть сложнее. Хочешь попробовать или оставим просто?»
Цель: чтобы я не боялся открывать код и мог сам что-то поправить.Универсальный запрос, который почти всегда работает
Если не знаешь, что именно сказать — просто кинь это:
«Я совсем новичок.
Не знаю, как правильно писать код.
Хочу, чтобы ты помогал, но не усложнял.
Напиши мне AGENTS.md, который будет напоминать тебе:
- говорить со мной простыми словами
- предлагать только самые лёгкие способы
- всегда спрашивать, если решение кажется сложным
- держать код коротким и понятным
Сделай файл коротким, дружеским, без страшных слов.»
Что делать после того, как ИИ написал файл
- Прочитай его (обычно 10–20 строк).
- Если что-то не нравится — скажи: «добавь, пожалуйста, что файлы не должны быть длиннее одной страницы» или «убери слово Zustand, я его даже не знаю».
- Сохрани как AGENTS.md в папке с проектом.(можно попросить ИИ, чтобы он сам сохранил)
- Каждый раз, когда начинаешь новую беседу с ИИ, начинай сообщение с:
«Проанализируй наш AGENTS.md, следуй ему»
После этого ИИ обычно становится гораздо спокойнее и понятнее.