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

> Генерация Architecture Decision Records с AI: шаблон, библиотека промптов, автоматизация в CI, workflow в Claude Code — от решения до документа.
> Author: Roman Belov · Published: 2026-04-04 · Source: https://futurecraft.pro/ru/blog/adr-template-ai/

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

```markdown
# 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, 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 по промпту выше:

```markdown
# 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 этот процесс автоматизируется через команду:

```bash
# Получить diff последнего PR и сгенерировать ADR
gh pr view --json title,body,comments,files | \
  claude -p "Проанализируй PR и сгенерируй ADR, если обнаружишь архитектурное решение."
```

## Автоматизация: ADR как часть CI/CD pipeline

Ручная генерация ADR работает, но требует дисциплины. Автоматизация через CI убирает человеческий фактор.

### GitHub Action: проверка наличия ADR

```yaml
# .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

```bash
#!/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 проекта:

```markdown
## 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](/ru/blog/context-engineering-guide/).

## Частые ошибки при написании ADR

**Слишком абстрактный Context.** «Нам нужно было улучшить производительность» — бесполезно. «Время ответа API выросло до 2.3s при p95, SLA требует < 500ms» — полезно.

**Отсутствие Alternatives.** Без раздела альтернатив ADR выглядит как постфактум-оправдание, а не осмысленный выбор. Даже если альтернатива была одна (ничего не делать), это стоит зафиксировать.

**Слишком большой scope.** ADR фиксирует одно решение. «Переход на микросервисы» — это не одно решение, это десять. Каждый сервис, каждый контракт, каждый механизм коммуникации заслуживает отдельного ADR.

**Неактуальный Status.** ADR со статусом `Accepted`, который давно заменён другим решением, вводит в заблуждение. Обновление статуса на `Superseded by ADR-{N}` занимает секунды и экономит часы чужого времени.

**Путаница ADR с документацией.** ADR не описывает как работает система. ADR описывает почему система работает именно так. Как — это задача для [SOP и операционной документации](/ru/blog/sop-generator-ai-documentation/).

## Метрики: как измерить эффективность 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 в команде

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](https://belov.works).*