Architecture Decision Records (ADRs)

Упрощайте проектирование ПО с навыком ADR для Claude Code. Автоматически фиксируйте, документируйте и отслеживайте архитектурные решения прямо в вашем репозитории.

Обучение и документация ★ 172,009 GitHub (172,009 ★)

Навык «Architecture Decision Records» позволяет Claude Code автоматически выявлять ключевые архитектурные моменты — например, выбор базы данных, фреймворка или шаблона API — и документировать обоснование этих решений. Ведя структурированный журнал контекста, альтернатив и последствий в вашем репозитории, он сохраняет «почему» вашей кодовой базы для будущих разработчиков. Навык управляет полным жизненным циклом ADR: от первоначального предложения до замены, легко встраиваясь в ваш процесс разработки и превращая сиюминутные решения в постоянную документацию.

Ключевые возможности

01Контекстный поиск существующих решений для ответа на вопросы «почему»

02172,009 звезд на GitHub

03Автоматическое обнаружение точек принятия архитектурных решений в процессе диалога

04Полное отслеживание жизненного цикла решений (предложено, принято, устарело или заменено)

05Стандартизированный формат ADR Майкла Найгарда, включающий контекст, альтернативы и последствия

06Автоматическое управление каталогом (docs/adr/) и обновление индекса для поиска

Варианты использования

01Введение новых членов команды в курс дела с помощью исторической записи технических обоснований

02Фиксация выбора конкретных библиотек или технологий баз данных для проекта

03Документирование архитектурных компромиссов при переходе от монолита к микросервисам

name	architecture-decision-records
description	Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is.
origin	ECC

Architecture Decision Records

Capture architectural decisions as they happen during coding sessions. Instead of decisions living only in Slack threads, PR comments, or someone's memory, this skill produces structured ADR documents that live alongside the code.

When to Activate

User explicitly says "let's record this decision" or "ADR this"
User chooses between significant alternatives (framework, library, pattern, database, API design)
User says "we decided to..." or "the reason we're doing X instead of Y is..."
User asks "why did we choose X?" (read existing ADRs)
During planning phases when architectural trade-offs are discussed

ADR Format

Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development:

# ADR-NNNN: [Decision Title]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]

## Context

What is the issue that we're seeing that is motivating this decision or change?

[2-5 sentences describing the situation, constraints, and forces at play]

## Decision

What is the change that we're proposing and/or doing?

[1-3 sentences stating the decision clearly]

## Alternatives Considered

### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]

### Alternative 2: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]

## Consequences

What becomes easier or more difficult to do because of this change?

### Positive
- [benefit 1]
- [benefit 2]

### Negative
- [trade-off 1]
- [trade-off 2]

### Risks
- [risk and mitigation]

Workflow

Capturing a New ADR

When a decision moment is detected:

Initialize (first time only) — if docs/adr/ does not exist, ask the user for confirmation before creating the directory, a README.md seeded with the index table header (see ADR Index Format below), and a blank template.md for manual use. Do not create files without explicit consent.
Identify the decision — extract the core architectural choice being made
Gather context — what problem prompted this? What constraints exist?
Document alternatives — what other options were considered? Why were they rejected?
State consequences — what are the trade-offs? What becomes easier/harder?
Assign a number — scan existing ADRs in docs/adr/ and increment
Confirm and write — present the draft ADR to the user for review. Only write to docs/adr/NNNN-decision-title.md after explicit approval. If the user declines, discard the draft without writing any files.
Update the index — append to docs/adr/README.md

Reading Existing ADRs

When a user asks "why did we choose X?":

Check if docs/adr/ exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?"
If it exists, scan docs/adr/README.md index for relevant entries
Read matching ADR files and present the Context and Decision sections
If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"

ADR Directory Structure

docs/
└── adr/
    ├── README.md              ← index of all ADRs
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← blank template for manual use

ADR Index Format

# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |

Decision Detection Signals

Watch for these patterns in conversation that indicate an architectural decision:

Explicit signals

"Let's go with X"
"We should use X instead of Y"
"The trade-off is worth it because..."
"Record this as an ADR"

Implicit signals (suggest recording an ADR — do not auto-create without user confirmation)

Comparing two frameworks or libraries and reaching a conclusion
Making a database schema design choice with stated rationale
Choosing between architectural patterns (monolith vs microservices, REST vs GraphQL)
Deciding on authentication/authorization strategy
Selecting deployment infrastructure after evaluating alternatives

What Makes a Good ADR

Do

Be specific — "Use Prisma ORM" not "use an ORM"
Record the why — the rationale matters more than the what
Include rejected alternatives — future developers need to know what was considered
State consequences honestly — every decision has trade-offs
Keep it short — an ADR should be readable in 2 minutes
Use present tense — "We use X" not "We will use X"

Don't

Record trivial decisions — variable naming or formatting choices don't need ADRs
Write essays — if the context section exceeds 10 lines, it's too long
Omit alternatives — "we just picked it" is not a valid rationale
Backfill without marking it — if recording a past decision, note the original date
Let ADRs go stale — superseded decisions should reference their replacement

ADR Lifecycle

proposed → accepted → [deprecated | superseded by ADR-NNNN]

proposed: decision is under discussion, not yet committed
accepted: decision is in effect and being followed
deprecated: decision is no longer relevant (e.g., feature removed)
superseded: a newer ADR replaces this one (always link the replacement)

Categories of Decisions Worth Recording

Category	Examples
Technology choices	Framework, language, database, cloud provider
Architecture patterns	Monolith vs microservices, event-driven, CQRS
API design	REST vs GraphQL, versioning strategy, auth mechanism
Data modeling	Schema design, normalization decisions, caching strategy
Infrastructure	Deployment model, CI/CD pipeline, monitoring stack
Security	Auth strategy, encryption approach, secret management
Testing	Test framework, coverage targets, E2E vs integration balance
Process	Branching strategy, review process, release cadence

