Вашему коду нужна инструкция для ИИ

Почему AGENTS.md может стать началом нового слоя архитектуры программ

Раньше код объяснял себя разработчикам. Теперь ему нужно объяснять себя и машинам.

Коротко

• AGENTS.md это обычный Markdown-файл в корне репозитория, который объясняет ИИ-агентам, как работать с проектом: команды, ограничения и правила, которые не видны из кода.
• Его читают больше двадцати инструментов для программирования, включая Codex, Cursor, Gemini CLI и Copilot. С 18 сентября 2026 года его читает и Claude Code.
• С декабря 2025 года AGENTS.md развивается в Agentic AI Foundation под крылом Linux Foundation, вместе с MCP.
• Исследование ETH Zürich показывает, что больше контекста не значит лучше: короткие файлы, написанные людьми, немного помогают, а длинные или сгенерированные добавляют стоимость без пользы.
• Самые ценные строки в таком файле это не правила кода. Это уроки бизнеса, о которых код сам не расскажет.

КАК МЫ НАЧАЛИ

Раньше, чем это стало новостью

В PERETZ мы не работаем внутри одной экосистемы ИИ. В разных проектах разные модели и разные среды разработки. Иногда выбор зависит от задачи, иногда от этапа проекта, а иногда мы просто знаем, что одна модель делает что-то лучше другой.

Среда разработки с ИИ давно перестала быть автодополнением с окном чата. Современные агенты изучают репозиторий, ищут по файлам, запускают команды, правят код, прогоняют тесты и проходят многошаговые задачи. Claude стал для нас особенно полезной частью этой работы, и я сознательно называю его ассистентом, а не инструментом. Инструмент ждёт, пока им воспользуются. Агент сам смотрит на задачу, изучает код, вносит изменение, проверяет результат и идёт дальше.

Долгое время каждому агенту нужны были свои инструкции. Codex, Cursor и другие уже читали AGENTS.md, а Claude Code читал только свой CLAUDE.md. 18 сентября, в версии 2.1.277, Claude Code начал читать и AGENTS.md: если в папке нет CLAUDE.md, он берёт AGENTS.md.

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

Поработав с этим на практике, а не просто прочитав, мы можем сказать больше, чем «выглядит многообещающе»: это работает. Не магически и не идеально, но работать с агентами стало заметно удобнее. А за этим небольшим улучшением стоит гораздо большая перемена.

РАЗРЫВ

Одного кода недостаточно

Представьте, что вы пришли разработчиком в большой проект. Вам дали репозиторий. Можно искать по всему коду, смотреть базу данных, читать описание API и запускать приложение. Технически у вас есть всё.

Но знаете вы не всё.

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

Человек обычно узнаёт это в разговоре. «Это не трогай». «Мы уже пробовали». «Так требует клиент». «Выглядит странно, но на то есть причина».

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

Но чище не значит правильнее. Агент понимает код. Он может не понимать бизнес, который этот код создал.

Агент понимает код. Он может не понимать бизнес.

ДАЛЬШЕ README

README писали для людей

Десятилетиями README был самым близким подобием инструкции к проекту. Установите это. Запустите это. Соберите это. Вот что делает приложение. Полезно, но написано прежде всего для людей.

ИИ-агенту нужен другой слой информации. Не обязательно больше информации. Другая информация.

Что можно трогать? Что нельзя трогать никогда? Как тестировать приложение? Каким шаблонам должен следовать новый код? Где живёт бизнес-логика? Какие зависимости оставлены намеренно? И, возможно, самый важный вопрос: когда агент должен остановиться и спросить человека, а не решать сам?

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

ОДИН ПРОЕКТ

Разные агенты, один проект

Представьте проект, где один разработчик работает в Claude Code, второй предпочитает Codex, а третий Cursor. Модели разные. Интерфейсы разные. Доступные инструменты разные.

Но проект один и тот же. Архитектура, бизнес-правила, ограничения выкатки и то, что ни в коем случае нельзя сломать, одинаковы для всех. Зачем каждому агенту открывать всё это заново?

