Как писать файл AGENTS.md на примере Codex

Что такое AGENTS.md и зачем он нужен в Codex?

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

Когда AI coding agent работает с вашим проектом, ему нужно быстро разобраться в архитектуре, стиле кодирования, используемых библиотеках и бизнес-логике. Без четких инструкций агент может генерировать код, который технически корректен, но не соответствует принятым в проекте соглашениям. AGENTS.md решает эту проблему. Он предоставляет агенту структурированную информацию о том, как именно нужно работать с кодовой базой.

Файл agents md особенно полезен в крупных проектах, где есть специфические требования к архитектуре, naming conventions или паттернам проектирования. Вместо того чтобы агент изучал весь код и пытался вывести правила самостоятельно, он получает готовую инструкцию.

Роль AGENTS.md в работе AI coding agent

ИИ-агент использует содержимое файла agents md как контекстную информацию при генерации кода. Это влияет на все аспекты его работы: от выбора названий переменных до принятия архитектурных решений.

Основные задачи, которые решает файл:

Например, если в проекте все API-запросы должны проходить через единый слой абстракции, а не напрямую через fetch или axios, это нужно явно указать в codex agents md. Иначе агент может сгенерировать код, который работает, но нарушает архитектурные принципы проекта.

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

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

README.md и AGENTS.md выполняют разные функции, хотя оба находятся в корне проекта и описывают его особенности.

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

Файл agents md, напротив, создан для машинного чтения. Его аудитория – нейросети, которые генерируют или модифицируют код. Здесь важна не презентация проекта, а конкретные технические инструкции:

Ключевое различие – в уровне детализации и формате подачи. README объясняет «что» и «зачем», AGENTS.md – «как именно». Если README может содержать маркетинговые описания и мотивационные блоки, то файл agents md должен быть максимально сухим и структурированным.

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

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

Где размещать AGENTS.md в проекте

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

AGENTS.md в корне проекта

Базовый файл AGENTS.md размещают в корневой директории репозитория — обычно на одном уровне с README.md, package.json, pyproject.toml, requirements.txt или другими основными файлами проекта. Это главный источник правил, который описывает проект целиком.

Важно использовать точное имя файла: AGENTS.md, в верхнем регистре и во множественном числе. Варианты вроде agents.md или agent.md могут не распознаваться конкретным инструментом или по-разному работать на файловых системах с чувствительностью к регистру.

В корневой AGENTS.md включайте информацию, которая относится ко всему проекту:

Корневой файл AGENTS.md задаёт базовый контекст для всего репозитория. Если для конкретной папки нет более точных инструкций, агент будет опираться на общие правила из корня проекта.

AGENTS.md во вложенных папках

Когда проект разрастается, одного файла в корне часто становится недостаточно. Вложенные AGENTS.md помогают описать правила для конкретного модуля, приложения, пакета или микросервиса.

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

В локальных файлах описывайте то, что важно именно для этой части проекта:

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

Пример структуры проекта с AGENTS.md

Вот как может выглядеть типичный проект с несколькими файлами AGENTS.md:

my-project/
├── AGENTS.md                    # Общие правила, архитектура, команды
├── README.md
├── package.json
├── backend/
│   ├── AGENTS.md                # Специфика серверной части
│   ├── src/
│   │   ├── controllers/
│   │   ├── models/
│   │   └── services/
│   └── tests/
├── frontend/
│   ├── AGENTS.md                # Правила для клиентского кода
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   └── utils/
│   └── public/
├── api/
│   ├── AGENTS.md                # Описание API-контрактов
│   └── openapi.yaml
└── docs/
    ├── AGENTS.md                # Инструкции по работе с документацией
    └── architecture.md

Корневой AGENTS.md содержит общую информацию: проект устроен как монорепозиторий, backend написан на Node.js, frontend — на React, зависимости устанавливаются через единый пакетный менеджер, а коммиты должны следовать формату Conventional Commits.

backend/AGENTS.md уточняет правила серверной части: используется Express.js, база данных — PostgreSQL с Prisma ORM, все новые роуты должны сопровождаться тестами, а миграции нельзя редактировать вручную после применения.

frontend/AGENTS.md добавляет правила клиентского приложения: компоненты пишутся на TypeScript, используются функциональные компоненты и хуки, стили оформляются через CSS Modules, перед коммитом обязательна проверка типов.

api/AGENTS.md объясняет правила API-слоя: все эндпоинты должны быть описаны в OpenAPI-спецификации, изменения контрактов требуют обновления документации, а версионирование API выполняется через URL.

