AGENTS.md Правильно: Повышение точности на 25% — или падение на 30%

Augment Code провела систематическое исследование файлов AGENTS.md в своем монорепозитории. Лучшие файлы обеспечили скачок качества работы агента, эквивалентный переходу от Haiku к Opus; худшие сделали результат хуже, чем полное отсутствие AGENTS.md. Один и тот же файл повысил показатель best_practices на 25% при обычном исправлении ошибки и снизил completeness на 30% при сложной задаче по реализации функции в том же модуле. Вот что работает.

Как они измеряли

Они использовали AuggieBench — внутренний набор для оценки. Начали с качественных PR из большого репозитория, отражающих типичные ежедневные задачи агента, настроили окружение и промпт, и попросили агента воспроизвести PR. Результат сравнивали с эталонным PR (версия, утвержденная после рецензирования несколькими старшими инженерами). PR должны были быть ограничены одним модулем или приложением, а область — такой, где AGENTS.md мог бы быть полезен. Каждая задача запускалась дважды — с файлом и без.

Что работает

1. Прогрессивное раскрытие информации > Всеобъемлющее покрытие

Описывайте общие случаи и рабочие процессы на высоком уровне; детали выносите в справочные файлы, которые агент может загружать по требованию. Четко обозначайте область каждого справочного файла. Файлы объемом 100–150 строк с несколькими сфокусированными справочными документами обеспечили улучшение на 10–15% по всем метрикам в модулях среднего размера (~100 основных файлов). При большем объеме улучшения сходили на нет.

2. Процедурные рабочие процессы

Нумерованный многошаговый рабочий процесс может перевести агента из состояния неудачи к успешному завершению. Пример: шестишаговый процесс развертывания новой интеграции. Количество файлов с отсутствующими связями снизилось с 40% до 10%, агент завершал работу быстрее, правильность возросла на 25%, полнота — на 20%. Держите основной файл кратким, а для разветвлений используйте справочные файлы.

3. Таблицы решений

Когда есть два или три разумных подхода (например, React Query против Zustand для управления состоянием), принудительно выбирайте на старте с помощью таблицы. Пример:

Вопрос → React Query → Zustand
Сервер — единственный источник данных? ✅
Несколько путей кода изменяют это состояние? ✅
Нужны оптимистичные обновления в сочетании с локальным состоянием? ✅

PR в этой области показали на 25% более высокий балл по best_practices.

4. Короткие примеры из продакшна

Фрагменты кода длиной 3–10 строк из реального продакшн-кода улучшили повторное использование и соблюдение шаблонов. Пример: шаблоны для копирования примитивов Redux Toolkit (createSlice с типизированным начальным состоянием, createAsyncThunk с обработкой ошибок, типизированный useAppSelector). Показатель code_reuse вырос на 20%.

5. Доменно-специфичные правила

По-прежнему важны — это тот шаблон, который большинство уже ассоциирует с AGENTS.md.