Design doc, ADR и технический долг

Design doc — до кода

Design doc — короткий документ, который пишут до начала крупной работы. Найденная на бумаге ошибка стоит часов, в коде — недель.

Структура:

1. Контекст и проблема — что происходит и почему это важно.
2. Цели и не-цели — что делаем и что сознательно не делаем.
3. Требования — нагрузка, данные, сроки.
4. Решение со схемой.
5. Альтернативы — и почему не они.
6. Риски и как их снимаем.
7. План внедрения и метрики успеха.

Три–шесть страниц, схемы вместо абзацев. Не-цели не менее важны, чем цели: они останавливают расползание задачи.

Как провести обсуждение

Документ рассылают заранее. На встрече его не читают вслух, а решают открытые вопросы. Приглашают тех, кого решение затронет: соседние команды, эксплуатацию, безопасность. Итог фиксируют — разделом «решение» или отдельным ADR. Ценность документа — в обсуждении, а не в самом тексте.

ADR — память о решениях

ADR (architecture decision record) — одна страница на одно значимое решение:

# ADR-0007: Очередь задач на RabbitMQ, а не на Kafka

Статус: принято (заменяет ADR-0003)

## Контекст
Фоновые задачи разной длительности, нужны повторы и приоритеты...

## Решение
RabbitMQ с отдельной очередью на тип задачи.

## Варианты
Kafka — перечитывание не нужно, медленная задача тормозит партицию...

## Последствия
Проще повторы и приоритеты; история событий не хранится.
Пересмотреть, если понадобится аналитика по событиям.

ADR хранят в репозитории, нумеруют и не переписывают: если решение меняется, пишут новый со ссылкой на старый. Пишут их для значимых решений: выбор базы, схема авторизации, деление на сервисы. Через год ADR отвечает на вопрос «почему так сделано?» — без него новые люди либо боятся трогать странный код, либо ломают то, что было сделано не зря.

Технический долг

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

• «код некрасивый» — не работает;
• «изменения в оплате занимают втрое дольше, четыре инцидента за квартал» — работает.

Как с ним жить:

• держать список долга с оценкой влияния и стоимости;
• гасить по частям вместе с задачами в той же области — правило бойскаута;
• выделять регулярную долю времени, например 15–20 %;
• крупные переделки обосновывать отдельно, как проект.

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

Что запомнить

• Design doc — до кода, с альтернативами и не-целями.
• На встрече решают вопросы, а не читают документ.
• ADR не переписывают — заменяют новым.
• Долг обсуждают в цифрах последствий.