Маркетинг и ИИ
Разработка

8 ответов на главные вопросы об AGENTS.md

opencode agents md
opencode agents md

AGENTS.md: что это такое, зачем нужен и как написать файл для AI-агента

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

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

Хороший AGENTS.md работает иначе. Он экономит время и человеку, и AI-агенту. Вместо того чтобы каждый раз объяснять: «у нас Python 3.12», «тесты запускаются вот так», «эти файлы не трогай», «используй существующий стиль», — правила один раз фиксируются внутри репозитория.

Разберёмся, что такое AGENTS.md, чем он отличается от README, что в него писать и как создать рабочий файл для своего проекта.

Что такое AGENTS.md

8 ответов на главные вопросы об AGENTS.md

AGENTS.md — это обычный текстовый файл в формате Markdown, предназначенный для передачи контекста и инструкций AI coding agents.

Если README.md обычно отвечает человеку на вопросы:

  • что это за проект;
  • как его установить;
  • как начать работу;
  • для чего он нужен;

то AGENTS.md объясняет AI-агенту, как именно работать с этим конкретным кодом.

Например, агенту можно сообщить:

  • какой язык и стек используются;
  • где находится основной код;
  • какими командами устанавливаются зависимости;
  • как запускать тесты;
  • какие файлы нельзя изменять;
  • какие правила именования используются;
  • что необходимо проверить перед завершением задачи.

Идея проста: агент не должен каждый раз самостоятельно угадывать правила проекта.

Представим небольшой репозиторий:

my-project/ ├── src/ ├── tests/ ├── scripts/ ├── package.json ├── README.md └── AGENTS.md

Человек открывает README.md и получает общее представление о проекте.

AI-агент читает AGENTS.md и получает рабочую инструкцию:

# Project instructions ## Setup Install dependencies: npm install ## Commands Run tests: npm test Run linter: npm run lint ## Code rules - Use TypeScript. - Do not use `any`. - Follow the existing project structure. - Do not modify files in `/legacy`. ## Before finishing Run tests and lint.

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

AGENTS.md
AGENTS.md

Зачем нужен AGENTS.md

Главная проблема AI-агентов в программировании — не способность написать код.

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

Допустим, вы просите агента добавить новую функцию.

Технически он справляется. Код работает. Но затем оказывается, что:

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

Человек-разработчик обычно узнаёт такие правила постепенно, изучая проект.

AI-агенту этот процесс можно сократить.

AGENTS.md становится точкой, где хранится минимальный набор инструкций для работы.

AGENTS.md ускоряет начало работы

Без инструкций агент может потратить значительную часть контекста на изучение репозитория.

Он открывает файлы, анализирует структуру, пытается определить используемые библиотеки и понять правила проекта.

Часть этой информации можно дать сразу.

Например:

## Architecture - API code: `/src/api` - Database layer: `/src/db` - Business logic: `/src/services` - Tests: `/tests` Do not put business logic into controllers.

Теперь агенту не нужно угадывать, куда поместить новый код.

AGENTS.md уменьшает количество ошибок

Особенно полезны явные ограничения.

Например:

## Restrictions - Do not modify database migrations. - Do not change public API signatures. - Do not add new dependencies without approval. - Do not delete tests.

Такие инструкции важнее общих фраз вроде «пиши хороший код».

AI-агент лучше работает с конкретными правилами.

8 ответов на главные вопросы об AGENTS.md

AGENTS.md делает результат более единообразным

Если над проектом работают разные агенты или разработчики используют разные инструменты, правила можно хранить в одном месте.

Например, сегодня код создаётся через Codex, завтра через другой AI coding agent, а часть задач выполняется вручную.

Вместо нескольких отдельных файлов с похожими инструкциями появляется единый источник правил.

Именно поэтому AGENTS.md часто описывают как README для AI-агентов.

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

Файлы могут находиться рядом, но их задачи разные.

Таблица отличий AGENTS.md от README.md
Таблица отличий AGENTS.md от README.md

README можно читать перед тем, как решить использовать проект.

AGENTS.md нужен в момент, когда агент уже должен что-то делать.

Например, в README может быть написано:

Это сервис для обработки заказов интернет-магазина.

А в AGENTS.md:

## Order processing Order logic is located in `/src/orders`. Do not access the database directly from controllers. Use the existing repository layer. Every change to order processing must include tests.

Оба файла полезны, но дублировать их полностью не стоит.

README объясняет проект.

AGENTS.md задаёт правила работы внутри него.

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

Жёсткого универсального шаблона нет. Один проект может уместить инструкции в 30 строк, другому понадобится несколько разделов.

Но обычно хороший AGENTS.md состоит из нескольких основных частей.

примеры agents md
примеры agents md

1. Краткое описание проекта

Не нужно переписывать весь README.

