| name | adr |
| description | Создание Architectural Decision Record (ADR) с авто-нумерацией и фронтматтером для traceability.
Стандалонный навык — может вызываться напрямую без обёртки `/dd:req:adr`.
Используй когда пользователь просит:
- создать ADR / архитектурное решение
- задокументировать выбор между опциями
- зафиксировать технический trade-off
- оформить supersedes/superseded_by ссылки между решениями
|
Навык: Architectural Decision Record (ADR)
Цель
Создай ADR — короткий документ, фиксирующий архитектурное решение в момент его принятия: контекст, рассмотренные варианты, выбор, последствия.
ADR — это не код-ревью и не дизайн-документ. Это запись развилки на дороге, чтобы будущий разработчик понял, почему текущее решение именно такое и стоит ли его пересматривать.
Обязательные действия
1. Найди или создай каталог ADR
Стандартный путь: <repo-root>/requirements/adr/ (можно переопределить через paths.requirements_subdirs.adr в config.yaml).
Если каталога нет — спроси пользователя, создавать ли его. Не создавай молча.
2. Авто-нумерация
Просканируй каталог на файлы вида NNNN-*.md (4-значные номера). Возьми максимум, прибавь 1.
- Если каталог пуст — следующий номер
0001.
- Нумерация только локальная: ADR в одном репо не «знают» о ADR в другом.
Помощник: lib/frontmatter.sh::fm_next_adr_number <dir>.
3. Собери контекст интерактивно
Задавай вопросы по одному, ждя ответа. Если пользователь уже дал часть в первом сообщении — не переспрашивай.
- Контекст — какая сила требует решения сейчас? Какую проблему нельзя обойти, не выбрав?
- Ограничения — бюджет, команда, сроки, существующие обязательства.
- Стейкхолдеры — кого затрагивает (опционально; если есть
requirements/stakeholders/ — попробуй сослаться).
- Рассмотренные варианты — минимум 2 реалистичных альтернативы с pros/cons.
- Предлагаемое решение — какой вариант выбран и почему.
- Последствия — позитивные, негативные, нейтральные. Что станет проще? Что — сложнее?
- Связи — superseded_by / supersedes / связанные ADR / открытые вопросы, которые ADR закрывает.
4. Сохрани файл
Имя: NNNN-<kebab-slug>.md (slug через fm_slug из lib/frontmatter.sh).
Шаблон:
---
title: "ADR-NNNN: <title>"
status: proposed
date: <YYYY-MM-DD>
deciders: "<имя или команда>"
supersedes: []
superseded_by: []
traces_to:
vision: "requirements/vision/<file>.md" # если применимо
requirements: []
open_questions: []
related: []
---
# ADR-NNNN: <title>
## Status
Proposed — <date>
## Context
<Описание проблемы, сил, ограничений. Без решений — только постановка.>
## Options considered
### Option A: <название>
- Pros: …
- Cons: …
### Option B: <название>
- Pros: …
- Cons: …
(минимум 2; больше если уместно)
## Decision
We will <option X> because <главные причины>.
## Consequences
**Positive:**
- …
**Negative / mitigations:**
- …
**Neutral:**
- …
## Follow-ups
- [ ] Конкретное действие 1 (кто, к какому сроку)
- [ ] …
## Related
- [[ADR-YYYY]]
- …
5. Обнови индекс ADR (если есть)
Если в каталоге есть README.md или INDEX.md со сводной таблицей — добавь строку. Если нет — не создавай молча, спроси пользователя.
6. Зарезолви открытые вопросы (опционально)
Если ADR закрывает вопросы из requirements/open-questions/:
- Перенеси файл в
open-questions/resolved/.
- Добавь во frontmatter перенесённого файла
resolved_by: ADR-NNNN.
- Используй
git mv, чтобы сохранить историю.
7. Опционально: создать GitHub issue
Если пользователь работает с GitHub-репо и config.yaml это разрешает (github.adr_creates_issue: true) — предложи создать обсуждение через gh issue create. По умолчанию не создавай — это локальный артефакт.
8. Отчёт
ADR-NNNN proposed: <title>
File: <repo>/requirements/adr/NNNN-<slug>.md
Supersedes: <если есть>
Resolves open questions: <список>
Next: discuss → set status: accepted (manually or via PR review).
Гардрейлы
- Никогда не ставь
status: accepted при создании — только proposed. Принятие — человеческое решение, обычно через PR-ревью.
- Минимум 2 варианта. Если у пользователя «только один» — спроси, что было отвергнуто и почему. Один вариант = не решение, а отчёт.
- Не создавай каталог
requirements/adr/ молча. Спроси.
- Не модифицируй существующие ADR без явного запроса. Заменяй через supersedes.
- Если ADR меняет публичный инвариант (контракт API, обратная совместимость, лицензия) — выведи это явно в Consequences.
Чеклист качества ADR
