При работе с AI быстро становится заметно, что качество ответа зависит не только от модели.

Не меньшее значение имеет контекст.

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

Чтобы этого избежать, я использую AGENTS.md.

Что такое AGENTS.md

AGENTS.md - это файл с инструкциями для AI.

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

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

Какую проблему он решает

Без контекста AI приходится принимать решения на основе предположений.

Например, он может:

  • предложить инструменты, которые уже используются
  • нарушить принятые соглашения
  • изменить структуру проекта без необходимости
  • усложнить простое решение

Большинство этих ошибок связано не с качеством модели, а с отсутствием информации о проекте.

Почему я начал использовать AGENTS.md

В течение дня я переключаюсь между разными проектами.

У каждого свой стек, структура репозитория и инженерные соглашения.

Повторять этот контекст в каждом новом диалоге оказалось неудобно.

Гораздо проще один раз описать правила и хранить их рядом с кодом.

Где находится AGENTS.md

Обычно я размещаю файл в корне репозитория.

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

Так он развивается вместе с проектом и обновляется одновременно с ним.

Что обычно содержит AGENTS.md

Содержимое зависит от проекта, но чаще всего я храню:

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

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

Вывод

Сначала я воспринимал AGENTS.md как инструкцию для AI.

Со временем понял, что это нечто большее.

Это способ сделать контекст проекта явным.

Именно с этого, на мой взгляд, начинается предсказуемая работа не только AI, но и любого человека, который впервые открывает репозиторий.