Ваша архитектурная диаграмма уже ложь

Каждая архитектурная диаграмма, которую я видел в вики, была неверной. Не катастрофически неверной. Просто тихо, постепенно неверной. Сервис с пометкой «Auth» был разделён на три микросервиса полгода назад. Стрелка с пометкой «sync call» теперь асинхронна через очередь. База данных с пометкой «PostgreSQL» была мигрирована на что-то другое во время пожарной ситуации, и никто не обновил прямоугольник.

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

Цель не в том, чтобы писать документы, которые никогда не устареют. Цель в том, чтобы обнаружить рассогласование до того, как оно введёт в заблуждение следующего инженера.

Почему документы устаревают быстрее, чем код

У кода есть встроенный механизм коррекции: он либо компилируется и проходит тесты, либо нет. У документации нет компилятора, нет набора тестов, нет CI-вороток. Неверная диаграмма отрисовывается идеально. Устаревший ADR читается так же убедительно, как и свежий.

Расхождение также социальное. Инженеры обновляют код, потому что сборка ломается. Они обновляют документы, потому что чувствуют вину. Вина — ненадёжный планировщик.

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

Три ловушки художественной литературы

Есть три места, где архитектурная документация быстрее всего превращается в художественную литературу.

Кладбище вики. Архитектурные документы в Confluence, Notion или SharePoint живут вне репозитория. У них нет истории коммитов, коррелированной с изменениями кода. Когда рефакторинг удаляет сервис, страница вики выживает как цифровой город-призрак. Ни одна сборка не падает. Ни один алерт не срабатывает.

Художественная диаграмма. Красивая диаграмма, экспортированная из Lucidchart или draw.io и вставленная в README, выглядит авторитетно. Но это статичное изображение. Следующий разработчик, который меняет архитектуру, должен открыть инструмент дизайна, найти исходный файл, обновить его, повторно экспортировать и вставить обратно. У этого workflow выживаемость 5%.

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

Живая документация, которая остаётся честной

Решение не в том, чтобы писать больше документов. А в том, чтобы сделать документы неизбежными.

Переместите документы в репозиторий. Если документация не находится в том же pull request, что и изменение кода, она не будет обновлена. ADR, runbooks и журналы решений должны жить в docs/architecture/ или docs/adr/ рядом с кодом, который они описывают. Когда ревьюер видит рефакторинг без обновления документов, он может заблокировать merge.

Генерируйте диаграммы из кода. Mermaid, PlantUML и Structurizr позволяют определять диаграммы в текстовых файлах, которые живут в репозитории. CI-job рендерит их при каждом коммите. Когда архитектура меняется, исходник диаграммы меняется вместе с ней. Никакой инструмент дизайна не требуется.

<!-- docs/architecture/data-flow.md -->
## Ingestion Pipeline

```mermaid
graph LR
    A[Client SDK] -->|HTTP POST| B[Ingest API]
    B -->|Pub/Sub| C[Event Consumer]
    C -->|Write| D[(ClickHouse)]


Эта диаграмма ревьюируется в diff. Когда pipeline получает новый Kafka topic, изменение появляется в том же PR, который добавляет consumer.

**Разделяйте «что» от «почему».** Кодовая база уже описывает, что делает система. Комментарии, имена функций и типы кодируют текущую структуру. Документация должна фокусироваться на том, почему система выглядит так, как выглядит. Именно это тихо устаревает: обоснование решения, а не само решение.

Architecture Decision Records захватывают это. ADR — это не спецификация. Это помеченная временем заметка, которая говорит: «В эту дату, по этим причинам, мы выбрали это. Вот ограничения, которые мы приняли.» Когда ограничения меняются, ADR заменяется новым. Старая запись остаётся как история.

## Автоматизируйте «что», пишите «почему"

Самая честная архитектурная документация — та, которую вы не пишете вручную.

OpenAPI-спецификации, генерируемые из controller-кода, точно описывают вашу API-поверхность. TypeDoc, RustDoc или Javadoc описывают ваши внутренние типы. Графы зависимостей, генерируемые `cargo tree`, `go mod graph` или `webpack-bundle-analyzer`, показывают реальную структуру модулей.

Для архитектурных ограничений более высокого уровня автоматизированные архитектурные тесты выступают как предохранительная сетка. В Java ArchUnit может применять правила вроде «никакой пакет в `domain` не может зависеть от `infrastructure`.» В Python `import-linter` делает то же самое. В Go вы можете написать небольшой тест, который обходит AST и ломает сборку, если появляется запрещённый import.

```java
// This test fails the build if architecture rules break.
@ArchTest
static final ArchRule domain_independence =
    noClasses()
        .that().resideInAPackage("..domain..")
        .should().dependOnClassesThat()
        .resideInAPackage("..infrastructure..");

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

