📐 Что это
Architecture Decision Records (ADR) — это навык для Claude Code, который автоматически фиксирует архитектурные решения, принятые во время сессии разработки, в структурированных документах (ADR). Вместо того чтобы решения оставались в переписке, PR-комментариях или памяти участников, этот навык создаёт формальные записи рядом с кодом. Он помогает командам отвечать на вопрос «почему код устроен так, а не иначе» — как сейчас, так и через год после принятия решения.
⚙️ Как работает
🎯 Детектирование момента решения
Навык распознаёт как явные, так и неявные сигналы, указывающие на архитектурный выбор:
- Явные сигналы (автоматическая запись): фразы вроде «давайте запишем это решение», «сделайте для этого ADR», «мы выбрали X вместо Y, потому что...», «причина, по которой мы выбрали X...».
- Неявные сигналы (предложение создать ADR, но не автоматически): сравнение фреймворков, выбор библиотеки, дизайн схемы БД, решение между архитектурными паттернами (монолит vs микросервисы), выбор стратегии аутентификации или развёртывания.
📝 Формат записи (адаптированный Michael Nygard)
Каждый ADR создаётся в файле docs/adr/NNNN-decision-title.md и содержит следующие обязательные разделы:
- Заголовок:
ADR-NNNN: [Название решения], дата, статус (предложено/принято/устарело/заменено), участники решения.
- Контекст: 2–5 предложений о проблеме, ограничениях и предпосылках.
- Решение: 1–3 предложения, ясно формулирующих выбранный подход.
- Рассмотренные альтернативы: для каждой — плюсы, минусы и причина отказа.
- Последствия: позитивные, негативные и риски (с мерами смягчения).
Кроме того, ведётся индекс docs/adr/README.md со сводной таблицей всех ADR, и опционально — template.md для ручного использования.
🔄 Жизненный цикл ADR и рабочий процесс
-
Создание нового ADR:
- При первом запуске навык спрашивает разрешения на инициализацию директории
docs/adr/ (без согласия файлы не создаются).
- При обнаружении решения навык собирает контекст, альтернативы и последствия, назначает следующий номер
NNNN, сканируя существующие файлы.
- Показывает пользователю черновик ADR для проверки. Только после явного одобрения записывает файл на диск и обновляет индекс. Если пользователь отвергает черновик — он отбрасывается.
-
Чтение существующего ADR:
- На вопрос «почему мы выбрали X?» навык проверяет наличие
docs/adr/, ищет в индексе релевантную запись и зачитывает контекст и решение. Если запись не найдена, предлагает создать новую.
-
Статусы: proposed → accepted → deprecated или superseded by ADR-NNNN. При замене всегда указывается ссылка на новый ADR.
🚦 Сигналы для записи
Навык рекомендует фиксировать решения в следующих категориях:
- Технический стек (фреймворк, язык, БД, облачный провайдер)
- Архитектурные паттерны (монолит/микросервисы, событийно-ориентированная, CQRS)
- Дизайн API (REST/GraphQL, аутентификация)
- Моделирование данных (схема, нормализация, кэширование)
- Инфраструктура (модель развёртывания, CI/CD, мониторинг)
- Безопасность (стратегия аутентификации, шифрование, управление ключами)
- Тестирование (фреймворк, покрытие, баланс E2E и интеграционных тестов)
- Процессы (ветвление, ревью, релизный цикл)
🚫 Чего не стоит записывать
Тривиальные решения (нейминг переменных, форматирование), слишком длинные контексты, отсутствие альтернатив, запись без указания реальной даты, «забытые» устаревшие ADR без ссылки на замену.
✅ Когда использовать
- В начале нового проекта — заложить фундамент зафиксированных решений.
- Во время архитектурного ревью или спринта — чтобы не потерять обоснование выбора.
- При онбординге новых разработчиков — быстрый ответ на вопрос «почему?».
- В случаях, когда решение было сложным и содержит много trade-off'ов.
- При планировании крупных изменений — создаётся
proposed ADR для обсуждения.
- Интеграция с другими агентами: Planning Agent (предложение ADR при архитектурных изменениях), Code Review Agent (проверка, что к PR с архитектурными изменениями приложен ADR).
⚠️ Важно знать
- Безопасный подход к файловой системе: навык никогда не создаёт файлы без явного подтверждения пользователя. Это защищает от случайной записи.
- Порядок имеет значение: навык автоматически определяет следующий номер ADR, сканируя
docs/adr/, поэтому удаление или ручное добавление файлов может нарушить нумерацию.
- Язык: в конфигурации навыка указан Китайский (
zh), что влияет на язык сообщений-подсказок, но сами ADR документы, скорее всего, будут на английском (в примерах — английские заголовки). При использовании проверьте настройки локализации.
- Не пытайтесь записать всё: навык содержит чёткие критерии, что достойно ADR, а что — нет. Используйте это как руководство, чтобы не плодить излишнюю документацию.
- Ручной шаблон:
template.md в docs/adr/ позволяет создавать ADR вручную, не дожидаясь автоматического детектирования.
Комментарии
Комментариев пока нет. Будьте первым.