Как сеньоры документируют проекты: протокол архитектурных решений

Это перевод статьи автора Мангабо Колаволе с портала DevTo с комментариями экспертов.

Есть одна задача, которую программисты терпеть не могут — но именно она отличает хорошего инженера от посредственного: как они документируют свой проект? Несколько лет назад я отвечал за запуск финтех-проекта. Мы выбрали стратегию быстрого старта, поэтому масштабируемость не стала для нас приоритетом. Главной целью было проверить гипотезу — и мы двигались вперёд, разрабатывая API, архитектуру и системы — с упором на простоту, не особенно задумываясь о будущем.

Но я отвечал за бэкенд и инфраструктуру — и понимал: как бы хороша ни была моя память, через шесть месяцев я не смогу вспомнить все технические детали.

Во время работы я наткнулся на подход, который мне очень понравился: ADR — Architectural Decision Record, или «протокол архитектурных решений».

По сути, это документ, в котором фиксируются все изменения, внесённые в архитектуру: само решение, его влияние и полученные уроки.

Проще говоря, это как личный дневник — только для всей команды.

Почему это важно?

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

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

Будущие разработчики скажут вам спасибо. Подумайте о человеке, который через пять лет будет разбираться в вашем коде. Если вы не оставили объяснений, он, скорее всего, будет мучиться, пытаясь понять, зачем было сделано то или иное изменение. А теперь представьте другого разработчика в другой компании, который находит ADR-документ с чётким объяснением принятого решения. Он, без сомнения, будет вам благодарен.

Синьор-фронтендер из ВК Маргарита Лукина, автор телеграм-канала «Фронтенд кухня»:

Ценность ADR я впервые осознала в 2019 году. В команду, где работала, активно набирали новых ребят, и приблизительно раз в неделю кто-нибудь из новых разработчиков спрашивал "а почему это сделано так, а не иначе?" Приходилось постоянно давать ответы на одни и те же вопросы, и тогда-то я и поняла, насколько будет удобно записывать ответы где-нибудь в документацию в confluence и просто кидать ссылку новичкам.

В 2019 году я еще не знала сам термин ADR и говорила "документация". С термином я познакомилась совсем недавно — этим летом, на курсе по архитектуре монолитных приложений. Тогда я поняла, насколько эффективно можно использовать ADR для ускорения разработки и уменьшения TTM. Дело в том, что начиная разрабатывать новый проект, разработчик первое время (от месяца до полугода! всё зависит от размера проекта) погружается в проект — разбирается, как всё устроено, чтобы вносить изменения соответственно архитектуре. В этот период разработчик, по сути, составляет собственные adr — обычно в виде мыслеобразов в своей голове :) Если записать основные решения, разработчик сможет намного быстрее погрузиться в проект.

Как писать ADR?

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

Вдохновившее меня соглашение можно найти на GitHub . Вы также можете ознакомиться с процессом ADR на Amazon.

Вот пример шаблона, который вы можете использовать.

			# Example Title: Database Choice for User Data
## Context and Problem Statement
We need a scalable database to store and manage user data efficiently as our user base grows.
## Decision Drivers
* Scalability
* Data consistency
* Ease of integration with existing services
## Considered Options

* PostgreSQL
* MongoDB
* Amazon DynamoDB
## Decision Outcome
Chosen option: **PostgreSQL** because it provides strong data consistency and aligns well with our need for complex queries.
### Consequences
* **Good:** Supports ACID compliance, enhancing data reliability.
* **Bad:** May require more tuning to achieve high performance with large datasets.
### Confirmation
We’ll confirm this decision through periodic load tests and performance reviews as the user base scales.
## Pros and Cons of the Options
### PostgreSQL
* **Good:** ACID compliance, robust community support.
* **Neutral:** Setup and tuning can be time-consuming.
* **Bad:** Lacks native horizontal scaling.
### MongoDB
* **Good:** Schema flexibility, horizontal scaling.
* **Bad:** No ACID compliance across collections, limiting data integrity.
## More Information
For additional details, see the database performance evaluation [here](link-to-evaluation).

		

Такой тип документа может находиться прямо в репозитории проекта, в Confluence или, например, в JIRA.

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

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

Синьор-фронтендер из ВК Маргарита Лукина, автор телеграм-канала «Фронтенд кухня»:

Многие руководители хотят видеть на своём проекте разработчиков, которые "сразу, без раскачки" начнут перформить. Совсем избежать периода погружения невозможно, но можно ускорить его в десятки раз за счёт ADR