TL;DR
Устаревшие строки в CLAUDE.md или AGENTS.md побеждают реальный код. Агент открывает файлы проекта, видит, что файл инструкций требует одно, а код делает другое, замечает это и всё равно пишет по файлу. Лекарство из исследования: одно предложение в личном (пользовательском) файле инструкций. Оно говорит агенту, что при расхождении документации и кода главный код, и просит перечислить найденные расхождения в финальном ответе.
Вот как выглядит боль. В CLAUDE.md осталась строка «Используй print() для сообщений о ходе работы», а команда год назад перешла на logging. Агент пишет в финале: «существующий код использует logging, что противоречит CLAUDE.md». И после этого добавляет новый код с print. Хуже ведёт себя Codex CLI. Он в четверти запусков переписал рабочие модули под устаревший файл, и родные тесты проекта после этого упали. Причина простая. Файл инструкций приходит в модель как команда, а код приходит как результат чтения файла. Модели специально обучены ставить команды выше содержимого файлов и веб-страниц, чтобы чужой текст в файле не мог угнать агента. Устаревшая строка получает тот же приоритет.
Метод использует эту же иерархию, но в свою пользу. Предложение в личном файле тоже приходит как команда, и теперь «следовать коду» становится самой командой. Выбор идёт не между «командой» и «чтением файла», а между двумя командами. Одно предложение, ничего больше. Доля выборов в пользу кода выросла с 4% до 91%, а тесты проходили во всех запусках.
Схема метода
ШАГ 1: Открыть ЛИЧНЫЙ файл инструкций (не проектный)
Claude Code → ~/.claude/CLAUDE.md
Codex CLI → ~/.codex/AGENTS.md
ШАГ 2: Добавить одно предложение: "при расхождении документации и кода
следуй коду + перечисли расхождения в финальном ответе"
ШАГ 3: Работать как обычно. Агент пишет в стиле существующего кода
и в конце выдаёт список устаревших мест
ШАГ 4: Использовать список → поправить проектный файл
Всё делается в одном файле, один раз. Дальше предложение работает во всех проектах.
Пример применения
Задача: Вы ведёте бэкенд интернет-магазина на Django с оплатой через ЮKassa. Год назад команда перешла с хранения сумм в рублях (float) на целые копейки, чтобы не ловить ошибки округления. В CLAUDE.md проекта осталась строка «Суммы храним в рублях как float». Вы просите Claude Code добавить промокоды с процентной скидкой. Без страховки агент напишет арифметику с float рядом с кодом, где всё посчитано в копейках. Деньги расползутся на копейку-другую, и найдёте вы это на проверке заказов, а не на ревью.
Промпт: (файл ~/.claude/CLAUDE.md, добавляется один раз)
Если документация репозитория и существующий код расходятся, следуй
соглашениям, которые используются в существующем коде, а в финальном
ответе укажи каждое найденное расхождение между документацией и кодом.
Дальше обычная задача в чате с агентом:
Добавь в корзину промокоды с процентной скидкой. Скидка применяется к сумме
заказа до доставки. Нужны модель, проверка срока действия и тесты.
Результат: Агент прочитает модули оплаты и увидит копейки. Новый код он напишет по тем же правилам: целые числа, те же хелперы округления, тот же стиль ошибок. В финальном ответе будет отдельный список расхождений. Например: «CLAUDE.md говорит, что суммы хранятся в рублях как float, а код хранит целые копейки». Этот список вы используете как задание на правку устаревшего файла. Существующие модули агент не тронет.
Почему это работает
Слабость. Файл инструкций пишется как команда («Используй X»), но на деле это снимок кода на момент записи. Код меняется, а повелительная форма остаётся. Модели обучены ставить команды выше текста из инструментов, поэтому устаревшая строка выигрывает у кода. Это работает даже когда модель видит расхождение. Замечание в финальном ответе ничего не меняет, потому что решение о том, как писать, принято по другому правилу.
Сильная сторона. Модели хорошо следуют явным командам, особенно из файла инструкций. Если команда говорит «побеждает код», модель выполняет именно её. Она хорошо умеет и сравнивать документацию с кодом, и описывать расхождения словами.
Как метод использует это. Предложение приходит тем же каналом, что и проектный файл, и получает тот же статус команды. Спор «команда против чтения файла» превращается в спор «команда против команды». Конкретное правило про этот случай побеждает общую строку. Остальные строки файла (команды сборки, структура) продолжают работать.
Рычаги управления: - Вторая часть предложения («укажи каждое расхождение») даёт побочный отчёт для чистки файла. Убрать её можно, но тогда у Codex CLI отчёта почти не будет: без предложения он упоминал конфликт лишь в 2 из 80 запусков. - Где лежит предложение. В статье проверен только личный файл. Проверять ли проектный, вы решаете сами, но там оно может стоять рядом с устаревшими строками. - Что считать «документацией». В исследовании речь про файлы инструкций. Расширять на README и комментарии можно, но это уже ваша догадка.
Шаблон промпта
Если {источник_правил} и существующий код расходятся, следуй
соглашениям, которые используются в существующем коде, а в финальном
ответе укажи каждое найденное расхождение между {источник_правил}
и кодом.
Это адаптация исходной фразы. В статье источник правил называется «документация репозитория». Подставьте:
- {источник_правил} — «документация репозитория» (как в исследовании). Если у вас только CLAUDE.md или AGENTS.md, можно написать «файл инструкций проекта».
Куда вставлять:
- Claude Code → ~/.claude/CLAUDE.md
- Codex CLI → ~/.codex/AGENTS.md
- Другие агенты (Cursor и т. п.) → глобальные правила пользователя. Эту установку авторы не проверяли, перенос — ваша догадка.
Быстрый старт не нужен. Это одно предложение, адаптировать там нечего.
Ограничения
⚠️ Работает, когда код новее файла: Предложение учит агента верить коду. Если вы намеренно пишете в CLAUDE.md новое правило («мигрируем на logging, пиши по-новому»), а код пока старый, агент по этому предложению будет следовать старому коду. Такой случай авторы не тестировали. Для него нужна оговорка в проектном файле или в задаче.
⚠️ Не 100%: С предложением доля выборов в пользу кода была около девяти из десяти, а не всегда. Проверять новый код по-прежнему нужно.
⚠️ Узкая проверка: Только небольшие синтетические проекты на Python, две пары «агент плюс модель», задачи на добавление функции за один запуск без вмешательства человека. Крупные реальные репозитории, другие языки и длинные сессии не проверялись.
⚠️ Есть исключения: В двух из 16 типов выбора (деньги и конфигурация) Claude Code и без предложения в половине случаев шёл за кодом. Для денег это особенно важно, но не гарантия: проверяйте суммы тестами.
⚠️ Чинит симптом, не причину: Предложение не обновляет устаревший файл. Оно только защищает от его последствий. Список расхождений в ответе нужно использовать, чтобы потом исправить сам файл.
Как исследовали
Авторы сделали 40 небольших Python-проектов с работающими тестами, файлом инструкций и просьбой добавить функцию. Для реализации нужно было сделать четыре-пять выборов между двумя соглашениями, например print или logging. В каждом проекте код придерживался одного соглашения, а файл требовал другого. Всего было 16 видов выбора, причём каждый встречался в обоих направлениях, чтобы вкусы модели не влияли на результат. Claude Code (Sonnet 5.5) и Codex CLI (GPT-6 Sol) прогнали каждый проект дважды с предложением и без: 320 запусков. Скрипт определял по добавленному коду, чему следовал выбор: файлу, коду или ничему из них. Отдельная модель (Opus 5.5), не знавшая условий, читала финальные ответы и отмечала, названо ли расхождение.
Без предложения 90,1% выборов шли по устаревшему файлу. Claude Code назвал конфликт в 79 из 80 запусков и всё равно писал по файлу. Это ключевой инсайт: «заметить» не значит «исправить». Codex CLI в 20 запусках переписал существующий код под файл, в 17 из них тесты упали. С предложением доля выборов по коду выросла с 4,2% до 91,4%, переписываний не было, тесты проходили во всех 160 запусках. Это подтвердило объяснение авторов про иерархию «команда выше результата инструмента». Заметный деталь: мощная «преамбула» Claude Code («ОБЯЗАТЕЛЬНО следуй») не причина. У Codex CLI такого текста нет, а файл он слушался даже чаще.
Авторы также показали на реальных репозиториях Supabase и OpenAI Codex, что файлы инструкций устаревают на 13–24 дня даже в живых проектах.
Оригинал из исследования
When a repository's documentation and its existing code disagree, follow the conventions used
in the existing code, and in your final reply point out each inconsistency you found between the
documentation and the code.
Контекст: Это дословное предложение, которое авторы добавляли в личный файл инструкций каждого агента во всех запусках «с предложением». Оно же использовалось и в задачах про деньги.
Адаптации и экстраполяции
💡 Адаптация для регулярного аудита файла инструкций: Исходная фраза даёт отчёт как побочный продукт. Если вы хотите чистить файл целенаправленно, дайте агенту отдельную задачу. Это не тестировалось, но использует тот же механизм сравнения.
Прочитай CLAUDE.md и сравни каждую строку с реальным кодом проекта. Ничего не меняй. Выведи таблицу: строка из файла | что в коде | совпадает или нет.
🔧 Техника: убрать вторую часть предложения → меньше шума, но нет отчёта. Если в ответах агента список расхождений мешает, оставьте только «следуй соглашениям, которые используются в существующем коде». Минус: Codex CLI без такой просьбы почти не сообщал о конфликтах.
🔧 Техника: разделить файл на «правила» и «описания». Авторы советуют производителям моделей отличать описания кода от правил для агента. Читателю можно сделать это руками: хранить в файле команды сборки и запреты отдельно от того, «как устроен код». Вторую часть устаревать проще. Эффект самим разделением авторы не проверяли.
Ресурсы
- Работа: Stale Instruction Files Override the Code in Coding Agents: A One-Sentence Fix
- Авторы: Xiaonan Xu (Georgia Institute of Technology), Wenjing Wu (University of Colorado Boulder)
- Данные и код: github.com/WenJing95/stale-docs-data
- Связанные работы: Wallace et al., «The Instruction Hierarchy» (arXiv:2404.13208); Mohammadi et al., «The working set of a coding agent» (arXiv:2608.16630); Treude & Baltes, «Context rot in AI-assisted software development» (arXiv:2606.09090)