← Назад ко всем статьям

Как использовать ADR и не превратить их в бюрократию

Опубликовано

Вести Architecture Decision Records (ADR) - отличная идея. Но если строго следовать всем рекомендациям по ADR, это быстро может превратиться в бюрократический кошмар.

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

Рекомендации по ведению ADR

  • Используйте один файл для всех записей, если у вас небольшой или новый проект и записей меньше 10.

  • Минимум текста, максимум смысла. Например, если вы выбрали PostgreSQL, кратко укажите почему. Не нужно перечислять все причины отказа от SQL Server, Oracle и других альтернатив.

  • Читаемость важнее формата. Пара предложений в свободной форме часто полезнее, чем строгие поля, заполненные только ради соответствия шаблону.

  • Фокусируйтесь на актуальности. Актуальность записей важнее их объема или строгого следования конкретному формату.

Что ADR должен содержать на самом деле

  • Дата решения. Храните записи в хронологическом порядке.

  • Заголовок. Кратко опишите решение.

  • Имя сотрудника. Через пару лет сотрудник может все еще работать в компании. Даже если нет, имя поможет найти коллег, которые знакомы с проектом и его историей.

  • Описание решения. Объясните, что именно было решено.

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

  • Ссылка на конкретный класс, если нужно. Например, если вы решили использовать Redis для caching данных, можно указать класс RedisCacheProvider.cs. Это может казаться избыточным, но так ADR попадает в контекст, доступный GitHub Copilot, и помогает ему понимать архитектурные решения проекта.

  • Уникальный ID записи. На ID и заголовок можно ссылаться из XML comments, например в RedisCacheProvider.cs. Это тоже может сделать работу с Copilot эффективнее.

Пример

# ADR-002: Choosing Redis for Data Caching

## Date

2025-01-23

## Author

John Smith

## Decision Description

We have chosen **Redis** for data caching because it fully meets our requirements:

- High operation speed due to in-memory data storage.
- TTL support for managing data expiration.
- Reliability and fault tolerance proven by years of use in our department.
- Existing infrastructure for Redis is already deployed and configured in both testing and production environments.

The class `RedisCacheProvider.cs` will be used to implement caching in the project.

## Consequences

- Potential limitations in memory consumption for large data volumes.
- Minimal risks, as the team already has experience working with Redis.

Заключение

Если у вас небольшой проект или недостаточно времени на документацию, упростите ведение ADR, но не отказывайтесь от него полностью. ADR-записи действительно могут быть полезны новым разработчикам, GitHub Copilot и сотрудникам, которые будут работать с проектом в будущем.