# Что такое AGENTS.md и как написать свой в 2026

ИИ-агенты кода всё чаще приходят в проект, не зная о нём ничего: как его собрать, какими командами тестировать, что трогать нельзя. Объяснять это каждому агенту заново – долго. Чтобы не повторяться, договорились о едином файле с инструкциями – AGENTS.md.

Если коротко: **AGENTS.md – это обычный Markdown-файл в корне репозитория, в котором вы простыми словами описываете проект для ИИ-агентов: как его собрать, как протестировать, какие правила соблюдать и чего делать нельзя.**

Главная идея – это общий формат. Один и тот же файл читают разные ИИ-инструменты, а не каждый свой. Дальше разберём, что в нём пишут, чем он отличается от CLAUDE.md и как собрать свой по шагам.

## Содержание

- [Что такое AGENTS.md простыми словами](#что-такое-agentsmd-простыми-словами)
- [Чем AGENTS.md отличается от CLAUDE.md](#чем-agentsmd-отличается-от-claudemd)
- [Шаг 1: Опишите проект в двух абзацах](#шаг-1-опишите-проект-в-двух-абзацах)
- [Шаг 2: Дайте команды сборки и тестов](#шаг-2-дайте-команды-сборки-и-тестов)
- [Шаг 3: Зафиксируйте конвенции](#шаг-3-зафиксируйте-конвенции)
- [Шаг 4: Обозначьте границы и запреты](#шаг-4-обозначьте-границы-и-запреты)
- [Пример готового AGENTS.md](#пример-готового-agentsmd)
- [Типичные ошибки](#типичные-ошибки)
- [FAQ](#faq)

## Что такое AGENTS.md простыми словами

Представьте, что в команду пришёл новый исполнитель – толковый, но про ваш проект не знает ничего. Чтобы он сразу начал приносить пользу, вы пишете ему короткую памятку: вот так у нас собирается проект, вот этими командами проверяется, так мы оформляем код, а вот сюда лезть не надо. AGENTS.md – ровно такая памятка, только для ИИ-агента.

Технически это простой текстовый файл в формате Markdown. Чаще всего его кладут в корень репозитория, рядом с README. Когда ИИ-агент начинает работу в проекте, он первым делом читает этот файл и сразу понимает контекст – не приходится объяснять одно и то же в каждом запросе.

Важно понимать, что AGENTS.md – это договорённость, а не жёсткий технический формат с обязательными полями. Внутри – обычный Markdown: заголовки, списки, блоки кода. Вы сами решаете, какие разделы включить. Есть привычный набор, который встречается чаще всего: обзор проекта, команды сборки и тестов, правила оформления кода, границы и запреты. Но строгой спецификации с обязательными именами полей нет – пишите так, как удобно агенту читать.

Если вы уже работаете с ИИ-агентами кода и хотите глубже понять саму идею автономных помощников, посмотрите разбор [что такое ИИ-агент](/guides/chto-takoe-ii-agent/) – AGENTS.md как раз и нужен, чтобы такой агент быстрее входил в курс дела.

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

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

CLAUDE.md – это файл инструкций конкретного инструмента, Claude Code от Anthropic. Claude Code читает именно его и держит правила проекта перед глазами в каждой задаче. Это удобно, но привязано к одному инструменту: другой агент про CLAUDE.md может ничего не знать. Подробно его формат разобран в гайде про [файл памяти CLAUDE.md](/guides/claudemd-guide/), а все материалы по самому инструменту – в [разделе про Claude Code](/claude-code/).

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

| Параметр | AGENTS.md | CLAUDE.md |
|---|---|---|
| Назначение | Общий файл инструкций для разных агентов | Файл инструкций конкретного инструмента |
| Кто читает | Несколько ИИ-инструментов, поддерживающих формат | В первую очередь Claude Code |
| Формат | Обычный Markdown, гибкая структура | Обычный Markdown, формат Claude Code |
| Когда удобен | Хотите один файл на разные инструменты | Работаете в основном в Claude Code |

На практике эти файлы не конфликтуют. Если вы работаете в Claude Code, у вас может быть CLAUDE.md под него, а AGENTS.md – как общий файл для остальных агентов. Некоторые команды идут проще: держат один файл инструкций и подключают его к нескольким инструментам сразу, чтобы не дублировать правила. Какой путь выбрать – зависит от того, сколько разных агентов крутится в вашем проекте.

## Шаг 1: Опишите проект в двух абзацах

Начните с обзора – короткого ответа на вопрос «что это за проект». Агент должен за пару предложений понять, с чем имеет дело: что это, на чём написано, как устроено в общих чертах.

Не нужно пересказывать всю архитектуру. Достаточно дать опору: язык и стек, ключевые папки, точка входа. Это контекст, от которого агент будет отталкиваться дальше.

```markdown
## Обзор проекта

Веб-приложение на Next.js (TypeScript). Фронтенд в `app/`,
серверная логика в `api/`, общие компоненты в `components/`.
База данных – PostgreSQL, доступ через Prisma.
```

## Шаг 2: Дайте команды сборки и тестов

Это самый ценный раздел. Агент должен знать, какими командами проект собирается, запускается и проверяется – иначе он будет угадывать, а угадывает он не всегда верно.

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

```markdown
## Команды

- Установка: `npm install`
- Запуск дев-сервера: `npm run dev`
- Сборка: `npm run build`
- Тесты: `npm test`
- Линтер: `npm run lint`
```

Главное правило этого раздела – команды должны быть рабочими. Проверьте их сами перед тем, как класть в файл: если команда устарела, агент честно выполнит неправильную и потратит время впустую.

## Шаг 3: Зафиксируйте конвенции

Конвенции – это про то, как у вас принято писать код и вести проект. Здесь вы экономите себе бесконечные правки: один раз описали стиль – и агент следует ему, а не навязывает свой.

Опишите то, что для вас важно: стиль именования, формат отступов, подход к импортам, требования к тестам, язык комментариев. Не обязательно перечислять всё – вынесите то, что чаще всего приходится поправлять руками.

```markdown
## Конвенции

- TypeScript strict, без `any`
- Именование компонентов – PascalCase, функций – camelCase
- Каждый новый модуль сопровождается тестом
- Комментарии в коде – на английском
```

Если в проекте используется ИИ-агент с поддержкой внешних инструментов, в конвенциях полезно упомянуть и это – например, какие [MCP-серверы](/guides/mcp-servers-claude-code/) подключены и для чего, чтобы агент понимал доступный ему набор возможностей.

## Шаг 4: Обозначьте границы и запреты

Последний и недооценённый раздел – чего делать нельзя. Агент действует автономно, поэтому явные запреты страхуют от неприятных сюрпризов.

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

```markdown
## Границы

- Не трогать файлы в `migrations/` без явной задачи
- Не запускать `git push` и операции с продакшеном
- Секреты и `.env` не коммитить и не выводить в логи
```

## Пример готового AGENTS.md

Соберём всё вместе. Вот компактный AGENTS.md, который можно взять за основу и адаптировать под свой проект – коротко, по делу, без воды.

```markdown
# 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 – не документация на сто страниц. Если вписать туда всё подряд, агент утонет в воде и пропустит важное. Держите файл коротким и конкретным: команды, правила, границы.

**Устаревшие команды.** Самая обидная ошибка: команда сборки изменилась, а в файле осталась старая. Агент честно выполнит неправильную. Обновляйте файл вместе с проектом.

**Нет раздела про запреты.** Описали, что делать, но не описали, чего нельзя – и агент автономно лезет туда, куда не нужно. Границы так же важны, как инструкции.

**Расплывчатые формулировки.** «Пиши хороший код» агенту ничего не даёт. Чем конкретнее правило, тем точнее результат – это общий принцип работы с ИИ, разобранный в гайде про [промпт-инжиниринг](/guides/prompt-inzhiniring/).

Написать рабочий AGENTS.md за вечер реально, но дальше начинается главное – привычка вести проект так, чтобы агенты приносили пользу, а не правки. В сообществе EdgeLab Space мы собираем разборы и шаблоны под ИИ-агентов, а на [воркшопе по запуску AI-агентов](https://go.edgelab.space/blog-ws) проходим путь от настройки проекта до первого работающего агента вместе – чтобы «вроде понял» превратилось в реальный результат.

## 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?

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