Фразы для 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.
Правила приведены на английском. При желании переведите их на язык команды. Как объясняет глава «Память проекта», файл направляет поведение агента, но не гарантирует соблюдения правил. Держите список коротким, чтобы он не превратился в раздутую память.
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
Предпочитай зрелые, поддерживаемые библиотеки самописным реализациям.
Агент может написать собственный парсер дат, который проходит простой пример и ошибается на переходе часового пояса. У зрелой библиотеки такие случаи уже могут быть разобраны и покрыты тестами. Правило побуждает проверить готовые решения и сократить объём кода, который команда будет сопровождать сама.
Перед выбором библиотеки проверьте состояние репозитория, релизы и поддержку нужных сценариев. Заброшенная зависимость может потребовать больше работы, чем собственная реализация.
Fix the cause, not the symptom
Найди и исправь причину ошибки.
Столкнувшись с падающим тестом, агент может добавить try/catch, после которого симптом исчезнет. Если ошибка возникла из-за неожиданного null, такое исправление оставит источник некорректного значения на месте. Правило требует выяснить, откуда пришёл null и какой контракт нарушен.
Правило можно сочетать с рефлексией. Перед правкой агент объясняет причину сбоя, и разработчик проверяет, устраняет ли предложенное изменение эту причину.
Suggest best practices, even if they may require refactoring
Предлагай лучшие практики, даже если они могут потребовать рефакторинга.
Агент, который стремится к минимальному диффу, может повторить недостаток соседнего кода. Правило разрешает предложить рефакторинг и объяснить, как он поможет решить задачу. Человек оценивает пользу и согласует объём работы.
Агент может предлагать рефакторинг слишком часто. Сочетайте это правило с требованием выбирать простейшую реализацию и сначала устанавливать причину проблемы.
Связанные главы
- Память проекта объясняет, где хранить эти правила.
- Раздутая память показывает, почему список нужно держать коротким.
- Инженерия контекста объясняет, как постоянные инструкции расходуют контекст каждой сессии.