Достаточно нескольких строк:

# Project Backend service for processing customer orders. S tack: - Python 3.12 - FastAPI - PostgreSQL - SQLAlchemy

Задача раздела — быстро дать агенту базовый контекст.

2. Структура проекта

Это особенно полезно для больших репозиториев.

Например:

## Project structure /src/api HTTP endpoints /src/services Business logic /src/db Database layer /tests Tests /scripts Maintenance scripts

Можно сразу добавить ограничения:

Do not place business logic in `/src/api`.

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

3. Команды для разработки

Один из самых полезных разделов.

Агенту можно сразу сообщить, как:

  • установить зависимости;
  • запустить проект;
  • выполнить тесты;
  • проверить код;
  • собрать приложение.

Например:

## Commands Install: pip install -r requirements.txt Run tests: pytest Run lint: ruff check . Run formatter: ruff format .

Лучше писать реальные команды, а не абстрактное:

Перед завершением обязательно проверь код.

Если есть команда, укажите её.

pytest && ruff check

Для агента это гораздо полезнее.

4. Правила написания кода

Здесь фиксируются соглашения конкретного проекта.

Например:

## Code style - Use type hints. - Follow existing naming conventions. - Do not introduce new abstractions without a reason. - Prefer existing utilities over duplicate code. - Do not use `Any` unless necessary.

Не обязательно перечислять все правила языка.

AGENTS.md не должен превращаться в учебник Python или TypeScript.

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

Например, если команда использует определённый подход к работе с базой данных, это стоит указать.

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

5. Ограничения и запреты

Этот раздел часто оказывается полезнее остальных.

AI-агент может выполнить технически правильную задачу, но изменить слишком много.

Например, пользователь просит исправить одну ошибку, а агент заодно начинает рефакторить соседние модули.

Чтобы избежать этого, можно написать:

## Restrictions - Change only files related to the task. - Do not refactor unrelated code. - Do not add dependencies without approval. - Do not modify environment files. - Do not change database schema unless explicitly requested.

Такие ограничения уменьшают вероятность неожиданного результата.

6. Правила работы с тестами

Если в проекте есть тесты, лучше прямо объяснить, что от агента требуется.

Например:

## Testing For every bug fix: 1. Add or update a test. 2. Run the relevant test suite. 3. Do not remove failing tests. 4. Report which tests were executed.

Последний пункт особенно полезен.

Агент должен не просто написать:

Всё готово.

Гораздо полезнее получить:

Изменены три файла. Добавлен тест. Выполнена команда pytest tests/orders.

Так результат становится проверяемым.

Как написать AGENTS.md: готовый шаблон

Для большинства небольших проектов можно начать с такого варианта:

# AGENTS.md ## Project Brief description of the project. ## Stack - Language: - Framework: - Database: - Package manager: ## Project structure - `/src` — application code - `/tests` — tests - `/scripts` — utility scripts ## Setup Install dependencies: ```bash npm install Commands Run development server: npm run dev Run tests: npm test Run lint: npm run lint

Code rules

  • Follow existing project conventions.
  • Reuse existing utilities.
  • Do not introduce unnecessary dependencies.
  • Keep changes focused on the task.

Restrictions

  • Do not modify generated files.
  • Do not change public APIs without approval.
  • Do not modify configuration unless required.

Before finishing

  1. Run relevant tests.
  2. Run lint.
  3. Check changed files.
  4. Report what was changed.

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

Пример AGENTS.md для Python-проекта

Предположим, есть небольшой backend на FastAPI.

Структура:

project/ ├── app/ │ ├── api/ │ ├── services/ │ ├── models/ │ └── main.py ├── tests/ ├── pyproject.toml └── AGENTS.md

AGENTS.md может выглядеть так:

# AGENTS.md ## Project Python backend built with FastAPI. ## Environment - Python 3.12 - FastAPI - PostgreSQL - SQLAlchemy ## Structure - `/app/api` — HTTP endpoints - `/app/services` — business logic - `/app/models` — database models - `/tests` — tests Do not put business logic directly into API handlers. ## Commands Install dependencies: pip install -e . Run tests: pytest Run type checking: mypy app ## Code rules - Use type hints. - Follow existing async patterns. - Reuse existing database abstractions. - Add tests for new business logic. ## Restrictions - Do not change database schema without approval. - Do not add dependencies unless necessary. - Do not refactor unrelated modules. ## Completion Before finishing: 1. Run relevant tests. 2. Check formatting. 3. Summarize changed files.

Такой файл уже даёт агенту значительно больше полезного контекста, чем простой запрос:

Добавь новую функцию.

Где размещать AGENTS.md

Самый очевидный вариант — положить файл в корень репозитория:

project/ ├── AGENTS.md ├── README.md ├── src/ └── tests/

