Спек-тесты вылечили архитектурный дрифт: агент поправил 637 размеров шрифта за раз

Есть известный эксперимент: просишь ChatGPT сделать точную копию картинки и ничего не менять, и повторяешь это 101 раз. Фотография Дуэйна Джонсона к концу превращается в мультяшное месиво. Каждый шаг по отдельности почти честный, а в сумме получается совсем другое.

С кодом, которым занимается ИИ-агент, происходит то же самое. Автор разбора называет это архитектурным дрифтом. Пример с фронтенда самый наглядный: шрифт задан и везде один, а вот размеры на каждой странице свои, и общий стиль сайта рассыпается. Принцип при этом общий для любых зон разработки: разъезжается source of truth.

Истина в спеке, а не в коде

Автор код вообще не читает, он контролирует только спеки. Логика такая: спека — чертёж, код — деталь, и деталь сверяют с чертежом, а не с другой деталью. Два источника правды дают хаос.

Вся документация лежит в папке docs в корне проекта. На 5 ноября 2026 там 7 478 файлов .md и 11 уровней вложенности. В 95,3% папок не больше 7 файлов, в 97,4% не больше 9. Это правило «7 плюс-минус 2»: человеку (и агенту) проще понять, где что лежит. Спеки пишут и читают агенты, а человек смотрит их в админке в удобном виде.

Пример: все правила типографики лежат в одном typography.md. Там 22 роли, и у каждой семейство, кегль на десктопе и мобильном, вес и цвет. Например, абзац статьи — Charis 21/30, база — Inter 14/21. Два семейства на весь сайт, веса только 400 и 700. Главное правило: состояний вне реестра не бывает, новая связка означает новую строку по вердикту.

Заставить читать и проверить детерминированно

Спеки сами по себе работают вероятностно: агент может им последовать, а может нет. Поэтому есть два слоя защиты.

Первый — файл AGENTS.md. В нём прописано, что перед задачей агент читает документацию из соответствующей папки. Если нужен аудит облачных расходов, он идёт в папку про облака и разбирает всех провайдеров. По оценке автора, в 9 случаях из 10 правила при этом не нарушаются.

Второй слой — спек-тесты на «десятый случай». Тест читает таблицы из typography.md, собирает допустимые пары размеров и обходит весь фронтенд. Любая пара вне спеки валит сборку с именем файла и строкой.

Что вскрыл тест

До 6 ноября тест был чёрным списком из девяти устаревших пар. Когда автор готовил статью, выяснилось, что в коде около 150 пар вне спеки. Агент за один заход привёл 637 употреблений к спеке, добавил в неё 4 недостающие строки и переписал тест в белый список. Это главный практический урок: чёрный список ловит только то, что вы уже знаете, белый ловит всё остальное.

Если доки и код всё же разошлись, помогает порядок: сначала тесты, потом self-heal на проде (автор обещает отдельную статью), и только потом человек. Его задача не поймать баг, а понять, почему он прошёл, и закрыть эту дыру.

Ограничения и вывод

Подход требует дисциплины: нужно содержать тысячи документов в согласованном виде, а примеры автора касаются в основном типографики, где проверка простая. Для бизнес-логики спек-тесты написать сложнее. Это опыт одного проекта, цифры самоотчётные, а опрос под статьёй собрал один голос.

Практический вывод для тех, кто работает с агентами: вынесите правила в машиночитаемые спеки, пропишите в AGENTS.md обязательное чтение перед задачей и превратите самые частые отклонения в тесты с белыми списками. Сам каркас (AGENTS.md, CLAUDE.md и папка docs без кода) автор выложил на GitHub, так что начать можно с готового шаблона.