В проекте уже используют pytest, а старый AGENTS.md требует unittest. ИИ-агент может не только написать новый тест по старому правилу, но и переделать существующий код под документ. Тогда инструкция выглядит соблюдённой, а рабочий проект ломается.
Авторы препринта об устаревших instruction-файлах проверили этот конфликт на 40 небольших Python-проектах. Claude Code и Codex CLI выполнили 320 запусков в двух условиях.
Без отдельного правила 90,1% оцениваемых решений следовали устаревшему файлу и 4,2% — текущему коду. После добавления одного правила доля решений в пользу кода выросла до 91,4%. Это результат авторов препринта, а не тест ИИ-цеха.
Сначала определите, что именно расходится
Код не становится источником истины для всего проекта. Разделите конфликт на два вида.
Техническое соглашение можно проверить в репозитории:
- формат тестов;
- структура импортов;
- названия файлов и функций;
- способ обработки ошибок;
- фактические команды сборки и проверки.
Требование продукта живёт в решении владельца, задаче или договорённости:
- что должно получить лицо, использующее продукт;
- кто имеет право публиковать или удалять данные;
- какие интеграции разрешены;
- какой результат считается принятым;
- какие ограничения нельзя менять без согласования.
Если старый документ спорит с реализацией технического соглашения, агент сохраняет работающий контур и сообщает о расхождении. Если код спорит с актуальным требованием, агент не выбирает победителя сам: нужен ответ владельца.
Проверьте проект до правки инструкции
- Найдите корневые и вложенные
AGENTS.md,CLAUDE.md, rules и skill-файлы. - Запустите существующие тесты и запишите исходный результат.
- Для каждого спорного правила найдите носитель: код, конфигурацию, тест или решение
владельца с датой.
- Отметьте файлы, которые описывают старую структуру, удалённую команду или иной
формат тестов.
- Не исправляйте код только ради совпадения с текстом до этой сверки.
Результат проверки — таблица конфликтов, а не общий вывод «документация устарела».
| Инструкция | Что найдено в проекте | Тип конфликта | Следующее действие |
|---|---|---|---|
Использовать unittest | Все тесты написаны на pytest | техническое соглашение | сохранить pytest, обновить документ |
| Публиковать после сборки | Нужна ручная приёмка владельца | полномочие | не публиковать, сохранить gate |
Читать src/config.py | Файл удалён, настройки в config/ | путь | обновить путь после проверки |
Добавьте правило приоритета
Для технических соглашений подойдёт такая формулировка:
Если документация проекта расходится с текущим кодом и тестами, сохраняй
проверяемые соглашения кода и перечисли найденные расхождения в итоговом отчёте.
Рядом нужна граница:
Это правило не отменяет актуальные требования продукта, решения владельца,
ограничения безопасности и полномочия на публикацию. При таком конфликте остановись
и запроси решение.
Первую строку лучше держать в корневой инструкции, которую получают все coding-агенты. Вложенные документы уточняют локальные правила, но не должны молча отменять общий порядок.
Проверьте поведение после изменения
Возьмите одну небольшую задачу, где старый документ и код требуют разных соглашений. До запуска запишите ожидаемый выбор и команду теста. После выполнения проверьте:
- агент сохранил действующий стиль кода;
- существующие тесты по-прежнему проходят;
- новый тест проверяет поведение, а не только структуру;
- итоговый ответ перечисляет конфликт;
- инструкция или код не переписаны за пределами задачи.
В исследовании Codex CLI без правила переписал существующий код в 20 из 80 запусков. В 17 из этих 20 запусков тесты затем упали. После добавления правила все 160 запусков обоих агентов прошли существующие и скрытые тесты.
Где правило не даёт гарантии
Препринт проверяет две версии coding-агентов, синтетические Python-проекты и ограниченный набор конфликтов. Независимого повторения в материале нет. Результат нельзя переносить на все модели, языки и репозитории без собственного теста.
Код тоже может быть устаревшим или ошибочным. Поэтому правило работает вместе с тестами, журналом решений и явной границей полномочий, а не заменяет их.
Критерий готовности
- все instruction-файлы перечислены;
- каждому конфликту назначен источник истины;
- технические соглашения подтверждены кодом или тестом;
- продуктовые требования подтверждены решением владельца;
- правило приоритета добавлено один раз в общий вход;
- агент обязан перечислять расхождения;
- контрольная задача проходит исходные и новые тесты;
- публикация и другие внешние действия по-прежнему требуют отдельного разрешения.
Открытые данные и скрипты авторов находятся в репозитории исследования. У репозитория данных не указана лицензия, поэтому его файлы нельзя автоматически переносить в собственный курс или проект.
Что проверить следом
После сверки instruction-файлов зафиксируйте правила, состояния и критерии приёмки самой функции. Пошаговый шаблон есть в гайде как подготовить спецификацию до работы ИИ-агента.
Как зашло?
Ответ засчитывает гайд и помогает нам его улучшить