Поэтому то, что индустрия сходится на AGENTS.md, важнее любого отдельного анонса. Формат оформили в августе 2025 года OpenAI вместе с Google, Cursor и Factory. В декабре 2025 года Linux Foundation создал Agentic AI Foundation, и AGENTS.md стал одним из трёх её первых проектов, рядом с Model Context Protocol от Anthropic и goose от Block. С приходом Claude Code в сентябре 2026 года основные агенты для программирования читают один и тот же файл.

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

Иногда соглашения важнее стандартов.

НАША ИНСТРУКЦИЯ

Что написано у нас

Файлы клиентских проектов мы показать не можем. Но можем показать свой. Вот часть AGENTS.md из репозитория сайта PERETZ:

## Never
- Never add noindex, nofollow or an X-Robots-Tag header, and never edit
  public/robots.txt. The live site must stay open to search engines.
- Never block AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot).
- Never regenerate APP_KEY on an existing environment.
- Never change the URL or alias of an existing page. If it is unavoidable,
  add a 301 redirect and ask first.

## Before deleting anything
Code that looks unused may be called from database content, cron scripts
or external integrations. Search for usages and ask before removing it.

Ни одна из этих строк на самом деле не про код. Каждая из них урок бизнеса.

Правило про noindex существует потому, что один тег, добавленный «временно» во время разработки, может тихо убрать сайт из Google. Правило про ИИ-роботов существует потому, что сайта, который не могут прочитать ChatGPT и Perplexity, для растущей части покупателей просто нет. Правило про адреса существует потому, что каждый адрес, изменённый без переадресации, выбрасывает годы поисковой истории.

А правило про удаление кода мы поставили бы в каждый AGENTS.md. «Выглядит лишним, удали» это совершенно разумный инженерный рефлекс и удивительно дорогая ошибка для бизнеса. На сайте, где контент живёт в базе данных, код, на который не ссылается ни один файл, может использоваться каждый день.

Именно такое знание обычно и исчезает из проектов: не то, как устроен код, а то, чему бизнес научился на собственных ошибках.

УСТРОЙСТВО

Как мы это устроили

Если вы работаете с Claude Code, важна одна деталь. Он читает AGENTS.md, только если ни в этой папке, ни выше нет CLAUDE.md. Если CLAUDE.md есть, Claude Code читает его и игнорирует AGENTS.md.

Поэтому мы разделили файлы по адресату:

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

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

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

СТАРЫЙ КОД

Со старым кодом сложнее

Старые системы часто хранят историю бизнеса. Кто-то сделал обходной путь. Кто-то добавил исключение. Кто-то оставил странный ответ API, потому что от него зависела другая система. Разработчик, принявший это решение, мог уйти много лет назад. Код остался.

Поэтому модернизация старой системы это не просто «найти старый код и заменить его лучшим». Это археология. Нужно понять, что обязано остаться, прежде чем решать, что может исчезнуть. Подробнее мы писали об этом в статье «Обновление старого сайта на Laravel или PHP в 2026 году».

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

ИИ читает код. А кто читает бизнес?

Хороший AGENTS.md сам по себе эту проблему не решит. Но он даёт команде одно место, где можно записать тот бизнес- и архитектурный контекст, который агенту действительно нужен, пока люди, которые его помнят, ещё рядом.

МЕНЬШЕ ЛУЧШЕ

Роман нам не нужен

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

В 2026 году SRI Lab в ETH Zürich проверила файлы контекста на нескольких агентах, включая Claude Code и Codex, на сотнях реальных задач с GitHub. В целом файлы не повысили долю решённых задач и увеличили стоимость работы больше чем на 20%. Агенты действительно следовали инструкциям: больше тестировали и изучали больше файлов. Но лишние требования делали задачи сложнее.

Детали ещё полезнее. Файлы, написанные людьми, улучшили результат в среднем примерно на 4%. Файлы, сгенерированные моделью, дали результат чуть хуже, чем вовсе без файла. А обзоры структуры папок, которыми заполнена большая часть сгенерированных файлов, не помогли агентам быстрее находить нужные файлы.

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

