Что писать в AGENTS.md, чтобы агент сразу понимал проект?

Базовый контекст проекта живёт в файле, а не в голове разработчика и не в промптах.

Описание

AGENTS.md (или эквивалент — CLAUDE.md для Claude Code) описывает стек, структуру каталогов, команды запуска, локальные URL, конвенции и ссылки на эталонные реализации. Файл подгружается в начале каждой сессии и формирует базовый контекст агента.

Предусловия

• Репозиторий существует и доступен агенту
• У разработчика есть представление о структуре проекта и регулярных задачах команды

Постусловия / гарантия успеха

• Агент при запуске понимает стек, структуру и базовые команды без дополнительных вопросов
• Снижается доля «исследовательских» обращений агента к коду, экономятся токены и время

Основной сценарий

1. Разработчик добавляет в AGENTS.md описание стека, входных точек, способов запуска и тестирования, эталонных реализаций (см. UC-011 · Эталонная реализация)
2. При работе с агентом разработчик отслеживает, какие «базовые» вопросы агент задаёт сам себе в thinking
3. Каждый такой повторяющийся вопрос превращается в дополнение к AGENTS.md (например, фиксируется локальный URL разработки)
4. Раз в неделю/спринт разработчик ревьюит AGENTS.md и удаляет устаревшее

Расширения / альтернативные потоки

• 1a. Для крупных монорепозиториев — иерархия AGENTS.md (корневой + локальные для подсистем)
• 2a. Если поведение специфично для одной повторяющейся задачи (например, переводы) — оно выносится в отдельный скилл (см. UC-004 · Переиспользуемые скиллы), а не раздувает AGENTS.md

Исключения и риски

Бизнес-правила и ограничения

• AGENTS.md описывает контекст, а не промпт: «как устроен проект», а не «как разговаривать с моделью»
• Поддержка AGENTS.md — это непрерывный процесс, а не разовая настройка

Примечания

Маркер хорошо настроенного AGENTS.md: после старта новой сессии агент сразу даёт релевантные ответы по проекту, не уточняя версии, пути или используемый фреймворк. Если каждая новая сессия начинается с «расскажи мне о проекте» — файл недонастроен.