К ленте · Россия

РоссияСтатьяМодели

«Создай точную копию этой картинки, ничего не меняй». Что такое архитектурный дрифт и чем я его вылечил

«Создай точную копию этой картинки, ничего не меняй» 101 раз подряд. Автор: u/Foreign_Builder_2238, r/ChatGPT, апрель 2025 Человек попросил ChatGPT сделать точную копию картинки и ничего не менять....

Человек попросил ChatGPT сделать точную копию картинки и ничего не менять. Дал настоящую фотографию Дуэйна Джонсона. С каждой итерацией фотография менялась до неузнаваемости, пока не превратилась в мультяшное месиво. На каждом шаге он просил ничего не менять.

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

Это архитектурный дрифт. Даю пример с фронтенда как самый простой для восприятия, но принцип распространяется и на все другие зоны разработки. Основная проблема в том, что разъезжается source of truth.

Код я не читаю вообще. Я контролирую только спеки. Ниже, как пофиксить дрифт в агентной разработке.

Архитектурный дрифт лечится тремя принципами. Правдой является не код, а документация (спеки).

  • Single source of truth задаётся спеками.
  • ИИ обязан сначала прочитать спеки, ассоциированные с выполняемой задачей, перед её исполнением.
  • Спек-тесты детерминированным способом проверяют код на соответствие документации.

1. Single source of truth задаётся спеками

Как мы решаем проблему дрифта? С помощью принципа single source of truth. Истина находится в одном месте. И эта истина находится не в коде, а в документации.

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

Вся документация лежит в одной папке docs в корне проекта. Сейчас там более 7 тысяч документов, и каждый лежит на своём месте. Это не свалка, а структурированная папка с десятью уровнями вложенности, где в каждой папке в 90 % случаев не более 7 файлов. Я структурирую по правилу 7 плюс-минус 2: по ключевым сущностям в каждой папке не более 9 объектов. Поэтому я понимаю, где что находится.

папка docs на 5 ноября 2026

файлов .md

7 478

уровней вложенности под docs

11

папок, где не больше 7 файлов

95,3 %

папок, где не больше 9 файлов

97,4 %

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

На примере шрифтов. У меня все правила по типографике лежат в одном файле typography.md: все шрифты, размеры и цвета, как они выглядят на сайте.

Кусок реестра из typography.md , в полной таблице 22 роли:

роль

семейство

кегль (десктоп · моб)

вес

цвет

H1 карточки

Inter

52/56 · моб 34/38

700

#111111

H2 статьи

Inter

38/45 · моб 28/32

700

#111111

лид статьи

Charis

27/35 · моб 23/30

400

#111111

абзац статьи

Charis

21/30 · отступ 25px

400

#111111

база

Inter

14/21

400

#8A8A8A

мета

Inter

13/19

400

#8A8A8A

капшн

Inter

12/18

400

#8A8A8A

Два семейства на весь сайт: Charis для длинного чтения, Inter для всего остального. Веса только 400 и 700. (Из той же спеки: «состояний вне реестра не бывает: новая связка = новая строка по вердикту».)

Когда агент работает с каким-то куском проблемы, у него есть конкретная папка, в которой находится нужная документация. Из-за того, что каждый док на своём месте, агенту легко убедиться, что внутри папки ничто не противоречит задумке. Агент следит за тем, чтобы спеки находились в единообразном виде и ничто в них друг другу не противоречило.

2. ИИ читает спеки перед задачей

Его нужно заставить прочитать нужный док, и это прописано в базовом документе AGENTS.md. Там прописаны правила: он должен читать доки, которые соответствуют задаче. Когда мне нужно сделать изменение на сайте, агент сперва всегда прочитает папку с исходной документацией, и в 9 случаях из 10 не нарушит правила.

Например, я вижу, что улетели облачные расходы, и ставлю задачу провести аудит, разобраться, что можно подрезать. Агент должен пойти и прочитать всю документацию по облакам. Он увидит, что там есть отдельная папка прямо под это, увидит все облачные провайдеры и проанализирует их.

Из AGENTS.md, как есть:

3. Спек-тесты проверяют код

Спеки и админка находятся в недетерминированной плоскости: есть вероятность, что агент последует примерам или не последует. На десятый случай у нас есть спек-тесты. Мы пишем тест на базе спеки. В спеке написаны допустимые размеры шрифтов, а спек-тест смотрит, что на сайт не проходят другие размеры. Если мы выпускаем на сайт что-то, что не проходит спек-тест, оно не проходит.

Тест читает две таблицы typography.md, собирает из колонки «кегль» разрешённые пары и обходит весь фронтенд. Пара или кегль, которых нет в спеке, валит сборку с именем файла и строкой:

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

когда

что пришло от агента

что сделал тест

чем кончилось

1 октября 2026

карточки цен на странице услуг с парами 14/20 и 12/16

сборка красная: «вытесненная типо-пара»

пары заменены на 14/21 и 12/18 из спеки, коммит 1797f67

Когда док и код расходятся, в действие вступают три вещи. Первое, этап тестирования, который должен выловить проблему. Второе, self-heal, который выловит проблему уже на проде. Про него будет отдельная статья. А если первое и второе не сработали, вступаю я как человек. Моя задача не выловить проблему, а понять, почему этот косяк прошёл, и сделать так, чтобы в следующий раз он уже не прошёл.

Постоянно бывает, что спека была, а агент сделал по-своему. Зачастую это связано с тем, что агент не прочитал нужную спеку. Для этого у нас жёсткие правила, чтобы он читал. Но иногда приходится прямо ткнуть его в нужную спеку.

Коротко

Одна из основных целей всего подхода: иметь один single source of truth. И то, как мы это инфорсим спек-тестами, это и есть то, как мы решаем проблему архитектурного дрифта.

Слово не новое: пару architectural drift / architectural erosion ввели Перри и Вульф в 1992 году в статье Foundations for the Study of Software Architecture. С агентами оно ожило снова: The Spec Growth Engine, октябрь 2026. На Хабре: «Что делать с архитектурным дрифтом в эпоху ИИ?», апрель 2026.

Если начинаете с нуля

Если хотите внедрить это у себя: берите мой Spec Driven Company. Он открытый, и это ровно то, чем пользуюсь я сам: AGENTS.md, CLAUDE.md и папка docs, кода внутри нет, только спеки.

А где у вас находится source of truth: в коде, в доках или в головах? Напишите в комментариях, что у вас разъехалось первым. Вопросы в Telegram: личный @shilovevgeny, канал @shilovtech.

Источник: Хабр · статьиПубликуется с разрешения правообладателя, подтверждённого редакцией.Оригинал: «Создай точную копию этой картинки, ничего не меняй». Что такое архитектурный дрифт и чем я его вылечил ↗

Есть кому отправить?

Скопируется постоянная ссылка на этот материал.

Комментарии

Обсуждайте статью, отвечайте и оценивайте комментарии. Вход — через ваш Яндекс ID.

Загружаем обсуждение…