ИИ-агенты кода всё чаще приходят в проект, не зная о нём ничего: как его собрать, какими командами тестировать, что трогать нельзя. Объяснять это каждому агенту заново – долго. Чтобы не повторяться, договорились о едином файле с инструкциями – AGENTS.md.
Если коротко: AGENTS.md – это обычный Markdown-файл в корне репозитория, в котором вы простыми словами описываете проект для ИИ-агентов: как его собрать, как протестировать, какие правила соблюдать и чего делать нельзя.
Главная идея – это общий формат. Один и тот же файл читают разные ИИ-инструменты, а не каждый свой. Дальше разберём, что в нём пишут, чем он отличается от CLAUDE.md и как собрать свой по шагам.
Содержание
- Что такое AGENTS.md простыми словами
- Чем AGENTS.md отличается от CLAUDE.md
- Шаг 1: Опишите проект в двух абзацах
- Шаг 2: Дайте команды сборки и тестов
- Шаг 3: Зафиксируйте конвенции
- Шаг 4: Обозначьте границы и запреты
- Пример готового AGENTS.md
- Типичные ошибки
- FAQ
Что такое AGENTS.md простыми словами
Представьте, что в команду пришёл новый исполнитель – толковый, но про ваш проект не знает ничего. Чтобы он сразу начал приносить пользу, вы пишете ему короткую памятку: вот так у нас собирается проект, вот этими командами проверяется, так мы оформляем код, а вот сюда лезть не надо. AGENTS.md – ровно такая памятка, только для ИИ-агента.
Технически это простой текстовый файл в формате Markdown. Чаще всего его кладут в корень репозитория, рядом с README. Когда ИИ-агент начинает работу в проекте, он первым делом читает этот файл и сразу понимает контекст – не приходится объяснять одно и то же в каждом запросе.
Важно понимать, что AGENTS.md – это договорённость, а не жёсткий технический формат с обязательными полями. Внутри – обычный Markdown: заголовки, списки, блоки кода. Вы сами решаете, какие разделы включить. Есть привычный набор, который встречается чаще всего: обзор проекта, команды сборки и тестов, правила оформления кода, границы и запреты. Но строгой спецификации с обязательными именами полей нет – пишите так, как удобно агенту читать.
Если вы уже работаете с ИИ-агентами кода и хотите глубже понять саму идею автономных помощников, посмотрите разбор что такое ИИ-агент – AGENTS.md как раз и нужен, чтобы такой агент быстрее входил в курс дела.
Чем AGENTS.md отличается от CLAUDE.md
Здесь чаще всего и возникает путаница, потому что файлы похожи по сути. Разберём разницу.
CLAUDE.md – это файл инструкций конкретного инструмента, Claude Code от Anthropic. Claude Code читает именно его и держит правила проекта перед глазами в каждой задаче. Это удобно, но привязано к одному инструменту: другой агент про CLAUDE.md может ничего не знать. Подробно его формат разобран в гайде про файл памяти CLAUDE.md, а все материалы по самому инструменту – в разделе про Claude Code.
AGENTS.md решает другую проблему – общий язык для разных агентов. Идея в том, что один файл читают несколько ИИ-инструментов, а не каждый требует свой. Вы пишете инструкции один раз, и они работают там, где этот формат поддерживается.
| Параметр | AGENTS.md | CLAUDE.md |
|---|---|---|
| Назначение | Общий файл инструкций для разных агентов | Файл инструкций конкретного инструмента |
| Кто читает | Несколько ИИ-инструментов, поддерживающих формат | В первую очередь Claude Code |
| Формат | Обычный Markdown, гибкая структура | Обычный Markdown, формат Claude Code |
| Когда удобен | Хотите один файл на разные инструменты | Работаете в основном в Claude Code |
На практике эти файлы не конфликтуют. Если вы работаете в Claude Code, у вас может быть CLAUDE.md под него, а AGENTS.md – как общий файл для остальных агентов. Некоторые команды идут проще: держат один файл инструкций и подключают его к нескольким инструментам сразу, чтобы не дублировать правила. Какой путь выбрать – зависит от того, сколько разных агентов крутится в вашем проекте.
Шаг 1: Опишите проект в двух абзацах
Начните с обзора – короткого ответа на вопрос «что это за проект». Агент должен за пару предложений понять, с чем имеет дело: что это, на чём написано, как устроено в общих чертах.
Не нужно пересказывать всю архитектуру. Достаточно дать опору: язык и стек, ключевые папки, точка входа. Это контекст, от которого агент будет отталкиваться дальше.
## Обзор проекта
Веб-приложение на Next.js (TypeScript). Фронтенд в `app/`,
серверная логика в `api/`, общие компоненты в `components/`.
База данных – PostgreSQL, доступ через Prisma.Шаг 2: Дайте команды сборки и тестов
Это самый ценный раздел. Агент должен знать, какими командами проект собирается, запускается и проверяется – иначе он будет угадывать, а угадывает он не всегда верно.
Перечислите команды явно, прямо как их вводят в терминале: установка зависимостей, запуск, сборка, тесты, линтер. Чем конкретнее, тем меньше шансов, что агент запустит не то.
## Команды
- Установка: `npm install`
- Запуск дев-сервера: `npm run dev`
- Сборка: `npm run build`
- Тесты: `npm test`
- Линтер: `npm run lint`Главное правило этого раздела – команды должны быть рабочими. Проверьте их сами перед тем, как класть в файл: если команда устарела, агент честно выполнит неправильную и потратит время впустую.
Шаг 3: Зафиксируйте конвенции
Конвенции – это про то, как у вас принято писать код и вести проект. Здесь вы экономите себе бесконечные правки: один раз описали стиль – и агент следует ему, а не навязывает свой.
Опишите то, что для вас важно: стиль именования, формат отступов, подход к импортам, требования к тестам, язык комментариев. Не обязательно перечислять всё – вынесите то, что чаще всего приходится поправлять руками.
## Конвенции
- TypeScript strict, без `any`
- Именование компонентов – PascalCase, функций – camelCase
- Каждый новый модуль сопровождается тестом
- Комментарии в коде – на английскомЕсли в проекте используется ИИ-агент с поддержкой внешних инструментов, в конвенциях полезно упомянуть и это – например, какие MCP-серверы подключены и для чего, чтобы агент понимал доступный ему набор возможностей.
Шаг 4: Обозначьте границы и запреты
Последний и недооценённый раздел – чего делать нельзя. Агент действует автономно, поэтому явные запреты страхуют от неприятных сюрпризов.
Пропишите границы прямым языком: какие файлы и папки не трогать, какие команды не запускать без подтверждения, что считается опасной операцией. Это не про недоверие к агенту – это про предсказуемость.
## Границы
- Не трогать файлы в `migrations/` без явной задачи
- Не запускать `git push` и операции с продакшеном
- Секреты и `.env` не коммитить и не выводить в логиПример готового AGENTS.md
Соберём всё вместе. Вот компактный AGENTS.md, который можно взять за основу и адаптировать под свой проект – коротко, по делу, без воды.
# AGENTS.md
## Обзор проекта
Веб-приложение на Next.js (TypeScript). Фронтенд в `app/`,
API в `api/`, общие компоненты в `components/`.
База – PostgreSQL через Prisma.
## Команды
- Установка: `npm install`
- Запуск: `npm run dev`
- Сборка: `npm run build`
- Тесты: `npm test`
- Линтер: `npm run lint`
## Конвенции
- TypeScript strict, без `any`
- Компоненты – PascalCase, функции – camelCase
- Новый модуль – с тестом
- Комментарии в коде на английском
## Границы
- Не трогать `migrations/` без явной задачи
- Не запускать `git push` без подтверждения
- Секреты и `.env` не коммититьПоложите этот файл в корень репозитория, проверьте, что команды рабочие, – и агент получит понятный контекст с первого захода. Со временем файл дополняется: заметили, что агент раз за разом ошибается в одном и том же – добавьте про это строчку.
Типичные ошибки
Даже простой файл легко испортить. Вот что встречается чаще всего.
Слишком длинно и абстрактно. AGENTS.md – не документация на сто страниц. Если вписать туда всё подряд, агент утонет в воде и пропустит важное. Держите файл коротким и конкретным: команды, правила, границы.
Устаревшие команды. Самая обидная ошибка: команда сборки изменилась, а в файле осталась старая. Агент честно выполнит неправильную. Обновляйте файл вместе с проектом.
Нет раздела про запреты. Описали, что делать, но не описали, чего нельзя – и агент автономно лезет туда, куда не нужно. Границы так же важны, как инструкции.
Расплывчатые формулировки. «Пиши хороший код» агенту ничего не даёт. Чем конкретнее правило, тем точнее результат – это общий принцип работы с ИИ, разобранный в гайде про промпт-инжиниринг.
Написать рабочий AGENTS.md за вечер реально, но дальше начинается главное – привычка вести проект так, чтобы агенты приносили пользу, а не правки. В сообществе EdgeLab Space мы собираем разборы и шаблоны под ИИ-агентов, а на воркшопе по запуску AI-агентов проходим путь от настройки проекта до первого работающего агента вместе – чтобы «вроде понял» превратилось в реальный результат.
FAQ
Что такое AGENTS.md простыми словами?
Это обычный текстовый файл в формате Markdown, который кладут в корень проекта. В нём вы простыми словами описываете для ИИ-агента, как собрать проект, как его протестировать, какие правила соблюдать и чего делать нельзя. Агент читает этот файл первым делом и сразу понимает контекст, поэтому не приходится объяснять одно и то же в каждом запросе.
Чем AGENTS.md отличается от CLAUDE.md?
CLAUDE.md – это файл инструкций конкретного инструмента, Claude Code. AGENTS.md задуман как общий формат: один файл читают разные ИИ-агенты, а не каждый требует свой. Грубо говоря, CLAUDE.md – «для Claude Code», AGENTS.md – «для разных агентов». Они не конфликтуют: можно держать оба, а некоторые команды используют один файл инструкций сразу для нескольких инструментов.
Где разместить AGENTS.md?
Обычно файл кладут в корень репозитория, рядом с README – туда агенты заглядывают в первую очередь. Это удобное место по умолчанию: файл сразу попадает в поле зрения инструмента, когда тот начинает работу в проекте. Жёсткого требования по расположению нет, но корень проекта – самый предсказуемый вариант.
Обязателен ли AGENTS.md?
Нет, это не обязательный файл – проект и без него соберётся. Но с ним ИИ-агент работает заметно лучше: меньше угадывает, реже ошибается в командах и не лезет туда, куда не нужно. Чем чаще вы работаете с агентами над проектом, тем больше пользы от такого файла – он экономит время на повторных объяснениях.
