Я регулярно работаю с AI-инструментами: ChatGPT, Codex, Gemini CLI и локальными моделями.
Проблема у всех одинаковая: отсутствие контекста.
Каждый новый диалог приходится начинать заново. Объяснять устройство проекта, принятые правила и ограничения.
Без этого AI работает вслепую.
Для решения этой задачи я использую AGENTS.md.
Что такое AGENTS.md
AGENTS.md — файл с инструкциями для AI-агентов.
Он хранится в репозитории и описывает правила работы с проектом.
По сути, это документация для AI.
Её задача — один раз описать контекст проекта и перестать повторять одни и те же инструкции в каждом новом диалоге.
Какую проблему он решает
Без контекста AI часто ошибается.
Типичные проблемы:
- усложняет архитектуру без необходимости
- предлагает инструменты, которые уже используются
- нарушает принятые соглашения
- создаёт лишнюю абстракцию
- игнорирует ограничения проекта
Чем больше проект, тем заметнее эти ошибки.
Особенно это касается инфраструктурных репозиториев.
Почему я начал его использовать
В течение дня я переключаюсь между разными задачами:
- Kubernetes
- CI/CD
- инфраструктурными репозиториями
- документацией
- внутренними инженерными проектами
Повторять один и тот же контекст оказалось неэффективно.
Гораздо проще один раз описать правила и поддерживать их в актуальном состоянии.
Это снижает когнитивную нагрузку и делает результат более предсказуемым.
Где лежит AGENTS.md
Обычно я храню его в корне репозитория.
project/
├── AGENTS.md
├── README.md
├── docs/
├── src/
└── ...
Файл становится частью проекта и развивается вместе с ним.
Что обычно хранят в AGENTS.md
Содержимое зависит от проекта, но чаще всего там описывают:
- назначение проекта
- используемый стек
- структуру репозитория
- инженерные соглашения
- ограничения и запреты
- правила работы с документацией
- стиль написания текстов
- принципы принятия решений
Это не README и не техническая документация. Его задача — быстро объяснить AI, как устроен проект и как с ним работать.