Подготовка репозитория

Info

Агент начинает работу с чистого листа: он не помнит предыдущие задачи и не знает договоренностей вашей команды. Файл AGENTS.md в корне репозитория — это то, что он читает всегда.

Что такое AGENTS.md

AGENTS.md — файл инструкций для AI-агентов в формате Markdown. Это открытый стандарт, который понимают разные AI-инструменты, поэтому один файл работает и в GitVerse, и в вашем редакторе.

AGENTS.md дополняет README.md, а не заменяет его:

  • README.md отвечает на вопрос «что это за проект» и написан для человека;
  • AGENTS.md отвечает на вопрос «как здесь работать» и написан для агента.

Файл читается автоматически при каждом запуске агента. Отдельно подключать его не нужно.

Создание файла командой /init

Не пишите AGENTS.md вручную с нуля. В сессии выполните команду /init: агент изучит репозиторий и соберет файл сам.

  1. Откройте сессию с нужным репозиторием.

  2. Введите /init и отправьте сообщение.

  3. Агент прочитает README, файлы сборки и зависимостей, конфигурацию CI/CD, настройки линтеров и тестов и уже существующие файлы инструкций.

  4. Если чего-то не хватает в репозитории, агент задаст уточняющие вопросы — например про порядок ревью или требования к оформлению запросов на слияние.

  5. Агент создаст AGENTS.md или улучшит существующий файл, сохранив то, что в нем уже было полезного.

  6. Проверьте результат и закоммитьте файл в репозиторий.

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

Info

Команду /init полезно повторять после крупных изменений: смены стека, переезда на новый инструмент сборки, реорганизации директорий.

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

Критерий один: включайте то, о чем агент ошибется, если не сказать.

Полезно:

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

Не нужно:

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

Если сомневаетесь, включать ли пункт, — не включайте. Раздутый файл инструкций расходует контекст и снижает точность.

Пример файла

AGENTS.md сервиса на Go в монорепозитории:

# Сервис заказов
 
Часть монорепозитория. Код сервиса — в `services/orders`, общие библиотеки — в `pkg`.
Изменения в `pkg` затрагивают четыре сервиса, поэтому правь их только если задача прямо об этом.
 
## Команды
 
- сборка: `make build`
- тесты пакета: `go test ./services/orders/...`
- один тест: `go test ./services/orders/internal/handler -run TestCreateOrder`
- линтер: `make lint`
 
Порядок перед коммитом: `make lint`, затем тесты. Линтер настроен строже стандартного
и падает на неотсортированных импортах.
 
## Особенности
 
- Код доступа к базе генерируется: после правки `*.sql` в `services/orders/db`
  нужно выполнить `make generate`, руками сгенерированные файлы не редактируются.
- Интеграционные тесты требуют поднятого Postgres: `make test-env-up`.
  Без него они падают с таймаутом подключения, и это не ошибка в коде.
- Конфигурация читается из `config/local.yaml`, переменные окружения его перекрывают.
 
## Соглашения
 
- Ошибки заворачиваются через `fmt.Errorf` с `%w`, паники в обработчиках запрещены.
- Публичные структуры запросов и ответов живут в `api/`, во внутренние пакеты не переносятся.
- Сообщение коммита — на русском, заголовок в формате `<тип>: <описание>`.

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

Вложенные файлы инструкций

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

AGENTS.md              общие правила репозитория
backend/
  AGENTS.md            правила backend-части
frontend/
  AGENTS.md            правила frontend-части

Это удобно в монорепозитории: общие договоренности лежат в корне, специфика — рядом с кодом.

Что дальше

  1. Вынесите повторяющиеся процедуры в навыки — в AGENTS.md должны остаться только постоянные правила.
  2. Переходите к циклу работы с агентом.

Вид графа

Связанные страницы