Фразы для AGENTS.md

Небольшой набор универсальных правил, которые имеет смысл добавить в память проекта почти любого репозитория. Это не конфигурация проекта и не команды сборки — это установки о том, как агенту принимать решения, когда выбор остаётся на его усмотрение.

Отправная точка — разошедшийся по сети список Marcos Hernanz; две последние формулировки — добавки Кирилла Мокевнина.

Готовый блок для копирования:

# AGENTS.md
- Do not preserve backward compatibility.
- Choose the simplest implementation that fully meets the current requirements.
- Prefer established, well-maintained libraries over custom implementations.
- Fix the cause, not the symptom.
- Suggest best practices, even if they may require refactoring.

Правила ниже приведены на английском — так их понимает любой инструмент, читающий AGENTS.md; при желании переведите на язык команды. Помните границу из главы «Память проекта»: файл памяти направляет поведение агента, но не гарантирует его. И держите список коротким — иначе получите раздутую память.

Do not preserve backward compatibility

Не тащи обратную совместимость.

По умолчанию агент осторожничает: оставляет старые поля «на всякий случай», плодит перегрузки, копит слои совместимости вокруг каждого изменения. На внутреннем коде, который правит одна команда, это чистый балласт — мёртвые ветки и дублирование, которые никто никогда не удалит. Правило разрешает агенту менять код смело: переименовывать, удалять, переписывать сигнатуры.

Граница: правило уместно для приложений и внутренних модулей. Для публичной библиотеки или внешнего API совместимость — это контракт с пользователями; там формулировку нужно перевернуть.

Choose the simplest implementation that fully meets the current requirements

Выбирай простейшую реализацию, полностью закрывающую текущие требования.

Агент склонен к переусложнению: закладывает конфигурируемость, абстракции и точки расширения под задачи, которых ещё нет. Правило возвращает его к принципу YAGNI — решать поставленную задачу, а не воображаемую будущую. Слово fully здесь важно: это не разрешение срезать углы, а требование закрыть текущие требования целиком — но не шире.

Родственно анти-паттерну «Преждевременная спецификация»: и там, и тут вред в том, что сложность закладывается раньше, чем на неё есть спрос.

Prefer established, well-maintained libraries over custom implementations

Предпочитай зрелые, поддерживаемые библиотеки самописным реализациям.

Оставленный без указаний агент охотно пишет свой парсер дат, свою валидацию, свой пул соединений — код, который выглядит рабочим, но не проходил через боль чужого продакшена. Правило разворачивает выбор в сторону готового: меньше кода под сопровождение, известные крайние случаи уже закрыты.

Проверяйте, что библиотека действительно established и well-maintained — живой репозиторий, свежие релизы, — иначе зависимость станет обузой. Про эту установку подробнее — в контексте выбора инструментов вместо ручного кода.

Fix the cause, not the symptom

Исправляй причину, а не следствие.

Столкнувшись с падающим тестом или ошибкой, агент тяготеет к локальной заплатке: подправить проверку, обернуть в try/catch, подогнать под конкретный вход. Симптом исчезает, причина остаётся и всплывает рядом. Правило требует докопаться до корня — почему значение вообще оказалось null, — а не гасить проявление.

Хорошо сочетается с рефлексией: прежде чем чинить, агент объясняет, почему сломалось, — и заплатки отсекаются на этом шаге.

Suggest best practices, even if they may require refactoring

Предлагай лучшие практики, даже если они могут потребовать рефакторинга.

Агент, оптимизирующий под «сделать задачу минимальным диффом», молча встраивается в кривой код и тиражирует его недостатки. Правило даёт ему право голоса: заметил, что задачу лучше решить с рефакторингом соседнего кода, — скажи об этом, а не обходи молча. Решение остаётся за человеком, но выбор хотя бы становится осознанным.

Обратная сторона — агент может предлагать рефакторинг слишком часто; держите это правило в паре с предыдущими двумя (простейшая реализация, причина а не следствие), чтобы предложения оставались уместными.

Связанные главы

• Память проекта — куда эти фразы попадают и как файл памяти устроен.
• Раздутая память — почему список нужно держать коротким.
• Инженерия контекста — каждая строка памяти расходует бюджет внимания в каждой сессии.