Компромиссы, которые никто не признаёт

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

Не каждой системе нужна диаграмма. Один монолит с тремя слоями не нуждается в C4-модели. Усилия на поддержку сгенерированных документов должны быть пропорциональны боли от непонимания системы. Если неверная ментальная модель стоит вам дня дебаггинга, инвестируйте час в диаграмму. Если пять минут — напишите комментарий.

Сгенерированные документы тоже могут лгать. OpenAPI-спецификация, сгенерированная из кода, описывает каждый endpoint, включая внутренние, которые вы забыли задокументировать. Граф зависимостей показывает каждый import, включая те, которые нарушают вашу архитектуру. Сгенерированная правда точна, но не всегда полезна. Вам всё ещё нужна человеческая куратория, чтобы подсветить то, что важно.

ADR накапливаются. Через два года у вас может быть тридцать ADR в docs/adr/. Большинство будут нерелевантны. Решение не в том, чтобы их удалять. А в том, чтобы чётко помечать: status: superseded со ссылкой на замену. История имеет ценность. Путаница — нет.

Минимальная настройка, которая работает

Вам не нужна платформа документации. Вам нужны три вещи в вашем репозитории.

docs/adr/YYYY-MM-DD-title.md для решений. Используйте лёгкий шаблон:

# ADR 012: Event Storage Backend

- Status: accepted
- Date: 2026-03-15

## Context
We need durable storage for ingestion events with sub-second query latency.

## Decision
Use ClickHouse for hot storage, S3 for cold archival.

## Consequences
- Fast analytical queries on recent data.
- Complex operational footprint compared to PostgreSQL.
- Migration path defined in ADR 013.

docs/architecture/*.md с Mermaid-диаграммами для системных границ и потоков данных. Требуйте обновления документов в том же PR, что и структурные изменения кода.
Один архитектурный тест, который применяет ваше самое дорогостоящее инвариантное правило. Если у вас есть только одно правило, пусть это будет то, которое предотвращает последний болезненный рефакторинг. Добавляйте больше по мере роста системы.

FAQ

Нужно ли мне рисовать диаграмму для каждого микросервиса?

Нет. Рисуйте границы, где команды передают друг другу работу, где данные пересекают зоны доверия и где отказы каскадируют. Диаграмма вашего внутреннего CRUD-сервиса обычно — отходы. Диаграмма того, какие сервисы вызывают payment gateway, обычно — ценность.

А если моя команда уже использует Confluence?

Дублируйте критические документы в репозитории и делайте ссылки. Источник истины остаётся в git. Вики становится удобным слоем. Если вики устареет, инженеры знают, где найти реальную версию.

Сколько ADR — это слишком много?

Верхнего предела нет, но есть предел читаемости. Если новый инженер не может просмотреть docs/adr/ и понять эволюцию системы за десять минут, добавьте индекс. Группируйте по подсистемам. Чётко помечайте заменённые записи.

А как насчёт вики для нетехнических стейкхолдеров?

Продуктовые менеджеры и руководители нуждаются в высокоуровневых саммари. Генерируйте их из индекса ADR. Не поддерживайте отдельный нарратив. Одни и те же факты должны течь от исходного кода, через ADR, в человеческие саммари. Один источник истины, множество представлений.

Начните с одного ADR и одного теста

Вам не нужно перестраивать культуру документации на этой неделе. Выберите последнее архитектурное решение, которое вызвало путаницу. Напишите один ADR, объясняющий, почему вы выбрали то, что выбрали. Выберите один инвариант, который вы хотели бы применять автоматически. Напишите один архитектурный тест, который ломает сборку, когда кто-то его нарушает.

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