Введение
Когда я начал использовать AI-агентов для написания кода, я думал, что главное — это проверить логику и синтаксис. Но уже через месяц работы с Cursor и Claude я понял: ревью AGENTS.md — это не просто формальность, а критический этап, который может спасти проект от недели переписывания. В 2026 году, когда AI-агенты генерируют до 80% кода в стартапах, файл AGENTS.md стал таким же важным, как и сам код. В этой статье я расскажу, почему обзор AGENTS.md — это новый стандарт, и как его правильно делать.
Зачем нужен AGENTS.md?
Файл AGENTS.md — это манифест для AI-агента. Он описывает контекст проекта, правила, ограничения и архитектурные решения. В отличие от README, который ориентирован на людей, AGENTS.md пишется для AI: чёткие инструкции, примеры кода, ссылки на API и запреты. Без него агент может начать генерировать код, который не соответствует стилю проекта, использует устаревшие библиотеки или нарушает архитектуру.
Я веду блог на asibiont.com/blog, где делюсь опытом использования AI в бизнесе. В одном из проектов мы интегрировали Telegram API — и именно AGENTS.md помог агенту правильно обработать вебхуки. Если бы мы не обновили этот файл, агент бы использовал устаревший метод long polling, что привело бы к задержкам.
Как AGENTS.md влияет на качество кода?
Представьте, что вы нанимаете нового разработчика. Вы даёте ему доступ к репозиторию, но не объясняете, какие паттерны использовать, какие тесты писать и какой стиль кода принят. Результат — хаос. С AI-агентами то же самое. AGENTS.md — это ваш «онбординг-документ». В нём можно указать:
- Язык и фреймворк (например, Python 3.12 + FastAPI)
- Структуру проекта (папки, модули)
- Правила именования (snake_case для переменных, PascalCase для классов)
- Требования к тестам (покрытие > 80%, обязательные unit-тесты для бизнес-логики)
- Список запрещённых зависимостей (например, «не используй библиотеку X»)
Когда я впервые написал AGENTS.md для проекта на Node.js, агент перестал предлагать jQuery в 2026 году — это было смешно, но до этого он постоянно его вставлял.
Практический кейс: ревью AGENTS.md спасло проект
Работал с командой над SaaS-продуктом для аналитики. Мы использовали AI-агента для генерации отчётов. В AGENTS.md было написано: «Используй Chart.js для графиков». Но через месяц мы перешли на ECharts — более производительную библиотеку для больших данных. Разработчик забыл обновить AGENTS.md, и агент продолжал генерировать код с Chart.js. Результат: графики тормозили на датасетах в 10 000 точек. Мы потратили два дня на переписывание. Если бы мы сделали ревью AGENTS.md перед спринтом, проблема бы не возникла.
Как проводить ревью AGENTS.md?
Вот чек-лист, который я использую в своей практике:
| Этап | Что проверять | Пример плохо | Пример хорошо |
|---|---|---|---|
| 1. Контекст | Цель проекта, стек, целевая аудитория | «Мы делаем сайт» | «SaaS для малого бизнеса, стек: Next.js 15, Tailwind, Supabase» |
| 2. Правила кода | Стиль, линтеры, форматтеры | «Код должен быть чистым» | «Используй Prettier с конфигом из .prettierrc, ESLint с правилами Airbnb» |
| 3. Ограничения | Запрещённые библиотеки, устаревшие методы | «Не используй устаревшее» | «Не используй moment.js — замени на date-fns. Не используем jQuery» |
| 4. Тестирование | Требования к тестам, инструменты | «Пиши тесты» | «Каждая функция должна иметь unit-тест в папке tests. Используй Vitest» |
| 5. API и интеграции | Ссылки на документацию, ключи, эндпоинты | «Используй API» | «API: /api/v2/docs. Аутентификация: JWT в заголовке Authorization. Rate limit: 100 req/min» |
Я проверяю AGENTS.md перед каждым спринтом и после добавления новой библиотеки или изменения архитектуры.
Типичные ошибки при написании AGENTS.md
-
Слишком общие инструкции. «Пиши хороший код» — это бесполезно. Нужно конкретно: «Используй async/await вместо колбэков, избегай мутации объектов, применяй TypeScript strict mode».
-
Отсутствие примеров. Если вы пишете «используй паттерн Repository», приложите пример кода. Агент лучше понимает на примерах.
-
Неактуальная информация. AGENTS.md должен жить вместе с кодом. Если вы обновили версию фреймворка, сразу меняйте файл. Иначе агент будет генерировать код под старую версию.
-
Игнорирование безопасности. Укажите, какие данные нельзя передавать агенту (например, API-ключи, пароли). AI-агенты могут случайно включить их в код.
Как AGENTS.md помогает в командной работе?
В моей команде из 5 разработчиков каждый использует AI-агента. Без AGENTS.md каждый агент генерировал код в своём стиле: один использовал class-компоненты в React, другой — функциональные. После введения AGENTS.md с чёткими правилами (только функциональные компоненты, только hooks) код стал единообразным. Ревью кода теперь занимает на 30% меньше времени, потому что стилистические правки отпали.
Инструменты для автоматизации проверки AGENTS.md
В 2026 году появились инструменты, которые автоматически проверяют AGENTS.md на актуальность. Например, я использую GitHub Action, который сравнивает AGENTS.md с фактическим кодом: если агент использовал библиотеку, не указанную в файле, action выдаёт предупреждение. Также есть линтеры для AGENTS.md — они проверяют синтаксис и полноту.
Заключение
Ревью AGENTS.md — это не бюрократия, а инвестиция в качество. В мире, где AI генерирует большую часть кода, управлять этим кодом можно только через чёткие правила. Начните с малого: напишите AGENTS.md для своего проекта, включите его в ревью и обновляйте каждый спринт. Увидите, как количество багов снизится, а скорость разработки вырастет.
Я веду блог на asibiont.com/blog, где делюсь такими кейсами. Если вы хотите глубже разобраться в теме, подписывайтесь — в следующих статьях я расскажу, как настроить AGENTS.md для конкретных стеков и как интегрировать его с CI/CD.
Иллюстрация к статье: AGENTS.md как мост между человеком и AI-агентом. Без него — хаос, с ним — порядок.
Комментарии