docs/AGENTS.md фиксирует правила документации: архитектурные изменения нужно отражать в architecture.md, примеры команд должны быть проверяемыми, а устаревшие разделы необходимо обновлять вместе с изменением кода.

Такая структура помогает ИИ-агенту быстро находить нужный контекст. Работая с backend, он использует общие правила из корня и уточнения из backend/AGENTS.md. Переключаясь на frontend, он применяет уже другой локальный контекст — frontend/AGENTS.md.

Если в проекте есть микросервисы, каждый сервис может иметь собственный AGENTS.md:

services/
├── auth-service/
│   ├── AGENTS.md                # Правила сервиса авторизации
│   └── src/
├── payment-service/
│   ├── AGENTS.md                # Правила платёжного сервиса
│   └── src/
└── notification-service/
    ├── AGENTS.md                # Правила сервиса уведомлений
    └── src/

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

Основные разделы AGENTS.md

Файл AGENTS.md — это инструкция для ИИ-агента, который будет работать с вашим кодом: читать проект, вносить изменения, запускать проверки и объяснять результат. Это не замена README.md, а отдельный файл с правилами именно для автоматизированной работы с репозиторием.

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

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

Начните с того, что делает ваш проект. Опишите назначение в 2–3 предложениях — коротко и по делу. ИИ-агенту важно понимать не только техническую часть, но и бизнес-логику: так он будет предлагать решения, которые соответствуют целям продукта, а не просто выглядят технически корректными.

Хорошее описание отвечает на три вопроса:

Пример:

# О проекте

Это веб-приложение для управления задачами команды разработки.
Пользователи создают задачи, назначают исполнителей, отслеживают прогресс
и получают уведомления о дедлайнах. Основная аудитория — небольшие
IT-команды до 20 человек.

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

Область действия и приоритет инструкций

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

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

# Область действия

Этот AGENTS.md применяется ко всему репозиторию.

Для отдельных частей проекта используются дополнительные инструкции:
- `/frontend/AGENTS.md` — правила для React-приложения
- `/backend/AGENTS.md` — правила для API и работы с базой данных
- `/infra/AGENTS.md` — правила для Docker, CI/CD и облачной инфраструктуры

Если инструкции конфликтуют, используй более близкий к изменяемому файлу AGENTS.md.
Явная инструкция пользователя в чате имеет приоритет над правилами из файла.

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

Технологический стек

Перечислите языки, фреймворки, библиотеки и инструменты, которые используете. Указывайте версии — это помогает ИИ-агенту не предлагать устаревшие API, несовместимые зависимости или подходы, которые не подходят вашему проекту.

Структурируйте информацию по категориям:

# Технологический стек

**Backend:**
- Node.js 18.x
- Express 4.18
- PostgreSQL 15
- Prisma ORM 5.x

**Frontend:**
- React 18.2
- TypeScript 5.x
- Vite 4.x
- TanStack Query 4.x

**Инфраструктура:**
- Docker
- GitHub Actions
- AWS S3 для хранения файлов

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

Архитектура и структура директорий

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

Начните с общей структуры папок:

# Структура проекта

/src
  /api          # REST API endpoints
  /components   # React-компоненты
  /hooks        # Кастомные хуки
  /lib          # Утилиты, клиенты API и хелперы
  /services     # Бизнес-логика
  /types        # TypeScript-типы
  /db           # Миграции и схемы БД

Затем объясните ключевые принципы:

## Архитектурные принципы

- Используем feature-based структуру: каждая фича содержит свои компоненты,
  хуки, типы и тесты.
- Бизнес-логика изолирована в сервисах; компоненты отвечают за отображение
  и пользовательское взаимодействие.
- API-роуты следуют REST-конвенциям.
- Состояние сервера управляется через TanStack Query.
- Глобальное клиентское состояние хранится в React Context только там,
  где это действительно необходимо.

Если применяете конкретные паттерны — Repository, Factory, Observer, CQRS, Feature-Sliced Design, Clean Architecture — укажите это явно. Тогда агент будет следовать тем же подходам при генерации нового кода.

Команды для запуска и разработки

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

# Команды

## Установка
npm install

## Разработка
npm run dev          # Запуск dev-сервера
npm run db:migrate   # Применить миграции БД
npm run db:seed      # Заполнить БД тестовыми данными

