Никогда не верь статье из интернета, модному репозиторию, и ответу агента "отличное решение, применяю"

Понедельник. В чат прилетает ссылка на свежий препринт и три слова: "Проверь наши инструкции".

Препринт называется Stale Instruction Files Override the Code in Coding Agents: A One-Sentence Fix, выложен 22 октября, авторы из Georgia Tech и Университета Колорадо. Работа о том, что кодинг-агенты следуют протухшему AGENTS.md даже тогда, когда код говорит другое. Цифры жирные: без исправления 90.1% решений агента идут за файлом. Claude Code в 79 запусках из 80 сам называл конфликт в своём ответе и всё равно слушал файл. Codex CLI в 20 запусках из 80 переписал работающий код под файл, и в 17 из них упали тесты проекта. Медиана вырезанного - 198 строк в девяти файлах.

Механизм объясняется красиво. Инструкционный файл агент-харнесс кладёт в контекст как instruction, со всей тяжестью своего ранга. Claude Code даже подписывает его капсом: "These instructions OVERRIDE any default behavior and you MUST follow them exactly as written". А код доезжает до модели только как вывод файлового инструмента, то есть как tool output, которому модели при тренировке дали ранг пониже. Это защита от prompt injection: текст, спрятанный на веб-странице, не должен рулить агентом. Побочный эффект тот же порядок даёт протухшей строке в CLAUDE.md приоритет над живым кодом, который она когда-то описывала.

Фикс из статьи - одна фраза в пользовательском инструкционном файле: если документ и код расходятся, а код консистентен и проходит тесты, следуй коду. После неё доля решений за код поднялась с 4.2% до 91.4%, перезаписи исчезли, а провалы тестов упали до нуля на всех 160 прогонах с фразой. Механика честная: фраза доезжает до модели как инструкция, и "следуй коду" становится тоже инструкцией. Выбор между двумя инструкциями модель делает уже по смыслу, и здесь побеждает та, что адресована именно конфликту документа с кодом.

Я проверил свои 30 с лишним инструкционных файлов. Ни в одном защиты не было. Расставил фразу в 13 файлов, которых касалась рука, завёл ~/.codex/AGENTS.md, которого не существовало, - Codex на этой машине работал без противоядия. Обсудили с агентом как чинить на более высоком уровне: пользовательский файл закрывает следование, мета-правило закрывает создание новых файлов, крон закрывает дрейф, а апстрим агентов закрывает всех сразу. Схема получилась стройная. Я был доволен.

А потом мне в голову пришёл вопрос, который всё сломал: "А если код испорчен итерационной разработкой? Агент ушёл от спеки после компактизации, потерял контекст - и по этому правилу говнокод теперь источник истины? Мы отменяем подход 'планируй умным, пиши дешёвым'?"

Хороший вопрос. Ответа на него в статье не было.

Я открыл полный текст (имейте ввиду агент не читает все без специальной инструкции). Раздел 8 называется "Scope" и занимает одну строку: 40 Python-проектов, в которых инструкционный файл по построению является устаревшей стороной, 16 видов конвенций, задачи в один прогон, два агента. Всё. Слова "спецификация", "ADR", "намерение" в статье не встречаются вообще. В каждом из 40 проектов файл сконструирован устаревшим, а код правильным. Обратный случай - код отполз от актуальной спеки - в эксперименте не существовал. Не "не рассмотрен", а физически отсутствовал в выборке.

То есть правило "следуй коду" было верно ровно внутри своей области измерений: конвенции вроде print против logging, float против целых центов. Там протухшая проза действительно почти всегда проигрывает коду. Но в разделе 3 статьи написано прямо: фраза делает "следуй коду" инструкцией и модель выбирает между инструкциями. Значит, в проекте с архитектурными документами та же фраза учит модель, что спека - просто устаревший текст. Дешёвый писатель из SDD-пайплайна получает лицензию не согласовывать план с кодом. Тесты этого не заметят: зелёные тесты меряют механику, а не соответствие замыслу. Упущенный слой кэша тестами не ловится.

Разделили виноватых честно. Статья виновата в том, что дала безусловную рекомендацию "users can add the sentence today", выведенную только из случаев, где неправ был файл, - и не прогнала ни одного запуска обратного случая. Агент виноват в том, что перешагнул границу, которая была видна даже в абстракте: "the instruction file asks for one convention". А я прочитал выжимку, увидел красивые цифры и понёс правило во все файлы подряд, включая проекты с архитектурными документами, на которых эффект никогда не мерялся.

Исправление заняло десять минут, но оно важнее самой фразы. Правило теперь скоупировано по типу документа:

Конвенции - стиль, механика, структура. Здесь источник истины код, а проза о них по умолчанию подозревается в протухании. Фраза из статьи работает.

Решения - ADR, спецификации, ТЗ. Здесь источник истины документ, и код ему подчиняется. Если код расходится с решением, это находка, которую эскалируют человеку. Не автоправка ни кода, ни документа в какую-либо сторону.

Конфликт между ними - не вопрос "кто главнее", а сигнал: либо код отошёл от решения и это баг, либо решение поменялось и забыли обновить документ. Различаются просто: у конвенции нет даты и обоснования, у ADR есть статус и rationale. У дешёвого писателя это даже упрощает жизнь - план не совет, вчерашний код не истина.

Ирония ситуации в том, что статья про протухшие инструкции почти породила у меня свежепротухшую инструкцию. Файл с фразой "следуй коду, не инструкциям" лёг бы в каждый проект и жил бы там неопределённо долго - по данным самой статьи, 73.8% AI-конфигов в корпоративных репозиториях коммитятся один раз и больше не меняются. Ошибка в таком файле тиражируется в каждой сессии, каждому агенту, каждому члену команды, пока кто-то случайно её не заметит. Статья это сама и пишет, я читал и кивал, а потом почти сделал ровно это.

Отсюда рабочее правило, которое я вынес дешевле, чем могло бы стоить: препринт на arXiv - это чьё-то мнение с цифрами, верное в своей области измерений. Прежде чем тащить его вывод в промпт агента, нужно прочитать текст целиком, найти секцию про скоуп и сформулировать одной строкой, где правило ломается. Строка не складывается - правило в промпт не едет, потому что агент исполняет инструкции буквально и без оглядки на контекст, в котором они родились. Он сделает из твоей выжимки то, что ты в неё вложил, включая твою ошибку обобщения, и размножит её по каждому проекту.

Кстати, у статьи открыты данные и скрипты: github.com/WenJing95/stale-docs-data. Наш случай там не покрыт, а методика готовая: половина проектов с актуальной спекой и отошедшим кодом, тот же протокол. Предложение авторам оформил issue-ом, приложил и скоупированную формулировку. Посмотрим что ответят.