Значит, цель не инструкция, в которой собрано всё, что люди знают о проекте. Цель в том, чтобы дать агенту те немногие вещи, которые он иначе узнал бы только через повторяющиеся ошибки. Наш собственный файл короче пятидесяти строк, и мы написали его вручную.

НОВЫЙ ИНТЕРФЕЙС

Репозиторий как интерфейс

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

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

У этой истории есть и вторая сторона. Инструкция помогает агентам строить ваши программы. Но агенты начинают пользоваться и самими сайтами: искать товары, сравнивать предложения, заполнять формы, оформлять заказы. Для этого нужно другое: сайт, который открывает машинам свои данные и действия, а не только страницы людям.

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

ЧТО ДАЛЬШЕ

Чем это закончится

Говорить, как всё будет выглядеть через пять лет, ещё рано. У инструментов по-прежнему свои системы правил: кто-то использует CLAUDE.md, кто-то .cursor/rules, кто-то AGENTS.md, кто-то всё сразу.

Годами связь между людьми и кодом была простой. Теперь это не так:

Разные модели, разные возможности, один и тот же репозиторий, один и тот же бизнес и одни и те же последствия, когда что-то ломается.

Мы даже можем хотеть, чтобы разные агенты подходили к одной задаче по-разному. Но понимать они должны одну и ту же реальность.

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

Название файла может измениться. Принцип, скорее всего, останется.

ИНСТРУКЦИЯ

Инструкция для ИИ

Мы начали пользоваться AGENTS.md, потому что это было практично. Продолжили, потому что работать с разными агентами стало проще. А сама идея оказалась интереснее файла.

У программ появляется ещё одна аудитория. Не только разработчики и не только пользователи, но и машины, которые умеют разрабатывать программы. Это меняет то, как мы думаем о документации, об архитектуре и о старом коде.

Хорошо спроектированная система всегда старалась сделать свою логику понятной людям, которые её поддерживают. Теперь у неё есть ещё одна обязанность: сделать нужные части этой логики понятными агентам, которые работают рядом с людьми. Не всё, не вслепую, не в тысяче строк. Ровно столько контекста, чтобы знать то, чего код не может рассказать сам.

Если ваша команда начинает работать с ИИ-агентами или ваша система слишком стара, чтобы они могли безопасно в ней работать, именно с таких задач начинается наша работа по модернизации сайтов. А если вы ещё решаете, сколько доверить ИИ, прочитайте статью «Нужен ли мне разработчик, или хватит ИИ?»

FAQ

Вопросы и ответы

Что такое AGENTS.md?

Обычный Markdown-файл в корне репозитория, который объясняет ИИ-агентам, как работать с проектом: команды, ограничения, соглашения и когда нужно спросить человека. По сути, это README для агентов.

Читает ли Claude Code файл AGENTS.md?

Да, начиная с версии 2.1.277 от 18 сентября 2026 года, но только если ни в папке, ни выше нет CLAUDE.md. Чтобы использовать оба файла, начните CLAUDE.md со строки @AGENTS.md.

Чем AGENTS.md отличается от CLAUDE.md?

AGENTS.md не привязан к конкретному инструменту, его читает большинство агентов для программирования. CLAUDE.md читает Claude Code. На практике удобно держать общие правила в AGENTS.md, а в CLAUDE.md только то, что касается Claude.

Какой длины должен быть AGENTS.md?

Короткий. Исследование ETH Zürich показало, что лишний контекст повышает стоимость работы больше чем на 20% без улучшения результатов, и рекомендует описывать только минимальные требования. Наш файл короче пятидесяти строк.

Что не стоит писать в AGENTS.md?

Пароли, ключи и адреса серверов, длинные обзоры структуры папок, которые агент найдёт сам, и всё, что сгенерировано автоматически и не проверено человеком.

Источники

• Anthropic decides to support OpenAI's markdown instructions spec, The Register
• Claude Code now supports AGENTS.md natively, DEV Community
• Linux Foundation forms Agentic AI Foundation, SD Times
• OpenAI and Anthropic donate AGENTS.md and MCP to the Agentic AI Foundation, InfoQ
• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, SRI Lab, ETH Zurich
• Does AGENTS.md Actually Help Coding Agents?, DAIR.AI Academy