Базовый контекст проекта живёт в файле, а не в голове разработчика и не в промптах.
Описание
AGENTS.md (или эквивалент — CLAUDE.md для Claude Code) описывает стек, структуру каталогов, команды запуска, локальные URL, конвенции и ссылки на эталонные реализации. Файл подгружается в начале каждой сессии и формирует базовый контекст агента.
Предусловия
- Репозиторий существует и доступен агенту
- У разработчика есть представление о структуре проекта и регулярных задачах команды
Постусловия / гарантия успеха
- Агент при запуске понимает стек, структуру и базовые команды без дополнительных вопросов
- Снижается доля «исследовательских» обращений агента к коду, экономятся токены и время
Основной сценарий
- Разработчик добавляет в AGENTS.md описание стека, входных точек, способов запуска и тестирования, эталонных реализаций (см. UC-011 · Эталонная реализация)
- При работе с агентом разработчик отслеживает, какие «базовые» вопросы агент задаёт сам себе в thinking
- Каждый такой повторяющийся вопрос превращается в дополнение к AGENTS.md (например, фиксируется локальный URL разработки)
- Раз в неделю/спринт разработчик ревьюит AGENTS.md и удаляет устаревшее
Расширения / альтернативные потоки
- 1a. Для крупных монорепозиториев — иерархия AGENTS.md (корневой + локальные для подсистем)
- 2a. Если поведение специфично для одной повторяющейся задачи (например, переводы) — оно выносится в отдельный скилл (см. UC-004 · Переиспользуемые скиллы), а не раздувает AGENTS.md
Исключения и риски
Бизнес-правила и ограничения
- AGENTS.md описывает контекст, а не промпт: «как устроен проект», а не «как разговаривать с моделью»
- Поддержка AGENTS.md — это непрерывный процесс, а не разовая настройка
Примечания
Маркер хорошо настроенного AGENTS.md: после старта новой сессии агент сразу даёт релевантные ответы по проекту, не уточняя версии, пути или используемый фреймворк. Если каждая новая сессия начинается с «расскажи мне о проекте» — файл недонастроен.
Частые вопросы
AGENTS.md и CLAUDE.md — это одно и то же?+
Близко. CLAUDE.md — конкретное имя для Claude Code; AGENTS.md — кросс-агентный стандарт (читается OpenCode, Codex, Aider). Многие проекты используют оба: симлинк или дублирование. Можно начать с одного — конвертация займёт минуты.
Что обязательно должно быть в AGENTS.md?+
Стек и версии, точки входа, команды dev/build/test/lint, локальный dev-URL (если есть), договорённости по работе с git (как коммитить, ветки), правила безопасности (что не трогать), ссылки на эталонные реализации в коде. Всё остальное — по мере необходимости.
Как понять, что AGENTS.md перегружен?+
Если агент стал хуже работать после очередного добавления — это сигнал. Если файл больше ~300 строк — точно пора чистить или выносить в скиллы (UC-004). Постоянно повторяемое — в AGENTS.md, эпизодическое — в скилл.
Нужен ли AGENTS.md в маленьком проекте?+
Да, даже на 5 строк. Минимум: команды запуска/тестов + 1-2 предупреждения. Это быстрее окупится, чем кажется.
Как структурировать AGENTS.md для монорепо?+
Иерархия: корневой AGENTS.md с общим, локальные в каждой подсистеме. Агент читает корневой + ближайший к рабочей директории. Не дублируйте — выносите общее в корень.