Integration with Other Skills

Planner agent: when the planner proposes architecture changes, suggest creating an ADR
Code reviewer agent: flag PRs that introduce architectural changes without a corresponding ADR

🧱 Что это

Architecture Decision Records (ADRs) — это навык для фиксации архитектурных решений прямо во время сессии разработки. Вместо того чтобы решения оставались в Slack-тредах, комментариях к PR или в памяти одного разработчика, этот навык создаёт структурированные документы ADR, которые живут рядом с кодом. Навык автоматически распознаёт моменты принятия решений, записывает контекст, рассмотренные альтернативы и обоснование, а также ведёт журнал ADR, чтобы будущие разработчики понимали, почему кодовая база устроена именно так.

⚙️ Как работает

🎯 Обнаружение момента решения

Навык реагирует на явные и неявные сигналы в диалоге:

Явные сигналы — пользователь говорит «давай запишем это решение», «ADR это», «мы решили использовать X вместо Y», «компромисс оправдан, потому что...»
Неявные сигналы — сравнение двух фреймворков или библиотек с выводом, выбор схемы БД с обоснованием, обсуждение архитектурных паттернов (монолит vs микросервисы, REST vs GraphQL), решение по стратегии аутентификации или инфраструктуре развёртывания. В таких случаях навык предлагает записать ADR, но не создаёт его без подтверждения.

📝 Формат ADR

Используется облегчённый формат Майкла Найгарда, адаптированный для AI-assisted разработки:

Заголовок: ADR-NNNN: [Название решения]
Метаданные: Дата, статус (proposed | accepted | deprecated | superseded by ADR-NNNN), участники
Контекст: 2–5 предложений о проблеме, ограничениях и движущих силах
Решение: 1–3 предложения, чётко формулирующие выбор
Рассмотренные альтернативы: Для каждой — название, плюсы, минусы, причина отклонения
Последствия: Положительные эффекты, негативные компромиссы, риски и их mitigation

📂 Структура директории

docs/
└── adr/
    ├── README.md              ← индекс всех ADR
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← шаблон для ручного использования

🔄 Рабочий процесс

Создание нового ADR:

Инициализация (только при первом использовании) — если docs/adr/ не существует, навык запрашивает разрешение на создание директории, README.md с заголовком таблицы индекса и template.md. Файлы не создаются без явного согласия.
Определение решения — извлечение ключевого архитектурного выбора
Сбор контекста — какая проблема привела к решению, какие ограничения существуют
Документирование альтернатив — какие ещё варианты рассматривались и почему отклонены
Формулировка последствий — какие компромиссы, что становится проще/сложнее
Назначение номера — сканирование существующих ADR в docs/adr/ и инкремент
Подтверждение и запись — навык показывает черновик ADR пользователю. Запись в docs/adr/NNNN-decision-title.md происходит только после явного одобрения. Если пользователь отказывается, черновик отбрасывается без записи.
Обновление индекса — добавление строки в docs/adr/README.md

Чтение существующих ADR:

Если пользователь спрашивает «почему мы выбрали X?», навык проверяет наличие docs/adr/
Если директории нет — отвечает, что ADR не найдены, и предлагает начать запись
Если есть — сканирует индекс README.md на предмет подходящих записей
Читает соответствующие ADR-файлы и показывает разделы Context и Decision
Если совпадений нет — сообщает об этом и предлагает записать новое решение

🏷️ Жизненный цикл ADR

proposed → accepted → [deprecated | superseded by ADR-NNNN]

proposed — решение обсуждается, ещё не принято
accepted — решение в силе, используется
deprecated — решение больше не актуально (например, функциональность удалена)
superseded — новое ADR заменяет это (обязательно указывается ссылка на замену)

🎯 Когда использовать

Навык особенно полезен в следующих ситуациях:

Выбор технологий — фреймворк, язык, база данных, облачный провайдер
Архитектурные паттерны — монолит vs микросервисы, event-driven, CQRS
Дизайн API — REST vs GraphQL, стратегия версионирования, механизм аутентификации
Моделирование данных — дизайн схемы, решения по нормализации, стратегия кэширования
Инфраструктура — модель развёртывания, CI/CD пайплайн, стек мониторинга
Безопасность — стратегия аутентификации, подход к шифрованию, управление секретами
Тестирование — тестовый фреймворк, целевое покрытие, баланс E2E и интеграционных тестов
Процессы — стратегия ветвления, процесс ревью, ритм релизов

💡 Важно знать

Не записывайте тривиальные решения — выбор именования переменных или форматирования не требует ADR
Будьте конкретны — «использовать Prisma ORM», а не «использовать ORM»
Записывайте «почему» — обоснование важнее, чем само решение
Включайте отклонённые альтернативы — будущим разработчикам нужно знать, что рассматривалось
Честно указывайте последствия — у каждого решения есть компромиссы
Держите кратко — ADR должен читаться за 2 минуты. Если контекст превышает 10 строк — он слишком длинный
Используйте настоящее время — «мы используем X», а не «мы будем использовать X»
Не заполняйте задним числом без пометки — если записываете прошлое решение, укажите оригинальную дату
Не допускайте устаревания — заменённые решения должны ссылаться на замену

🔗 Интеграция с другими навыками

Planner agent — когда планировщик предлагает архитектурные изменения, навык предлагает создать ADR
Code reviewer agent — навык может помечать PR, которые вносят архитектурные изменения без соответствующего ADR

Установите одной командой.

npx skillfish add affaan-m/everything-claude-code architecture-decision-records

Источник: https://mcpmarket.com/tools/skills/architecture-decision-records-adrs-4