Запишите это для машины

Самое полезное, что можно сделать, чтобы кодовые ИИ-агенты работали лучше, — это не лучший промпт и не лучшая модель. Это простой текстовый файл в корне репозитория под названием AGENTS.md, и большинство строящих с агентами его до сих пор не написали.

Вот почему это важно сейчас. Год назад у каждого инструмента был свой особый файл — .cursorrules, CLAUDE.md, конфиг Copilot, что-то своё у Devin. Вы писали конвенции проекта пять раз или не писали вовсе. Это позади. На начало 2026-го AGENTS.md читают нативно Claude Code, Codex CLI от OpenAI, Cursor, Aider, Devin, GitHub Copilot, Gemini CLI, Windsurf и Amazon Q — это ближайшее к универсальному формату инструкций для кодовых агентов. Один файл, и почти каждый агент, открывающий ваш репозиторий, читает его первым.

Давайте я приведу довод реально его написать, потому что рычаг тут перекошенный.

Что это, простыми словами

AGENTS.md — это Markdown-файл, который вы кладёте в корень проекта. Это записка, которую вы оставили бы толковому новому подрядчику, никогда не видевшему вашу кодовую базу: как её собрать, как гонять тесты, какие конвенции, что не трогать. Агент читает её перед началом работы и относится как к постоянным инструкциям — так вы пишете контекст один раз, вместо того чтобы перепечатывать его в каждый промпт до конца проекта.

В этом весь фокус. Это не новый фреймворк и не хитрый промпт. Это запись того, что вы и так знаете про свой проект, чтобы машина знала это тоже.

Почему это так хорошо работает

Агенты падают не потому, что тупы. Они падают потому, что работают вслепую — они не видят неписаных правил, которые каждый человек в команде впитал осмосом. Агент не знает, что вы всегда гоняете pnpm, никогда npm. Не знает про модуль, который никто не трогает без ревью. Не знает, что тесты должны пройти порог покрытия, прежде чем что-то отгрузится. Так что он гадает, и треть догадок неверна.

Хороший AGENTS.md убирает гадание. Это та же мысль, что и почему спека бьёт промпт: долговечный, переиспользуемый артефакт — это записанный контекст, а не одноразовая инструкция. И он накапливается — каждый запуск агента, в любом инструменте, на любой ветке, стартует из одного общего понимания, а не с нуля.

Что туда реально кладут

Держите коротко и конкретно. Те, что работают, читаются как чек-лист, а не как эссе:

• Как собрать и запустить. Точные команды — установка, dev-сервер, сборка. Пропишите pnpm против npm, нужную версию Node, любой неочевидный шаг настройки.
• Как тестировать. Команда тестов, планка покрытия, «все гейты зелёные перед коммитом». Агенты куда полезнее, когда могут гонять тесты и сами видеть настоящий сбой.
• Конвенции, что важны. Именование, правила линта/формата, «следуй окружающему коду». То, что ревьюер иначе вернёт обратно.
• Что не трогать. Сгенерированные файлы, тот самый хрупкий модуль, секреты, всё, где «услужливо отрефакторил» — это катастрофа.
• Форма проекта. Однострочная карта, где что лежит, чтобы агент не реверс-инженерил вашу структуру на каждой задаче.

Пропустите философию. Агенту не нужна ваша миссия; ему нужны команды, ограничения и мины.

Суть

Мы тратим много сил на промпты, которые на одну задачу и исчезают, и почти нисколько — на единственный артефакт, который на весь проект и остаётся. AGENTS.md превратился из пофичевой штучки в почти универсальный стандарт ровно потому, что решает настоящую проблему: агенты работают вслепую, и лекарство — перестать заставлять их гадать про то, что вы и так знаете.

Так что прежде чем в следующий раз навести агента на репозиторий, потратьте этот час. Запишите, как собрать, как тестировать, какие правила и что оставить в покое. Это редкий ИИ-совет, который стоит почти ничего, работает во всех инструментах, что вы используете, и окупается на каждом запуске. Запишите это для машины — она читает.