ADR Template + промпты: AI пишет архитектурные решения за 5 минут

Команды принимают десятки архитектурных решений в месяц, а документируют единицы. Остальные растворяются в 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 ниже 50% означает, что процесс не прижился. Time-to-ADR больше недели означает, что контекст теряется и запись превращается в художественную реконструкцию.

Чеклист: внедрение ADR в команде

1. Создать директорию docs/adr/ и шаблон
2. Написать 3–5 ADR для уже принятых решений (ретроспективно, с помощью AI)
3. Добавить скрипт new-adr.sh для быстрого создания
4. Настроить GitHub Action с мягким предупреждением (не блокировкой)
5. Включить ключевые ADR в CLAUDE.md / .cursorrules для AI-агентов
6. Ревьюить ADR так же, как код: через PR
7. Раз в квартал проходить по всем ADR и обновлять статусы

Первые три пункта занимают 30 минут с AI. Остальные — вопрос привычки, которая формируется за 2–3 спринта.

Нужна помощь с внедрением ADR и документированием архитектурных решений? Я помогаю стартапам внедрять AI-решения и строить продукты — belov.works.