ADR Template: How AI Generates Architecture Decision Records Your Future Self Will Thank You For
Что такое Architecture Decision Record (ADR)?
Architecture Decision Record (ADR) — документ, фиксирующий одно архитектурное решение: контекст, который его потребовал, что именно решили, последствия и отвергнутые альтернативы. Концепция предложена Майклом Найгардом в 2011 году, используется в Spotify и GitHub. ADR хранится рядом с кодом в репозитории и формирует институциональную память команды. AI генерирует черновик ADR за 3-5 минут из описания решения на естественном языке.
TL;DR
- -ADR снижают время онбординга и предотвращают повторный анализ принятых решений — Spotify и GitHub связывают улучшение DX с систематическим ведением ADR
- -Секция Alternatives Considered пропускается чаще всего и приносит максимум пользы: фиксирует, почему отвергнутые варианты не подошли, а не только то, что выбрали
- -AI генерирует полный черновик ADR за 3-5 минут вместо 30-40 минут вручную; ключ — конкретные метрики вместо размытого контекста
- -Ретроспективная генерация ADR из PR-диффов практична: специализированный промпт извлекает архитектурные решения из Git-истории с точностью 80%+
- -ADR coverage ниже 50% архитектурных PR означает, что процесс не прижился; Time-to-ADR больше недели означает, что контекст уже потерян
Команды принимают десятки архитектурных решений в месяц, а документируют единицы. Остальные растворяются в Slack-переписках, устных обсуждениях и головах людей, которые через год уйдут из компании.
Через шесть месяцев новый разработчик смотрит на код и задаёт вопрос: «Почему здесь Redis, а не PostgreSQL для очередей?» Никто не помнит. Начинается археология по Git-истории, Slack, Notion — два часа на расследование решения, которое заняло 15 минут.
Architecture Decision Records (ADR) решают эту проблему. Но их не пишут. Причина проста: оформление ADR занимает 30–40 минут, а разработчик уже переключился на следующую задачу. AI сокращает это до 3–5 минут. Статья описывает структуру ADR, промпты для генерации через LLM, реальные примеры и автоматизацию через CI pipeline.
Что такое ADR и зачем фиксировать архитектурные решения
ADR (Architecture Decision Record) — документ, фиксирующий одно конкретное архитектурное решение. Не спецификация, не RFC, не дизайн-документ. Одно решение, один файл.
Концепцию предложил Michael Nygard в 2011 году. Формат прижился в крупных компаниях (Spotify, Thoughtworks, GitHub), но в небольших командах остаётся редкостью. Основная причина: overhead на написание воспринимается выше пользы.
Три ситуации, где отсутствие ADR бьёт сильнее всего:
Онбординг. Новый разработчик читает код и видит нестандартное решение. Без ADR он либо тратит часы на расследование, либо принимает решение за ошибку и «исправляет» его. Оба варианта дорого обходятся команде.
Пересмотр решений. Контекст меняется: нагрузка выросла, появились новые требования, зависимость устарела. Без записи о том, почему было выбрано текущее решение и какие альтернативы отклонили, команда заново проходит весь путь анализа.
Аудит и compliance. В регулируемых отраслях (fintech, healthtech) требуется обоснование архитектурных решений. ADR закрывает этот вопрос автоматически.
Структура ADR-шаблона: 7 обязательных секций
Минимально жизнеспособный ADR содержит семь секций. Каждая отвечает на конкретный вопрос.
# ADR-{номер}: {Название решения}
## Status
Proposed | Accepted | Deprecated | Superseded by ADR-{номер}
## Date
2026-03-26
## Context
Какая проблема или ситуация вынуждает принять решение?
Технические ограничения, бизнес-требования, текущее состояние системы.
## Decision
Что именно решили. Конкретная формулировка без размытых фраз.
## Consequences
Положительные и отрицательные последствия решения.
Что становится проще, что становится сложнее.
## Alternatives Considered
Какие варианты рассматривали и почему отклонили.
Критерии сравнения, trade-offs.
## References
Ссылки на issues, PR, обсуждения, документацию, бенчмарки.
Status имеет четыре значения. Proposed — решение на обсуждении. Accepted — принято и применяется. Deprecated — решение устарело, но замена ещё не выбрана. Superseded by ADR-{N} — заменено новым решением с прямой ссылкой.
Context — самая важная секция. Без контекста решение теряет смысл. «Выбрали Redis для кэширования» ничего не значит. «Выбрали Redis для кэширования, потому что PostgreSQL LISTEN/NOTIFY не обеспечивал sub-millisecond latency для autocomplete при 10K RPS» — значит всё.
Alternatives Considered — секция, которую чаще всего пропускают и которая приносит больше всего пользы. Когда через год встанет вопрос «а почему не Kafka?», ответ уже зафиксирован.
Промпт для генерации ADR через AI
Базовый промпт, который работает с Claude, GPT-4, Gemini:
Ты — senior software architect. Сгенерируй ADR (Architecture Decision Record)
по следующему шаблону.
РЕШЕНИЕ: {описание принятого решения}
КОНТЕКСТ ПРОЕКТА:
- Стек: {языки, фреймворки, инфраструктура}
- Масштаб: {нагрузка, размер команды, стадия продукта}
- Ограничения: {бюджет, сроки, compliance, legacy}
ФОРМАТ ВЫВОДА:
# ADR-{номер}: {Название}
## Status
Accepted
## Date
{текущая дата}
## Context
Опиши проблему, которая привела к решению. Укажи технические и бизнес-факторы.
Конкретные метрики, если применимы. 3-5 предложений.
## Decision
Сформулируй решение одним абзацем. Без слов "решили", "будем" — только факты.
Укажи scope: что входит в решение, что не входит.
## Consequences
### Positive
- Перечисли 3-5 конкретных улучшений
### Negative
- Перечисли 2-3 trade-offs или риска
## Alternatives Considered
Для каждой альтернативы:
### {Название альтернативы}
- Описание в 1-2 предложения
- Причина отклонения (конкретная, не "не подошло")
## References
- Ссылки на релевантные ресурсы
ПРАВИЛА:
- Активный залог, без воды
- Конкретные метрики вместо "быстрее/лучше/проще"
- Если данных для метрик нет — укажи качественные критерии
- Каждый пункт Consequences должен быть верифицируемым
Этот промпт закрывает 80% случаев. Для оставшихся 20% нужны специализированные варианты.
Продвинутые промпты: миграция, выбор технологии, отказ от решения
Промпт для ADR о миграции
Миграция — решение с самым высоким риском и самым длинным горизонтом последствий.
Сгенерируй ADR для миграции.
ОТКУДА: {текущее решение, версия, сколько в продакшене}
КУДА: {целевое решение}
ПРИЧИНА МИГРАЦИИ: {что сломалось или перестало устраивать}
Дополнительно к стандартному шаблону добавь секции:
## Migration Strategy
- Подход: Big Bang | Strangler Fig | Parallel Run
- Обоснование подхода
- Этапы миграции с ожидаемыми сроками
## Rollback Plan
- Условия отката
- Процедура отката
- Допустимое окно для отката
## Success Criteria
- Метрики, по которым миграция считается завершённой
- Период стабилизации после миграции
Промпт для ADR о выборе технологии
Сгенерируй ADR для выбора технологии.
ЗАДАЧА: {какую проблему решает выбранная технология}
КАНДИДАТЫ: {список рассмотренных вариантов}
ВЫБОР: {победитель}
Дополнительно:
## Evaluation Criteria
Таблица сравнения кандидатов по критериям:
| Критерий | Вес | {Кандидат 1} | {Кандидат 2} | {Кандидат 3} |
Критерии: performance, DX, community/support, cost, learning curve, integration
## Proof of Concept
- Что проверяли на PoC
- Результаты с цифрами
Промпт для ADR об отказе от решения (Deprecated/Superseded)
Сгенерируй ADR, фиксирующий отказ от ранее принятого решения.
ИСХОДНЫЙ ADR: {номер и название}
ПРИЧИНА ОТКАЗА: {что изменилось с момента принятия решения}
ЗАМЕНА: {новое решение, если есть}
Дополнительно:
## What Changed
- Конкретные изменения контекста, которые сделали решение неактуальным
- Дата или событие, после которого стало очевидно
## Lessons Learned
- Что команда узнала из опыта использования предыдущего решения
- Как это влияет на будущие аналогичные решения
Пример: ADR для реального проекта
Команда выбирает стратегию кэширования для API travel-приложения. Вот что генерирует AI по промпту выше:
# ADR-012: Redis для кэширования ответов внешних API
## Status
Accepted
## Date
2026-03-26
## Context
API travel-приложения вызывает внешние сервисы (Foursquare, weather, flights)
для каждого пользовательского запроса. Средний response time: 800ms при
холодном вызове. 40% запросов — повторные обращения к тем же данным в
пределах 15-минутного окна (пользователь переключается между вкладками,
обновляет страницу). Rate limits внешних API: 500 req/min (Foursquare),
1000 req/min (weather). При 200 DAU текущая нагрузка составляет 60% от лимита.
## Decision
Использовать Redis (Upstash Serverless) как кэш-слой между edge functions
и внешними API. TTL: 15 минут для геоданных, 60 минут для погоды, 5 минут
для цен на авиабилеты. Cache key: `{api}:{endpoint}:{normalized_params_hash}`.
Стратегия инвалидации: TTL-based, без ручной инвалидации на первом этапе.
## Consequences
### Positive
- Response time для кэшированных запросов: 800ms → 15-25ms (Upstash REST API)
- Потребление rate limits снижается на 40% при текущем паттерне использования
- Edge functions освобождаются быстрее, снижая потребление compute-ресурсов
### Negative
- Дополнительная зависимость: Upstash (managed, но всё равно точка отказа)
- Stale data в пределах TTL: пользователь может увидеть устаревшую цену билета
- Стоимость: ~$5/mo при текущей нагрузке, масштабируется с ростом
## Alternatives Considered
### In-memory cache (Map в Deno-изоляте)
Нулевая latency, но state теряется при cold start. При текущей частоте cold
starts (каждые 3-5 минут) hit rate составит менее 20%. Не оправдывает
сложность реализации.
### Cloudflare KV
Eventual consistency с задержкой до 60 секунд. Для кэширования цен билетов
приемлемо, но для геоданных (пользователь перемещается) создаёт UX-проблемы.
Стоимость сопоставима с Redis.
### PostgreSQL materialized views
Требует переработки слоя данных. Не подходит для edge functions из-за
latency на connect (50-100ms vs 5-15ms у Redis REST API).
## References
- Upstash Redis REST API: https://docs.upstash.com/redis
- Foursquare rate limits: https://docs.foursquare.com/reference/rate-limits
Обратить внимание на конкретику. Нет фраз «улучшает производительность» или «снижает нагрузку». Есть цифры: 800ms → 15–25ms, 40% снижение rate limit consumption, $5/mo. Каждый пункт можно проверить через полгода.
Генерация ADR из Git-истории и PR-описаний
AI умеет извлекать архитектурные решения из уже существующих артефактов. Это закрывает проблему «мы приняли решение три месяца назад и забыли задокументировать».
Промпт для ретроспективной генерации:
Проанализируй следующий PR (diff + описание + комментарии) и определи,
содержит ли он архитектурное решение. Если да — сгенерируй ADR.
PR TITLE: {название}
PR DESCRIPTION: {описание}
PR DIFF (ключевые файлы):
{diff}
PR COMMENTS:
{комментарии к review}
Критерии архитектурного решения:
- Добавление новой зависимости
- Изменение структуры данных или схемы БД
- Новый паттерн (кэширование, очереди, retry strategy)
- Изменение API-контракта
- Выбор между двумя+ подходами (зафиксированный в обсуждении)
Если PR не содержит архитектурного решения — ответь "No ADR needed" с
кратким обоснованием.
Для Claude Code этот процесс автоматизируется через команду:
# Получить diff последнего PR и сгенерировать ADR
gh pr view --json title,body,comments,files | \
claude -p "Проанализируй PR и сгенерируй ADR, если обнаружишь архитектурное решение."
Автоматизация: ADR как часть CI/CD pipeline
Ручная генерация ADR работает, но требует дисциплины. Автоматизация через CI убирает человеческий фактор.
GitHub Action: проверка наличия ADR
# .github/workflows/adr-check.yml
name: ADR Check
on:
pull_request:
types: [opened, synchronize]
jobs:
check-adr:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Detect architectural changes
id: detect
run: |
CHANGED_FILES=$(gh pr diff ${{ github.event.pull_request.number }} --name-only)
ADR_NEEDED=false
# Новые зависимости
if echo "$CHANGED_FILES" | grep -q "package.json\|Cargo.toml\|go.mod\|requirements.txt"; then
ADR_NEEDED=true
fi
# Миграции БД
if echo "$CHANGED_FILES" | grep -q "migration\|schema"; then
ADR_NEEDED=true
fi
# Конфигурация инфраструктуры
if echo "$CHANGED_FILES" | grep -q "docker\|terraform\|cloudflare\|nginx"; then
ADR_NEEDED=true
fi
echo "adr_needed=$ADR_NEEDED" >> $GITHUB_OUTPUT
- name: Check for ADR file
if: steps.detect.outputs.adr_needed == 'true'
run: |
CHANGED_FILES=$(gh pr diff ${{ github.event.pull_request.number }} --name-only)
if ! echo "$CHANGED_FILES" | grep -q "^docs/adr/"; then
echo "::warning::This PR contains architectural changes but no ADR. Consider adding one to docs/adr/"
fi
env:
GH_TOKEN: ${{ github.token }}
Этот workflow не блокирует PR, а выдаёт предупреждение. Блокировка через ADR создаёт friction, который убивает adoption.
Структура файлов ADR в репозитории
docs/
└── adr/
├── README.md # Индекс всех ADR
├── template.md # Шаблон
├── 001-use-astro.md
├── 002-redis-caching.md
└── 003-event-driven.md
Нумерация через три цифры с ведущими нулями. Файлы в хронологическом порядке. Один файл — одно решение.
Скрипт для создания нового ADR
#!/bin/bash
# scripts/new-adr.sh
ADR_DIR="docs/adr"
LAST_NUM=$(ls "$ADR_DIR" | grep -oP '^\d+' | sort -n | tail -1)
NEXT_NUM=$(printf "%03d" $((10#$LAST_NUM + 1)))
SLUG=$(echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
FILENAME="${ADR_DIR}/${NEXT_NUM}-${SLUG}.md"
cat > "$FILENAME" << EOF
# ADR-${NEXT_NUM}: $1
## Status
Proposed
## Date
$(date +%Y-%m-%d)
## Context
<!-- Какая проблема вынуждает принять решение? -->
## Decision
<!-- Что решили? -->
## Consequences
### Positive
-
### Negative
-
## Alternatives Considered
###
-
## References
-
EOF
echo "Created: $FILENAME"
Использование: ./scripts/new-adr.sh "Switch from REST to GraphQL".
Интеграция ADR с context engineering для AI-агентов
ADR приобретают дополнительную ценность как контекст для AI-кодинга. Когда AI-агент (Claude Code, Cursor, Copilot) работает с кодобазой, ADR дают ему архитектурный контекст, которого нет в самом коде.
Добавление ADR в CLAUDE.md проекта:
## Architecture Decisions
Key ADRs to follow when making changes:
- ADR-005: Event-driven architecture for notifications (docs/adr/005-event-driven.md)
- ADR-008: PostgreSQL RLS for multi-tenancy (docs/adr/008-rls-multitenancy.md)
- ADR-012: Redis caching strategy (docs/adr/012-redis-caching.md)
AI-агент учитывает эти решения при генерации кода. Вместо того чтобы предлагать REST-вызов для уведомлений, он использует event bus, потому что ADR-005 зафиксировал это решение. Подробнее о структурировании контекста для AI — в гайде по context engineering.
Частые ошибки при написании ADR
Слишком абстрактный Context. «Нам нужно было улучшить производительность» — бесполезно. «Время ответа API выросло до 2.3s при p95, SLA требует < 500ms» — полезно.
Отсутствие Alternatives. Без раздела альтернатив ADR выглядит как постфактум-оправдание, а не осмысленный выбор. Даже если альтернатива была одна (ничего не делать), это стоит зафиксировать.
Слишком большой scope. ADR фиксирует одно решение. «Переход на микросервисы» — это не одно решение, это десять. Каждый сервис, каждый контракт, каждый механизм коммуникации заслуживает отдельного ADR.
Неактуальный Status. ADR со статусом Accepted, который давно заменён другим решением, вводит в заблуждение. Обновление статуса на Superseded by ADR-{N} занимает секунды и экономит часы чужого времени.
Путаница ADR с документацией. ADR не описывает как работает система. ADR описывает почему система работает именно так. Как — это задача для SOP и операционной документации.
Метрики: как измерить эффективность ADR-практики
Четыре метрики, которые показывают, работают ли ADR в команде:
| Метрика | Как измерить | Целевое значение |
|---|---|---|
| ADR coverage | Кол-во ADR / кол-во архитектурных PR за месяц | > 70% |
| Time-to-ADR | Время от принятия решения до записи ADR | < 24 часа |
| Reference rate | Как часто ADR упоминаются в PR и обсуждениях | > 2 раза/месяц на ADR |
| Onboarding feedback | Новые участники оценивают полезность ADR (1-5) | > 4.0 |
ADR coverage ниже 50% означает, что процесс не прижился. Time-to-ADR больше недели означает, что контекст теряется и запись превращается в художественную реконструкцию.
Чеклист: внедрение ADR в команде
- Создать директорию
docs/adr/и шаблон - Написать 3–5 ADR для уже принятых решений (ретроспективно, с помощью AI)
- Добавить скрипт
new-adr.shдля быстрого создания - Настроить GitHub Action с мягким предупреждением (не блокировкой)
- Включить ключевые ADR в CLAUDE.md / .cursorrules для AI-агентов
- Ревьюить ADR так же, как код: через PR
- Раз в квартал проходить по всем ADR и обновлять статусы
Первые три пункта занимают 30 минут с AI. Остальные — вопрос привычки, которая формируется за 2–3 спринта.
FAQ
Нужно ли ревьюить ADR через pull request, как код?
Да, это наиболее эффективный подход. Ревью ADR через PR делает архитектурные записи аудируемыми, позволяет членам команды оспорить или уточнить решение до его фиксации, и создаёт естественную связь между изменением кода и его обоснованием. Процесс ревью также выявляет разногласия заранее: ADR, обсуждаемый в PR, лучше, чем спорное решение, обнаруженное через полгода реализации.
Какая правильная гранулярность ADR — один на сервис или один на значимое решение?
Один ADR — одно атомарное решение. Выбор Redis для кэширования и выбор Upstash как managed-провайдера — два отдельных ADR. «Переход на микросервисы» — не один ADR, это минимум один на каждую границу сервиса, один на протокол коммуникации, один на стратегию деплоя. Слишком широкие ADR теряют точность; слишком узкие превращаются в шум.
Как работать с ADR при поглощении компании или получении унаследованной кодовой базы?
Воспринимать унаследованные ADR как непроверенные гипотезы. Читать для контекста, но проверять каждый на соответствие текущему состоянию системы. Часть решений устарела (библиотека deprecated, предположение о нагрузке изменилось), часть по-прежнему актуальна. Быстрый путь — однодневный «ADR audit sprint»: прочитать все ADR, обновить поля Status, добавить краткую заметку там, где контекст изменился. Эта инвестиция окупается в первый месяц разработки.