Как отследить, что меняется в архитектуре моей системы?

#Что это такое

История изменений

Смысловая разница между двумя снимками технической картины системы: компоненты, интерфейсы, связи и утверждения, которые появились, изменились, исчезли или перестали подтверждаться. Это не диф исходников — единица здесь компонент или утверждение, а не строка.

Если проще Запись о том, как техническая картина вашей системы сдвинулась от одного анализа к другому, — не о том, каким был диф кода, а о том, что он означал.

Система контроля версий уже отвечает на вопрос «какие строки изменились». У этого вопроса есть безупречный ответ, и это не тот вопрос, который задаёт владелец. Здесь вопрос звучит так: «что стало другим в моей системе», — и ответ на него это список вещей, а не список правок.

#Четыре ответа

#Больше не подтверждается

Категория, которая существует только потому, что картину хранят, а не переписывают.

У написанного архитектурного документа два состояния: актуальный и тихо неверный. Он переходит из одного в другое без всякого события, и никто не узнаёт об этом, пока кто-нибудь на него не сошлётся.

У утверждения в 1ADK есть третье состояние. В него верили, у него было доказательство, и последний анализ его больше не поддерживает. Такое утверждение не удаляют и не оставляют стоять — его помечают как больше не подтверждаемое, с датой, когда оно поддерживалось в последний раз.

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

#Почему удаление — сложный случай

Сообщить, что что-то добавилось, легко. Сообщить, что что-то удалили, — значит знать, что вы посмотрели туда, где оно было.

Каждый анализ записывает свой охват: какие области прочитаны целиком, частично или не прочитаны вовсе. Там, где нынешний анализ не покрыл область, в которой жил компонент, 1ADK не сообщает компонент удалённым. Он сообщает, что компонент в этот раз не видели, — а это другое и меньшее высказывание.

Полного охвата само по себе тоже недостаточно. Анализ, который прочитал папку целиком и просто не упомянул компонент, дал молчание; анализ, который говорит, что искал этот компонент и его там нет, дал доказательство. Как удалённое сообщается только второе. Первое становится вопросом к человеку — отсутствие упоминания не есть удаление, как бы тщательно ни читали. Это правило стоит продукту самого эффектного экрана и оно же делает экран достойным чтения.

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

#Почему тождество — самое трудное

По-настоящему сложная инженерная задача за всем этим, названная прямо.

Чтобы сказать, что компонент изменился, а не что один компонент исчез, а другой появился, два анализа должны сойтись в том, что говорят об одной и той же вещи. Названий для этого недостаточно:

• Переименуйте класс — это всё тот же класс.
• Назовите две вещи «Основная база» — это всё равно две разные вещи.
• Передвиньте файл — и всякое тождество по пути ломается разом.

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

Это та часть продукта, на которую ушло больше всего работы, и покупателю о ней стоит знать по одной причине: инструмент, который так не умеет, вообще не может иметь истории изменений. Он способен лишь показать вам два списка рядом и предложить сравнить их самостоятельно.

#Два анализа в сравнении

ПОЯВИЛОСЬ
  Обработчик просрочек        ФОНОВЫЙ ОБРАБОТЧИК
  Очередь платежей            ОЧЕРЕДЬ
    → сервис биллинга теперь публикует в неё, а не вызывает
      провайдера напрямую

ИЗМЕНИЛОСЬ
  Сервис биллинга
    было: вызывает платёжного провайдера напрямую
    стало: публикует в очередь платежей

ИСЧЕЗЛО
  Ночная выгрузка             ЗАДАНИЕ ПО РАСПИСАНИЮ
    → утверждается: этот анализ смотрел в app/ и не нашёл её

БОЛЬШЕ НЕ ПОДТВЕРЖДАЕТСЯ
  «Неудачный платёж повторяется на месте, три раза».
    последнее подтверждение  ·  анализ от 14 мая 2026
    причина                  ·  кода, поддерживавшего это
                                утверждение, больше нет; поведение
                                при повторах теперь в обработчике
                                просрочек и не установлено

НОВОЕ НЕИЗВЕСТНОЕ
  Что происходит с платежом, который обработчик просрочек не смог
  провести?

Такова форма ответа, нарисованная так, чтобы все пять блоков читались разом. У демонстрационного проекта есть настоящее: 2 вымышленных анализа, прогнанных по тому же конвейеру, по которому идёт собственное сканирование клиента, и сравнённых тем же кодом. Двух минут стоит одна строка, которую пришлось заслужить. Появилось вещей: 3, а Nightly CSV export сообщён как исчезнувшее — не потому, что поздний анализ о нём умолчал, а потому, что этот анализ прямо говорит: он прочитал папку, где эта вещь жила, от начала до конца и искал её там. Уберите это утверждение — и то же самое молчание даст вам вопрос, что и есть правило из раздела выше и единственный случай, где оно стоит продукту более красивого экрана.

В том же сравнении есть и строка, которая не является ни появлением, ни уходом. Billing service был прочитан обоими анализами по одному и тому же адресу, и второй читает его иначе: строка говорит изменилось. Ровно об этом раздел выше — сравнение, которое не смогло бы понять, что два прочтения об одной вещи, напечатало бы уход и появление и начало бы его заново как нечто новое.

Верить на слово не нужно, потому что в том же сравнении есть и вторая половина. Invoice PDF renderer лежит в той же папке, прочитанной столь же тщательно, — и второй анализ его не упоминает. Охват одинаковый, утверждения нет, и 1ADK не назовёт его исчезнувшим: строка читается как больше не подтверждается и говорит, какой из двух это случай и на каком основании. Из второго анализа ушли оба. Из системы, насколько кто-либо может показать, ушло только то, что этот анализ искал.

#Что владельцы с этим делают

• Перед релизом. Не «что мы слили», а «что теперь другое в системе», прочитанное за час, а не восстановленное из пул-реквестов.
• После окончания работы подрядчика. Сравнение анализа в начале и анализа в конце — самый прямой отчёт о том, что действительно построили.
• При вводе технического руководителя. Последние четыре сравнения скажут новому техническому директору о направлении системы больше, чем её текущее состояние.
• Для проверки работы агента. Там, где много кода написали быстро, сравнение — простой способ увидеть форму того, что появилось.

#Чего это не скажет