Но в больших проектах одного файла может быть недостаточно.

Например:

project/ ├── AGENTS.md ├── backend/ │ ├── AGENTS.md │ └── src/ ├── frontend/ │ ├── AGENTS.md │ └── src/ └── infrastructure/

Корневой файл может содержать общие правила проекта.

Локальный AGENTS.md — правила конкретной части.

Например, в корне:

Use existing project conventions.

Run tests before finishing.

Do not modify infrastructure without approval.

А внутри frontend:

Use React.

Do not use class components.

Run:

npm test

npm run lint

Это удобнее, чем создавать один файл на тысячу строк.

Главная ошибка — превращать AGENTS.md в огромную документацию

Возникает соблазн описать вообще всё:

  • историю проекта;
  • архитектурные решения пятилетней давности;
  • полный список зависимостей;
  • правила каждого модуля;
  • описание каждой функции.

В результате AGENTS.md становится слишком большим.

Агенту приходится тратить контекст на инструкции, которые могут не иметь отношения к текущей задаче.

Лучше соблюдать простой принцип:

В AGENTS.md должна находиться информация, которая помогает агенту принять правильное решение прямо сейчас.

Если задача касается API, агенту нужна структура API.

Если задача касается frontend, полезны правила frontend.

Если какая-то информация не влияет на работу, её не обязательно добавлять.

Хороший AGENTS.md — это не самая полная документация проекта.

Это наиболее полезная инструкция для выполнения работы.

Какие ошибки чаще всего встречаются

файл agents md
файл agents md

Слишком общие инструкции

Плохой вариант:

Write clean code. Follow best practices. Be careful.

Что именно считается чистым кодом?

Какие практики используются?

Что нельзя делать?

Агент вынужден решать самостоятельно.

Лучше:

Use existing utilities. Do not create new database access layers. Run pytest before finishing.

Конкретные инструкции работают лучше.

Дублирование README

Если в AGENTS.md полностью скопировать README, пользы немного.

Вместо этого стоит оставить только рабочий контекст.

Устаревшие команды

Это одна из самых неприятных проблем.

В файле указано:

npm test

А тесты давно запускаются через другую команду.

Агент честно следует инструкции и получает ошибку.

Поэтому AGENTS.md нужно обновлять вместе с проектом.

Слишком много запретов

Если написать двадцать пунктов:

Do not change this. Do not change that. Never touch this. Never refactor anything.

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

Ограничения должны защищать важные части проекта, а не запрещать любую работу.

Нужно ли создавать AGENTS.md для маленького проекта

Не всегда.

Если у вас небольшой скрипт из нескольких файлов и AI-агент используется один раз, отдельный файл может оказаться лишним.

Но AGENTS.md начинает приносить пользу, когда:

  • проект развивается;
  • задачи повторяются;
  • с кодом регулярно работают AI-агенты;
  • в проекте есть важные правила;
  • агентам постоянно приходится объяснять одно и то же;
  • несколько разработчиков используют разные инструменты.

Хороший тест очень простой.

Если вы регулярно пишете агенту:

Сначала посмотри структуру проекта.

Тесты запускаются вот этой командой.

Этот файл не трогай.

Используй существующий сервис.

— эти инструкции уже кандидаты для AGENTS.md.

AGENTS.md — это не волшебная кнопка

Важно понимать: сам по себе файл не превращает AI-агента в опытного разработчика.

Он всё ещё может ошибаться.

Инструкции могут быть неправильно поняты.

Тесты могут не покрывать проблему.

Агент может предложить решение, которое выглядит убедительно, но ломает бизнес-логику.

Поэтому AGENTS.md лучше рассматривать как способ уменьшить количество повторяющихся ошибок.

Он помогает передать агенту то, что уже знает команда.

- Архитектуру.

- Ограничения.

- Команды.

- Правила.

И ожидаемый результат.

Чем чаще AI-агент работает с одним и тем же проектом, тем заметнее становится эффект.

Итог

AGENTS.md — это файл с рабочими инструкциями для AI coding agents. Он помогает агенту быстрее понять проект и работать в рамках существующих правил.

Минимальный AGENTS.md обычно должен содержать:

  1. краткое описание проекта;
  2. технологический стек;
  3. структуру директорий;
  4. команды установки и запуска;
  5. команды тестирования и проверки;
  6. правила написания кода;
  7. ограничения;
  8. требования перед завершением задачи.

Не нужно писать огромную энциклопедию.

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

Если одно и то же правило приходится писать AI-агенту второй или третий раз, скорее всего, ему уже пора появиться в AGENTS.md.

Источники:

Официальный сайт стандарта AGENTS.md

Официальные ресурсы и материалы по ИИ

Спецификация в репозитории Agentic AI Foundation

33
11