Уровень: «базу IT знаешь, практики мало». ADR — не бюрократия ради галочки, а короткая память «почему мы так сделали», чтобы через месяц не спорить с собой и с ИИ заново.
Шаблоны и имена файлов — в decisions/README.md. Здесь — зачем, когда, как писать хорошо и как не расползтись.
ADR = запись об архитектурном (или процессном с долгим хвостом) решении: контекст → варианты → выбор → последствия.
Это не:
Это да:
plan/decisions/ и не предлагает пятый раз Drizzle, если уже accepted Prisma (или наоборот).apps/*;Эвристика: если через месяц вопрос «а почему так?» будет стыдно не вспомнить — нужен ADR.
На Фазе 0 у нас уже намечены кандидаты (см. backlog):
| Тема | Issue / место |
|---|---|
| Пакетный менеджер + тулчейн монорепы | #15 |
| NestJS vs Fastify | после Фазы 0 |
| Prisma vs Drizzle | после Фазы 0 |
| Auth для одного пользователя | после Фазы 0 |
| Стратегия merge (squash vs merge commit) | по желанию, если начнёт болеть |
| Статус | Смысл |
|---|---|
proposed |
Черновик, ещё выбираем |
accepted |
Живём по этому |
superseded by ADR-XXX |
Старое решение заменено новым ADR |
deprecated / rejected |
Редко; можно просто superseded |
Правило: не молча переписывать accepted-ADR под новое решение. Лучше новый файл 00N-… со статусом accepted, а в старом — superseded by ADR-00N. История выбора сохраняется.
Имя файла: NNN-краткое-название.md, например 001-monorepo-tooling.md.
Не «нужен ORM». А:
Контекст отвечает на: какую задачу решаем и при каких правилах игры.
Минимум два реальных варианта + иногда «ничего не делать».
На каждый вариант коротко:
Плохо: один вариант и три абзаца хвалы.
Хорошо: таблица или нумерованный список честных минусов.
Одна ясная фраза: выбрали X.
Потом 3–8 предложений «почему X при нашем контексте», не «потому что модно».
Обязательный блок. Дели на:
Если минусов нет — ты недодумал или решение слишком мелкое для ADR.
Базовый шаблон — в decisions/README.md. Когда вариантов много, можно так:
# NNN. Заголовок
Дата: YYYY-MM-DD
Статус: proposed | accepted | superseded by ADR-XXX
Связанные issues: #15
Связанные PR: …
## Контекст
…
## Критерии выбора
Что для нас важнее (упорядочить):
1. скорость старта
2. обучение паттернам с рынка
3. простота деплоя
4. …
## Варианты
### A. …
Плюсы: …
Минусы: …
### B. …
Плюсы: …
Минусы: …
### C. Ничего не менять
…
## Решение
Выбираем … потому что …
## Последствия
### Плюсы
- …
### Минусы и долги
- …
### Что сделать сразу
- [ ] …
## Отклонённое (чтобы не поднимать снова)
Кратко: почему не B/C.
Критерии выбора — секрет сильного ADR: без них спор скатывается в «мне больше нравится Nest».
proposed) по твоей развилке и фактам из чата.Хороший ритуал:
accepted (или просишь переписать).Типичная ошибка: неделю пилить Nest, потом «ой, надо было Fastify», и ADR задним числом.
Лучший порядок для дорогих решений:
#15) в Ready / In Progress.proposed → обсуждение → accepted.app-15md или app-10… уже по принятому решению.Refs ADR-001 / Closes #15.Исключение: крошечный выбор внутри уже принятой рамки (имя папки) — без ADR.
| Артефакт | Вопрос |
|---|---|
| Issue | Что сделать |
| ADR | Какое правило/стек выбираем надолго |
| PR / ветка | Как изменение попало в dev |
| Project | Где задача в потоке |
ADR не заменяет issue. Issue #15 может быть: «принять ADR по тулчейну монорепы и набросать структуру».
После accept карточка Done, файл ADR живёт в plan/decisions/ вечно (пока не superseded).
Перед accepted пробегись:
Антипаттерны:
Ниже — иллюстрация формы, не решение DPline. Реальный выбор по монорепе сделаем в #15.
# 001. Тулчейн монорепы (пример формы)
Дата: 2026-07-18
Статус: proposed
Связанные issues: #15
## Контекст
Нужны `apps/web` и `apps/api` в одном репо. Один разработчик, мало часов в неделю,
хочется простой DX и навыки, близкие к вакансиям junior+.
## Критерии выбора
1. Простой старт
2. Нормальная документация
3. Удобные workspace-скрипты
4. Не закрывать путь к CI (#14)
## Варианты
### A. pnpm + Turborepo
Плюсы: частый стек в индустрии, кэш задач, понятные pipelines.
Минусы: ещё один инструмент besides pnpm; кривая обучения.
### B. npm workspaces без turbo
Плюсы: меньше сущностей.
Минусы: слабее оркестрация сборки; позже всё равно захочется task runner.
### C. Отдельные репозитории
Плюсы: изоляция.
Минусы: боль для одного человека, дубли CI, сложнее шарить типы.
## Решение
(пример) Выбираем A, потому что критерий 2–3 важнее минимализма B,
а C противоречит решению «монорепа» из plan/main.md.
## Последствия
Плюсы: один PR может трогать web+api; единый CI-вход.
Минусы: нужно выучить базовые команды turbo/pnpm.
Сразу: корневой package.json, pnpm-workspace.yaml, пустые apps/, README «как поднять».
Когда будете делать настоящий #15 — ассистент набросит такой же каркас под ваши критерии.
Порядок:
plan/main.md + roadmap.md — рамка продукта.plan/decisions/* со статусом accepted` — жёсткие ограничения на советы.Если совет противоречит accepted ADR — либо явное предложение нового ADR (supersede), либо отказ от совета. «Давайте тихо сменим ORM» — антипаттерн.
ADR только про код?
Нет. У нас допустимы процессные ADR (стратегия веток, правила merge), если они реально правят работу. Мелочи процесса — в working-agreement.
Сколько ADR нормально за месяц?
На Фазе 0 ожидаемо 1–3. Если их 15 — вы дробите слишком мелко.
Нужно ли идеально с первого раза?
Нет. proposed → правка → accepted. Страх чистого файла хуже отсутствующей памяти.
Где хранить?
Только в git: plan/decisions/. Не в Notion как единственная копия (можно зеркало, но source of truth — репо).
#15 и следующие ADR