## Сборка и деплой
npm run build        # Production-сборка
npm run preview      # Предпросмотр production-сборки
npm run deploy       # Деплой на staging

## Тестирование
npm test             # Запуск всех тестов
npm run test:watch   # Тесты в watch-режиме
npm run test:e2e     # E2E-тесты

## Проверки перед завершением задачи
npm run lint         # ESLint
npm run typecheck    # Проверка типов TypeScript
npm run build        # Проверка production-сборки

Добавьте комментарии к неочевидным и потенциально опасным командам. Если npm run db:reset удаляет данные, это нужно указать отдельно. Если команда требует переменных окружения, тестовой базы или Docker, тоже напишите об этом в AGENTS.md.

## Опасные команды

- `npm run db:reset` полностью очищает локальную базу данных.
  Не запускать без явного разрешения пользователя.
- `npm run deploy` деплоит приложение на staging.
  Не запускать автоматически после правок.

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

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

# Стандарты кода

## Именование

- Компоненты: PascalCase (`UserProfile.tsx`)
- Функции и переменные: camelCase (`getUserData`)
- Константы: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)
- Файлы с хуками: префикс `use` (`useAuth.ts`)
- Типы и интерфейсы: PascalCase (`User`, `UserRole`)

## Форматирование

- Используем Prettier с конфигом из `.prettierrc`.
- Максимальная длина строки: 100 символов.
- Отступы: 2 пробела.
- Точка с запятой обязательна.

## TypeScript

- Не использовать `any`, если можно описать тип точнее.
- Для неизвестных данных использовать `unknown` и выполнять проверку перед использованием.
- Публичные функции должны иметь явные типы аргументов и возвращаемого значения.
- Для объектов предпочитать `interface`, для union и utility-типов — `type`.

Укажите, какие линтеры используются и как их запускать:

## Линтинг

Проект использует ESLint с конфигом `@typescript-eslint/recommended`.

Перед коммитом запускается автоматическая проверка через Husky.
Исправить ошибки линтера: `npm run lint:fix`.
Проверить типы: `npm run typecheck`.

Если в проекте есть спорные соглашения, формулируйте их прямо. Например: «не использовать default export», «не создавать barrel-файлы», «не выносить бизнес-логику в React-компоненты». Для агента такие детали важнее, чем абстрактная просьба «писать чистый код».

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

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

# Тестирование

## Фреймворки

- Vitest для unit- и integration-тестов.
- Playwright для E2E.
- Testing Library для тестирования React-компонентов.

## Требования

- Минимальное покрытие: 80% для сервисов и утилит.
- Каждый API-эндпоинт должен иметь integration-тест.
- Критичные пользовательские сценарии должны быть покрыты E2E-тестами.
- При исправлении бага сначала добавляй тест, который воспроизводит проблему.

## Структура тестов

Тесты располагаются рядом с тестируемым кодом:
/src
  /services
    userService.ts
    userService.test.ts

## Соглашения

- Используем `describe` для группировки связанных тестов.
- Названия тестов начинаются с `should` и описывают ожидаемое поведение.
- Моки создаём через `vi.mock()`, избегаем ручных моков без необходимости.
- Не тестируем приватную реализацию, если поведение можно проверить через публичный API.

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

## Если тесты не запускаются

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

Рабочий процесс и формат результата

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

# Рабочий процесс

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

## Итоговый ответ

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

Для командной разработки можно добавить правила по pull request, commit message и changelog. Это помогает агенту не только писать код, но и готовить изменения в формате, привычном для вашей команды.

## Pull request

- Название PR: `[<project>] Краткое описание изменения`.
- В описании PR укажи проблему, решение и список проверок.
- Если изменение влияет на пользователя, добавь запись в `CHANGELOG.md`.
- Не объединяй несвязанные изменения в один PR.

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

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

# Ограничения

## Не изменять без явного разрешения

- `/src/config/constants.ts` — конфигурация согласована с DevOps.
- `/prisma/schema.prisma` — изменения схемы БД только через миграции.
- `/.github/workflows/*` — CI/CD настроен и протестирован.
- `package-lock.json` — изменять только вместе с обоснованным изменением зависимостей.

## Не использовать

- `class`-компоненты в React — проект использует функциональные компоненты.
- `axios` — используем встроенный `fetch` с обёрткой из `/lib/api.ts`.
- Redux для глобального состояния — используем Context API и TanStack Query.
- `eval()` и конструктор `Function()`.

## Не добавлять зависимости без согласования

