От 300+ закладок к рабочей архитектурной системе

У меня была привычка: вижу классный материал по архитектуре — сохраняю.

Статья про DDD, репозиторий с CQRS, видео про системный дизайн, тред про масштабирование. Всё в «потом». Вы знаете, чем обычно заканчивается «потом».

В какой-то момент у меня было 300+ закладок. Половина ссылок — мёртвые, часть — дубли, остальное — материалы, которые ночью казались гениальными, а утром не давали ничего практического.

Я сел и вычистил всё до 106 ресурсов. Собрал их в awesome-software-design на GitHub.

Список ресурсов: github.com/QDenka/awesome-software-design

Но важнее не сам список. Важнее три вывода, которые сильно поменяли мой подход:

1. Нужно агрессивно фильтровать «контент-иллюзии».
2. ADR экономят время команды сильнее, чем кажется.
3. Если архитектурное правило не проверяется в CI — его не существует.

Что не попало — и почему это полезнее самого списка

1) Мёртвые репозитории

Признаки:

• последний коммит несколько лет назад,
• открытые critical issues без ответа,
• зависимости устарели на 1–2 major версии,
• no activity, no maintenance signal.

Звёзды в GitHub не гарантируют живой проект. Для reference-ресурсов важнее актуальность и сопровождение, чем историческая популярность.

2) Клоны без добавленной ценности

Отдельная категория — «переписали известный паттерн на другом языке» без практики:

• нет тестов,
• нет контекста применения,
• нет компромисс,
• нет production edge-cases.

Если материал не добавляет ничего сверх оригинала — это шум.

3) Контент ради контента

Формат «10 ошибок архитектуры, которые совершают все» часто звучит убедительно, но не даёт шага к действию.

Мой фильтр простой: можно ли завтра применить это в коде/процессе?

Если нет — в архив.

ADR: практика, которую недооценивают

Architecture Decision Record звучит бюрократично, пока не столкнёшься с реальным проектом.

Типичный сценарий:

• новый инженер видит «странное» решение,
• хочет заменить его «на нормальное»,
• тратит 1–2 дня,
• выясняет, что решение было осознанным из-за контекста, который нигде не записан.

Один короткий ADR мог сэкономить это время.

Минимальный формат ADR

Достаточно трёх блоков:

• Контекст — какая проблема/ограничения,
• Решение — что выбрали,
• Последствия — какие компромисс и что это значит дальше.

Хранить лучше рядом с кодом: docs/adr/.

Где это реально работает

• Kubernetes (KEP-процесс),
• Rust (RFC как история эволюции решений),
• Spotify (практика передачи контекста между командами),
• GOV.UK (публичные архитектурные решения).

Общий паттерн один: решение без контекста быстро превращается в «странный легаси-код».

Как начать без идеального шаблона

Не выбирай тулу и формат неделями.

Возьми одно решение прошлой недели и зафиксируй в 10–15 строк:

• почему приняли,
• что выбрали,
• чем заплатили.

Этого уже достаточно, чтобы команда перестала терять контекст.

Архитектурные тесты: если правило не в CI — его нет

Команда может договориться о чём угодно:

• «контроллеры не ходят в репозитории напрямую»,
• «домен не зависит от инфраструктуры»,
• «в адаптерах только внешняя интеграция».

Проблема в том, что договорённость в Notion/Asana не защищает от регрессии.

Через месяц сроки поджимают, кто-то делает «временный» shortcut, review пропускает — и границы начинают расползаться.

Что менять

Правило архитектуры должно быть:

1. формализовано,
2. автоматически проверяемо,
3. блокировать merge при нарушении.

Тогда это не пожелание, а инженерный контракт.

Инструменты по языкам (минимальный набор)

• Java — ArchUnit
• C# — ArchUnitNET
• PHP — Arkitect / Pest Arch
• Go — arch-go
• Kotlin — Konsist

Это частный случай fitness functions: архитектурные свойства проверяются так же, как unit-тесты.

Быстрый старт

Не пытайся описать всю архитектуру за один день.

Сделай одно правило:

Доменный слой не зависит от инфраструктурного.

Запусти в CI, посмотри, где ломается. Через месяц добавь второе правило.

Эволюция важнее «идеальной карты правил» в первый день.

Почему прод-кейсы полезнее книг и абстракций

Книги объясняют паттерн. Прод-кейсы объясняют, где паттерн не сработал и какой компромисс выбрали.

Вот три класса кейсов, которые стоит читать регулярно:

1) Масштаб и bottleneck

Сценарии вроде Discord показывают, что «заменить базу» обычно не магическое решение. Часто выигрыш приходит от промежуточного слоя, кэш-коалесинга и управления горячими точками.

2) Границы в большом монолите

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

3) Осознанный выбор более простого алгоритма

Кейсы типа Figma важны тем, что показывают: «правильный компромисс» чаще ценнее «самого мощного теоретического подхода».

Что в итоге должно остаться у инженера

После чистки списка и пересборки подхода я оставляю только то, что усиливает практику в проекте.

Минимальный рабочий набор:

1. Reference implementations (живые и поддерживаемые),
2. ADR-примеры (как фиксировать контекст решений),
3. Architecture testing (как защищать границы автоматически),
4. Real-world case studies (как принимаются решения под реальными ограничениями).

Чеклист, который можно применить сегодня

• Удалить 30–50% закладок без практической ценности
• Завести docs/adr/ и записать 1 решение этой недели
• Добавить 1 архитектурный тест в CI
• Раз в неделю разбирать 1 прод-кейс с командой

Короткая история из команды

В команде эта практика начала приносить пользу только после того, как её закрепили в ежедневном процессе: в ревью, CI и пост-релизной проверке.

Вывод

Сильная архитектурная культура строится не количеством сохранённых ссылок.

Она строится повторяемыми практиками:

• фиксировать контекст (ADR),
• автоматизировать правила (architecture tests),
• учиться на реальных кейсах, а не на абстракциях.

Если знаешь ресурс, который реально изменил инженерную практику — присылай. Особенно интересны ADR-кейсы из русскоязычных компаний и инструменты архитектурных тестов для менее популярных стеков.

Ещё раз ссылка на список: https://github.com/QDenka/awesome-software-design