Перед добавлением новой библиотеки проверь:
- есть ли альтернатива в текущем стеке;
- активно ли поддерживается библиотека;
- какой размер бандла она добавит;
- не создаёт ли она конфликтов с текущими зависимостями.

## Безопасность

- Не добавлять в репозиторий `.env` файлы.
- Не хранить API-ключи, токены и пароли в коде.
- Не выводить секреты в логи.
- Все пользовательские данные валидировать через Zod-схемы.
- Перед работой с персональными данными проверить требования проекта к privacy и compliance.

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

Лучшие практики написания AGENTS.md

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

Пишите конкретно, а не абстрактно

ИИ-агенту не стоит оставлять место для догадок. Расплывчатая инструкция вроде «запускай тесты перед коммитом» звучит понятно для человека, но для агента в ней не хватает действия: какие именно тесты запускать, из какой директории и какой результат считать успешным. Лучше указывать точную команду:

npm run test:unit && npm run test:integration

То же самое относится к путям, конфигурациям и соглашениям. Вместо фразы «конфигурация находится в корне проекта» напишите явно:

Конфигурация: ./config/app.config.js
Переменные окружения: .env.local

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

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

Ветки создаём по шаблону:
feature/user-auth
fix/payment-validation
refactor/api-client

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

Держите файл актуальным

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

Переименовали скрипт в package.json — обновите AGENTS.md. Добавили новый микросервис — опишите его структуру, команды запуска и проверки. Изменили процесс сборки, миграций или деплоя — отразите это в инструкциях для агента.

Простой способ не забывать про актуализацию — добавить AGENTS.md в чеклист перед мерджем крупных изменений. Если меняется архитектура, API, CI/CD, структура директорий или набор обязательных проверок, файл должен измениться тоже.

Можно добавить в конец файла дату последнего обновления:

Последнее обновление: 2026-04-30

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

Не перегружайте файл лишней информацией

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

Включайте только то, что помогает выполнять задачи:

Не включайте:

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

Добавляйте проверочные команды

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

Например, после изменения кода:

# Проверка линтера
npm run lint

# Проверка типов
npm run type-check

# Запуск тестов
npm run test

После изменения конфигурации:

# Проверка синтаксиса Docker Compose
docker compose config

# Проверка доступности API
curl -fsS http://localhost:3000/health

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

Можно добавить раздел «Чеклист перед коммитом»:

Перед коммитом выполни:
1. npm run lint
2. npm run test
3. npm run build
4. git status --short
5. Проверь, что в коммит не попали секреты, токены и .env-файлы

Явно описывайте ограничения и запреты

AGENTS.md должен объяснять не только то, что агенту можно делать, но и то, чего делать нельзя. Это снижает риск случайных разрушительных действий: удаления миграций, запуска деплоя, изменения публичного API или записи секретов в репозиторий.

Ограничения лучше писать в форме конкретных правил:

Запрещено:
- удалять или переписывать существующие миграции без отдельного согласования
- запускать npm run deploy без явного разрешения человека
- добавлять реальные токены, пароли и ключи API в код, фикстуры или .env-файлы
- менять публичный API без обновления docs/api.md
- устанавливать новые production-зависимости без объяснения причины

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

Разделяйте инструкции по зонам ответственности

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

Пример структуры внутри одного файла:

## Backend
- Запуск: `npm run dev:backend`
- Тесты: `npm run test:backend`
- Миграции: `npm run migrate`

## Frontend
- Запуск: `npm run dev:frontend`
- Сборка: `npm run build:frontend`
- Тесты: `npm run test:e2e`

## База данных
- Подключение: PostgreSQL на localhost:5432
- Схема: `./db/schema.sql`
- Сиды: `npm run db:seed`

## Инфраструктура
- Docker Compose: `docker compose up`
- Логи: `docker compose logs -f`

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

В монорепозитории можно использовать несколько файлов:

AGENTS.md
services/
  payments/
    AGENTS.md
  search/
    AGENTS.md
packages/
  ui/
    AGENTS.md

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

Можно добавить содержание для навигации внутри длинного файла:

## Содержание
- [Backend](#backend)
- [Frontend](#frontend)
- [База данных](#база-данных)
- [Инфраструктура](#инфраструктура)

Примеры AGENTS.md для разных проектов

Готовые примеры помогают быстрее понять, как структурировать файл AGENTS.md под конкретный стек и задачи. Ниже – три шаблона для типичных сценариев: минимальный Python-проект, backend на FastAPI и frontend-приложение. Их лучше воспринимать не как универсальные правила, а как основу: команды, версии и ограничения нужно сверять с конкретным репозиторием.

Минимальный AGENTS.md для Python-проекта

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

# AGENTS.md

## Назначение проекта
- Небольшая Python-утилита для обработки данных и запуска из командной строки.
- Основная точка входа: `main.py`.

## Область действия
- Эти инструкции применяются ко всему репозиторию.
- Если в подпапке есть свой `AGENTS.md`, он уточняет правила для этой подпапки.

## Стек
- Python 3.11+ (точную версию см. в `.python-version` или `pyproject.toml`)
- requests, pandas
- pytest для тестов

## Запуск
```bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -r requirements.txt
python main.py
```

## Стиль кода
- Следуем PEP 8.
- Максимальная длина строки – 88 символов, если проект использует Black.
- Добавляем type hints там, где они улучшают читаемость.
- Не добавляем новые зависимости без необходимости. Если зависимость нужна, кратко объясняем причину.

## Тесты и проверки
- Запуск тестов: `python -m pytest`
- Покрытие: `python -m pytest --cov=.`, если в проекте установлен `pytest-cov`
- Новые функции покрываем тестами перед передачей результата.

## Правила для агента
- Вноси минимальные изменения, необходимые для задачи.
- Не меняй публичное поведение утилиты без явного запроса.
- Не коммить секреты, токены, файлы `.env` и локальные артефакты.
- Не запускай разрушительные команды вроде `rm -rf` без отдельного подтверждения.

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

AGENTS.md для FastAPI-проекта

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

# AGENTS.md

## Назначение проекта
- Асинхронный REST API на FastAPI.
- Бизнес-логика находится в сервисном слое, роуты отвечают за HTTP-интерфейс.
- Перед изменением публичных эндпоинтов проверяй схемы, тесты и документацию.

## Область действия
- Эти инструкции применяются ко всему backend-проекту.
- Если внутри отдельного модуля есть свой `AGENTS.md`, он имеет приоритет для файлов этого модуля.

## Стек
- Python 3.11+ (точную версию см. в `pyproject.toml`)
- FastAPI, Pydantic v2
- SQLAlchemy 2.x, asyncpg
- PostgreSQL
- Redis для кеша
- Alembic для миграций
- pytest + pytest-asyncio
- Ruff, Black, isort для проверки и форматирования

## Структура проекта
```
src/
├── api/          # Роуты, зависимости и HTTP-эндпоинты
├── models/       # SQLAlchemy-модели
├── schemas/      # Pydantic-схемы запросов и ответов
├── services/     # Бизнес-логика
├── db/           # Подключение к БД, сессии, транзакции
├── cache/        # Работа с Redis
└── config.py     # Настройки через pydantic-settings
tests/
├── unit/         # Unit-тесты
└── integration/  # Интеграционные тесты с тестовой БД
```

## Запуск локально
```bash
# Создать локальный файл окружения
cp .env.example .env

# Поднять PostgreSQL и Redis через Docker
docker compose up -d

# Установить зависимости
poetry install

# Применить миграции
poetry run alembic upgrade head

# Запустить сервер разработки
poetry run uvicorn src.main:app --reload
```

## Переменные окружения
- Шаблон переменных хранится в `.env.example`.
- Локальный файл `.env` не коммитим.
- Новые переменные добавляем одновременно в `.env.example`, конфиг и документацию.

## Миграции
- Создать миграцию: `poetry run alembic revision --autogenerate -m "описание"`
- Применить миграции: `poetry run alembic upgrade head`
- Откатить последнюю миграцию: `poetry run alembic downgrade -1`
- Не редактируй уже примененные миграции без явного запроса. Для изменений создавай новую миграцию.

## Стиль кода
- Black для форматирования.
- isort для сортировки импортов.
- Ruff для линтинга.
- Типизация обязательна для публичных функций, методов сервисов и зависимостей FastAPI.
- Не смешивай HTTP-логику и бизнес-логику: роуты должны быть тонкими.

## Команды проверки
```bash
poetry run ruff check .
poetry run black --check .
poetry run isort --check-only .
poetry run pytest
```

## Тесты
- Unit-тесты пишем для сервисов и утилит.
- Интеграционные тесты используют тестовую БД. Настройки см. в `conftest.py`.
- Моки для внешних HTTP API создаем через `respx`.
- При изменении контракта API обновляем тесты схем и эндпоинтов.

## Правила работы с БД
- Все запросы выполняем через async-сессии.
- Не используем синхронные SQLAlchemy-вызовы внутри async-кода.
- Не вызываем `session.commit()` в сервисах. Коммит выполняется в роуте, dependency или unit-of-work-слое.
- Индексы, constraints и изменения схемы добавляем через миграции, а не только в коде моделей.

## Правила для агента
- Не меняй публичный API, формат ответов или схему БД без явного требования в задаче.
- Не добавляй новые production-зависимости без объяснения.
- Не раскрывай секреты из `.env`, логов и конфигов.
- После изменения поведения обновляй тесты и, если нужно, документацию API.

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

AGENTS.md для frontend-проекта

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

# AGENTS.md

## Назначение проекта
- Frontend-приложение на Next.js с App Router.
- Компоненты должны быть переиспользуемыми, типизированными и покрытыми тестами там, где есть логика.
- UI-изменения должны сохранять адаптивность и доступность.

## Область действия
- Эти инструкции применяются ко всему frontend-проекту.
- Если в подпапке есть свой `AGENTS.md`, используй его как уточнение для этой части проекта.

## Стек
- Next.js с App Router (точную версию см. в `package.json`)
- TypeScript в strict-режиме
- Tailwind CSS
- Zustand для локального стейт-менеджмента
- TanStack Query для клиентской работы с API
- Vitest + Testing Library
- MSW для моков API в тестах

## Структура проекта
```
src/
├── app/              # Роуты и layouts App Router
├── components/       # Переиспользуемые компоненты
│   ├── ui/           # Базовые UI-элементы: Button, Input, Modal
│   └── features/     # Фичевые компоненты: формы, карточки, виджеты
├── lib/              # Утилиты, API-клиенты, хелперы
├── hooks/            # Кастомные React-хуки
├── store/            # Zustand-сторы
├── types/            # Общие TypeScript-типы
└── test/             # Тестовые утилиты и моки
```

## Команды
```bash
# Установка зависимостей
npm install

# Разработка
npm run dev

# Линтинг
npm run lint

# Проверка типов
npm run typecheck

# Тесты
npm run test

# Production-сборка
npm run build
```

## Стиль кода
- Используем ESLint и Prettier.
- Компоненты именуем в PascalCase.
- Файлы компонентов: `ComponentName.tsx`.
- Хуки начинаются с `use`.
- Props типизируем явно через `type` или `interface`, придерживаясь существующего стиля проекта.
- Общие типы экспортируем из `types/index.ts`, если такой паттерн уже используется.

## Компоненты
- Используем функциональные компоненты.
- Директиву `use client` добавляем только там, где нужны state, effects, browser API или клиентские обработчики.
- Для UI-компонентов поддерживаем prop `className` и объединяем классы через `cn()` из `lib/utils`.
- Избегаем inline-стилей, если их можно заменить Tailwind-классами.
- Для интерактивных элементов проверяем доступность: keyboard navigation, focus states, aria-атрибуты при необходимости.

## Работа с API
- Клиентские запросы выполняем через TanStack Query.
- API-клиенты и fetcher-функции хранятся в `lib/api.ts` или рядом с фичей, если так устроен проект.
- Типы ответов API описываем в `types/api.ts`.
- Не дублируем raw `fetch`-вызовы в компонентах, если уже есть общий API-клиент.
- Для ошибок и loading-состояний используем существующие UI-паттерны проекта.

## Стили
- Основной инструмент стилизации – Tailwind CSS.
- Кастомные цвета, размеры и breakpoints настраиваем в `tailwind.config.ts`.
- CSS-модули не добавляем, если проект уже не использует их как основной паттерн.
- Не меняем глобальные стили без проверки влияния на существующие страницы.

## Тесты
- Unit-тесты пишем для утилит, хуков и сложной бизнес-логики.
- Компонентные тесты пишем через Testing Library.
- Моки для API создаем через MSW.
- Для пользовательских сценариев проверяем видимое поведение, а не внутреннюю реализацию компонента.

## Правила для агента
- Не редактируй сгенерированные директории: `.next/`, `dist/`, `coverage/`.
- Не добавляй новые UI-библиотеки без явного требования.
- Не помещай секреты в переменные с префиксом `NEXT_PUBLIC_`, потому что они доступны клиентскому коду.
- Перед передачей результата запускай `npm run lint`, `npm run typecheck`, `npm run test` и, для крупных изменений, `npm run build`.

Этот пример показывает, как организовать код в типичном React- и Next.js-проекте. Агент понимает, где создавать новые компоненты, как их типизировать, когда использовать клиентские компоненты и какие проверки запускать перед завершением задачи.

Готовый шаблон AGENTS.md

Базовая структура шаблона

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

# AGENTS.md

## Назначение файла

[Кратко объясните, для каких AI-агентов предназначен файл и какую работу они должны выполнять в проекте]

## Краткое описание проекта

[Что делает проект, для кого он предназначен, какую проблему решает]

## Стек технологий

- Язык: [JavaScript / TypeScript / Python / Go / другой]
- Фреймворк: [React / Next.js / Django / Laravel / другой]
- Пакетный менеджер: [npm / pnpm / yarn / pip / poetry / другой]
- База данных: [если используется]
- Инфраструктура: [Docker / Kubernetes / CI/CD / облачный провайдер]

## Структура проекта

- src/ — [основной исходный код]
- tests/ — [тесты]
- docs/ — [документация]
- scripts/ — [служебные скрипты]
- [другая важная папка] — [назначение]

## Команды для запуска

### Установка зависимостей
[команда установки зависимостей]

### Локальный запуск
[команда запуска проекта]

### Сборка
[команда сборки]

### Линтинг
[команда линтинга]

### Форматирование
[команда форматирования]

### Тесты
[команда запуска всех тестов]

### Тесты для одного файла или модуля
[команда запуска точечных тестов]

## Правила работы агента

### Что агент должен делать
- Перед изменениями изучать связанные файлы и существующие паттерны.
- Вносить минимальные изменения, необходимые для выполнения задачи.
- Сохранять текущую архитектуру проекта, если задача не требует обратного.
- После изменений запускать релевантные проверки: тесты, линтинг, сборку.
- Сообщать, какие проверки были выполнены и какой результат получен.

### Что агент не должен делать
- Не менять публичные API без явного запроса.
- Не удалять тесты, чтобы скрыть ошибку.
- Не добавлять новые зависимости без необходимости.
- Не менять настройки безопасности, авторизации или платежей без подтверждения.
- Не переписывать большие части проекта, если задачу можно решить локально.

## Стиль кода

- [Правило форматирования: отступы, кавычки, точка с запятой]
- [Правило именования файлов, функций, классов, компонентов]
- [Правило организации импортов]
- [Правило обработки ошибок]
- [Правило написания комментариев]

### Пример хорошего кода

[Добавьте короткий пример кода, который отражает стиль проекта]

### Пример нежелательного кода

[Добавьте пример антипаттерна и коротко объясните, почему так делать не нужно]

## Тестирование

- Для новой бизнес-логики добавлять или обновлять тесты.
- Для исправления бага сначала воспроизводить проблему тестом, если это возможно.
- Не изменять снапшоты без проверки причины изменений.
- Если тесты не запускаются из-за окружения, описать причину и предложить следующий шаг.

## Работа с зависимостями

- Использовать существующий пакетный менеджер проекта: [npm / pnpm / yarn / другой].
- Не добавлять библиотеки, если задачу можно решить средствами проекта.
- При добавлении зависимости объяснять, зачем она нужна и почему выбран именно этот пакет.
- Не обновлять версии пакетов массово без отдельной задачи.

## Безопасность и приватность

- Не выводить и не сохранять секреты, токены, ключи API и персональные данные.
- Не коммитить файлы .env, приватные ключи и локальные конфиги.
- Не отключать проверки авторизации, валидации или CSRF-защиту без явного запроса.
- При работе с пользовательскими данными соблюдать правила проекта по приватности.

## Коммиты и pull request

### Сообщения коммитов
[Опишите формат коммитов: Conventional Commits, внутренний стандарт команды или другой вариант]

### Описание pull request
- Что изменено.
- Почему это изменено.
- Какие проверки выполнены.
- Какие риски или ограничения остались.

## Типовые сценарии

### Сценарий 1: исправление бага

Запрос: [пример запроса на исправление бага]
Ожидаемое поведение агента:
- Найти причину ошибки.
- Внести минимальное исправление.
- Добавить или обновить тест.
- Запустить релевантные проверки.

### Сценарий 2: добавление функции

Запрос: [пример запроса на новую функцию]
Ожидаемое поведение агента:
- Проверить существующие паттерны.
- Реализовать функцию в согласованном стиле.
- Добавить тесты и документацию, если это требуется.

### Сценарий 3: рефакторинг

Запрос: [пример запроса на рефакторинг]
Ожидаемое поведение агента:
- Не менять внешнее поведение без необходимости.
- Сохранить обратную совместимость.
- Проверить результат тестами.

## Дополнительные инструкции для монорепозитория

[Если проект не является монорепозиторием, удалите этот раздел]

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

## Ссылки на важную документацию

- [README.md]: [что в нём искать]
- [Документация API]: [ссылка или путь]
- [Архитектурные решения]: [ссылка или путь]
- [Гайд по дизайну или UI-kit]: [ссылка или путь]

## Версионирование файла

Версия: [текущая версия]
Последнее обновление: [дата]

### История изменений
- [Дата]: [описание изменений]
- [Дата]: [описание изменений]

## Ответственные

Ответственный за актуальность файла: [имя, роль или команда]
Канал для вопросов: [email, Slack, Telegram, ссылка на issue tracker]

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

Что обязательно заменить под себя

Шаблон — это отправная точка. Чтобы AGENTS.md приносил пользу, его нужно адаптировать под реальные команды, структуру проекта, правила команды и ограничения конкретного репозитория.

Обязательные разделы для заполнения:

Что можно удалить:

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

Что можно добавить:

Если в проекте есть специфичные инструменты, добавьте отдельный раздел «Инструменты и команды». Если агенту нужно соблюдать бизнес-правила, создайте раздел «Доменная логика». Если в проекте есть опасные зоны — например, платежи, авторизация, миграции базы данных или работа с персональными данными, — вынесите их в отдельный раздел «Критичные области».

Пошаговая адаптация:

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

Как поддерживать шаблон в актуальном состоянии

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

Когда обновлять:

Как автоматизировать проверки:

Добавьте пункт в шаблон pull request: «Нужно ли обновить AGENTS.md из-за этих изменений?» Такой чеклист особенно полезен, когда меняются команды, структура проекта, тесты или правила разработки.

Можно настроить простую проверку в CI/CD: например, предупреждать команду, если файл AGENTS.md давно не обновлялся или если в репозитории изменились ключевые конфигурационные файлы, а инструкции для агента остались прежними. Такая проверка не гарантирует качество содержания, но помогает не забывать о регулярном ревью.

Версионирование:

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

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

Совместная работа:

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

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

Как проверить качество AGENTS.md

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

Базовые элементы файла

У AGENTS.md нет обязательной схемы или фиксированного набора полей. Это обычный Markdown-файл с инструкциями для AI-агента. Но в рабочем проекте есть минимальный набор блоков, без которых агенту сложнее понять контекст, выбрать правильные инструменты и проверить результат.

Что стоит добавить в любой AGENTS.md:

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

Признаки качественного AGENTS.md

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

Конкретность. В файле нет размытых фраз вроде «используем современные подходы», «пиши чистый код» или «следуй best practices». Вместо этого есть проверяемые инструкции: «используй type hints во всех публичных функциях», «не добавляй новую зависимость без причины», «все API-эндпоинты возвращают JSON с полями status и data».

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

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

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

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

Понятные приоритеты. В хорошем AGENTS.md видно, какие правила обязательны, а какие являются рекомендациями. Например, запрет менять публичный API без согласования важнее, чем предпочтение по стилю комментариев. Если приоритеты не указаны, агент может одинаково воспринимать критичные ограничения и второстепенные пожелания.

Наличие примеров. Там, где правило можно понять по-разному, стоит добавить короткий пример. Это может быть пример команды, формат ответа API, шаблон теста, структура компонента или фрагмент кода. Пример часто работает лучше длинного объяснения.

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

Частые ошибки при создании AGENTS.md

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

Слишком общие формулировки. Фразы вроде «пиши качественный код» или «следуй принципам SOLID» почти не помогают. Лучше указать, что именно считается качественным кодом в контексте проекта: допустимая длина функции, требования к типизации, правила обработки ошибок, формат логирования, подход к декомпозиции.

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

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

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

Отсутствие примеров. Текстовые правила часто допускают несколько трактовок. Короткий пример кода, команды или структуры файла снимает неоднозначность и показывает, как именно нужно действовать.

Противоречия внутри файла. В одном разделе указано, что используется camelCase, в другом – snake_case. В одном месте написано «добавляй тесты к каждому изменению», в другом – «тесты писать не нужно». Агент не сможет надёжно выбрать правильный вариант и будет действовать наугад или запрашивать уточнение.

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

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

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

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