Шаблон документа решения#
Версия: 6.5 · 2026-09-22 · правила версионирования
Один документ — одно проектное решение. Документ не содержит принятого решения: он ведёт к нему и задаёт форму записи. Принятое решение живёт в ADR конкретного проекта и ссылается сюда.
Когда заводить документ#
Отбор по двум осям — цене изменения и влиянию:
| Дёшево изменить | Дорого изменить | |
|---|---|---|
| Высокое влияние | Короткая форма — своя, см. ниже | Полная форма: все разделы |
| Низкое влияние | Не документируем | Обычно значит, что решение можно отложить |
Влияние считается по двум признакам: видно ли пользователю и видно ли в счёте. Обратимое решение с большим влиянием на экономику — класс хранения, стратегия кэша, размер пула — заслуживает короткой формы.
Третий вопрос, до матрицы: не делает ли существующая карточка большую часть этой работы? Карточка и документ решения — разные жанры, но не всегда разные документы. Иногда карточка уже содержит сравнение вариантов, умолчание и главный вопрос — и тогда заводить документ значит переписать её своими словами.
| Что в карточке уже есть | Что это значит |
|---|---|
| Сравнение вариантов с условиями применимости | Половина раздела 3 готова |
| Умолчание и практическое правило | Половина раздела 4 готова |
| Названный главный вопрос перед выбором | Половина раздела 1 готова |
Если всё три — документ, скорее всего, не нужен: дешевле достроить соседнее решение до той границы, где карточка кончается. Так закрылись три случая: выбор стиля взаимодействия (NET-08) остался карточкой, а необратимость публичного контракта ушла в соседнее решение; стратегии выката (OPS-02) остались карточкой, и предмет D-09 сузился до существования отката; состав телеметрии (OPS-07, OPS-08) не устоял как документ вовсе, и его решающая часть вошла в D-10.
Третий случай — самый показательный: правило отменило документ, уже стоявший в очереди и попавший туда по единственной измеренной экономике из всего реестра. Значит вопрос стоит задавать до того, как документ начат, а не после.
Чего карточка не даёт никогда: дисквалификаторов, области применения и формы записи. Если решение держится на них — документ нужен, сколько бы сравнений ни было в карточке.
Подвопрос, помогающий ответить на третий: что здесь выбирается — механизм или то, чего нельзя переиграть? Наблюдение по четырнадцати решениям, из которых четыре отклонены. Отклонённые все до одного оказались меню механизмов: какой стиль взаимодействия, какие сигналы телеметрии, какая модель доступа, какой алгоритм лимитирования. Их варианты раскладываются таблицей «приём — свойства», а такую таблицу карточка несёт по жанру. Принятые выбирают другое:
| Что выбирают | Документы |
|---|---|
| Границу — что с чем разрезано | D-02, D-05, D-07 |
| Обещание — что мы обязуемся дать | D-06, D-10, D-11 |
| Необратимость — переход, который нельзя переиграть | D-08, D-09 |
| Либо держатся на дисквалификаторах, а у части — и на рыночном слое; ни того ни другого у карточки не бывает | D-01, D-03, D-04 |
Это вопрос, а не правило, и намеренно. Формулировка подогнана по четырнадцати наблюдениям задним числом и ни разу не проверена предсказанием. Предсказания по следующему кейсу записаны заранее — research/40-predictions.md. Пока они не сверены, подвопрос помогает думать и никого не отклоняет.
Правило применено к уже написанному, и два документа оказались пограничными. DATA-01 «Выбор хранилища» содержит и умолчание, и критерии, и сравнение классов — все три признака; CACHE-02 — два с половиной. Оба соответствующих документа удержались ровно на исключении: D-01 держится на шести дисквалификаторах и рыночном слое с датой съёмки, которого у карточки не бывает; D-03 — на пяти дисквалификаторах и на главной развилке, которой в карточке нет. Проверка заняла минуты и стоит того, чтобы её повторять: она же отвечает на вопрос, почему документ не пересказывает карточку.
Короткая форма — не полная минус разделы#
У обратимого решения другая задача. Не «выбрать правильно», а не ошибиться катастрофически, быстро узнать об ошибке и суметь откатиться. Вес смещается с сравнения на дисквалификаторы, умолчание и измерение.
| Полная форма | Короткая форма | |
|---|---|---|
| Разделов | 7 | 6 |
| Сравнение вариантов | Матрица: строки — оси, колонки — варианты | Умолчание и таблица отклонений: варианты не равноправны, один заведомо разумен |
| Раздел 4 | Рынок или типовые формы | Нет: если рынок есть, выбор продукта — отдельное полное решение |
| Что мерить / когда пересматривать | Карточки и раздел 7 порознь | Слиты в один раздел: показатель и есть условие возврата |
| Запись | ADR со снимком матрицы | Обычно пять строк — но длина записи от формы не зависит, см. ниже |
| Срок пересмотра | По событию из раздела 7 | Не назначается — пересматривает метрика, не календарь |
Разделы короткой формы: 1 что выяснить · 2 оси и дисквалификаторы · 3 умолчание и отклонения · 4 эвристики · 5 что мерить и когда вернуться · 6 запись.
Короткая форма и короткая запись — разные вещи. Форма определяется обратимостью решения, длина записи — тем, сколько нужно объяснить. Обратимое решение может оказаться несущим: если умолчание отвергнуто, причина отказа обязана быть в записи, и пяти строк не хватит. Разросшаяся запись не является признаком того, что форма выбрана неверно — проверять надо другое: не появился ли рыночный слой.
Таблица отклонений вместо матрицы — когда заполнять колонки под каждый вариант значит в большинстве случаев прийти к умолчанию. Условие отклонения должно быть подтверждённым, а не ожидаемым: иначе короткая форма превращается в способ обосновать любимую оптимизацию.
Стадия системы — поле шапки, а не оговорка в тексте#
Стадий три, и первые две определяются одним: откуда берутся факты.
| Стадия | Чем отличается |
|---|---|
| гринфилд | Системы ещё нет. Фактов о ней не существует, они предсказываются или назначаются (см. правило о гринфилде в «Правилах заполнения») |
| работающая | Система есть. Факты измеряются — историей, схемой, трафиком |
| под изменением | Работающая система плюс обязательство её не сломать: переезд, окно перехода, обратная совместимость, откат |
«Под изменением» — режим работающей, а не третья стадия рядом с двумя. На гринфилде её не бывает: переходить не от чего. Отсюда правило наследования: документ, применимый к работающей системе, применим и под изменением, если он не сказал иного. Оно дешевле трёх независимых списков и проверяется машиной. Отдельно «под изменением» пишут только там, где документ вне этого режима не нужен — так устроен D-08, у которого предмет и есть переход.
Зачем поле. До его появления одиннадцать шапок объявляли стадию четырьмя разными способами — заголовком, синонимами, вводным блокквотом, строкой «не путать с», — а четыре не объявляли никак. Список документов, нужных на шаге, собирается по шапкам до начала работы; пока стадия живёт в прозе, этот список зависит от внимательности читателя.
Стадия ограничивает документ редко. Из одиннадцати ограничены трое: D-02 — только работающая, D-05 — только гринфилд, D-08 — только под изменением. Остальные восемь применимы на обеих, и это не небрежность заполнения: четыре прогона исключали документы по отсутствию предмета, а не по стадии.
Чем это не является. Не заменой строки «не решает»: там граница предмета, здесь — границa стадии, и они расходятся. Не разрешением молчать о том, что на этой стадии документ читается иначе: поле говорит «применим», а не «применим без оговорок».
Вторая копия — в рабочем процессе. Каждый шаг 00-workflow.md перечисляет свои документы со стадиями строкой «Документы шага». Это одно и то же знание в двух отображениях, и расхождение между ними ловит tools/check.py. Правило набора запрещает вторую копию там, где её ничто не синхронизирует; под машинной сверкой запрет не действует.
Связанные решения записываются вместе#
Решения бывают связаны так, что порознь их запись теряет главное — сумму. Признак связанности один: у решений общий параметр, общий бюджет или общее окно, и изменение одного пересчитывает другое.
| Случай | Что общего |
|---|---|
| Два кэша на одном пути чтения | Бюджет памяти и один параметр — порог, заданный в третьем решении |
| Границы сервисов и границы данных | Класс защищаемых данных: линия, рассекающая его, дорога в обоих |
| Миграция данных и выкат кода | Окно и дата. Точка невозврата и откат общие только пока приёмник данных наш; при чужом приёмнике расходятся |
Форма записи. Связанные решения записываются одним ADR: общий контекст, отдельные короткие записи по каждому решению, общие последствия и общие условия пересмотра. Дробить их на самостоятельные ADR можно, но тогда сумма не видна нигде, и первый же пересмотр одного из них пройдёт без учёта остальных.
Чем это не является. Не слиянием документов решений: каждое решение по-прежнему принимается своим документом, со своими дисквалификаторами. Связка живёт в записи, а не в методе.
Артефакты, уезжающие наружу, считаются в одном месте. Отдельный случай той же потери суммы, и опаснее обычного. Артефакт, который система отдаёт вовне и не может отозвать — квитанция, уведомление, выгрузка, запись в чужом реестре, — рождается внутри решения, для которого он не главное: решали про совместимость, про связность процесса, про деградацию, а наружу каждый раз уехало по одному. Признак, что сумму никто не собрал, один: ни одно решение не знает общего числа.
На прогоне U-02 квитанций оказалось три рода на одну подачу — получено, принято, встречный вердикт, — каждая юридически значима, и каждая появилась в своём ADR (ADR-0001, ADR-0005, ADR-0006). Такого вопроса в наборе не было, и заметить их вместе удалось только на ревизии.
Перечень сводится в одном месте — в ADR того решения, которое отвечает за обещание вовне, — и входит в охват обещания: артефакт, не попавший в перечень, не защищён ничем, ровно как исключённое из охвата в D-11. Считать их порознь можно; тогда охват обещания заведомо уже, чем то, что система уже отдала.
Чем это не является. Не требованием завести документ решения об исходящих артефактах: наблюдение пока одно, и структура под него преждевременна. Свести перечень — дёшево, завести документ — нет.
Три типа решений: варианты берут, строят или перечисляют#
Откуда берутся варианты — самое сильное различие между решениями, сильнее, чем предметная область. Оно меняет три раздела из семи.
| Варианты берут | Варианты строят | Варианты перечисляет модель | |
|---|---|---|---|
| Примеры | Хранилище, брокер, способ аутентификации | Границы сервисов, модель данных, схема развёртывания | Связь сервисов в процессе, уровень изоляции, гарантия доставки |
| Откуда кандидаты | С рынка — раздел 4 их перечисляет | Из раздела 1: применением разных принципов к нашим фактам | Из модели: произведение числа значений координат. Чаще координаты двоичные, и тогда это 2^N; у D-11 одна ось трёхзначна — 2 × 2 × 3 = 12 |
| Множество | Открытое, стареет | Открытое, не стареет | Закрытое и полное, не стареет |
| Можно ли упустить вариант | Да — рынок меняется | Да — принцип не пришёл в голову | Нет. Можно только неверно определить координату |
| Раздел 1 | Только собирает факты | Собирает факты и порождает кандидатов | Вопросы и есть оси: по одному на координату, плюс проверочные |
| Раздел 4 | Рыночный слой с датой съёмки | Слой типовых форм, даты нет | Слит с разделом 3: перечень вариантов и есть система координат |
| Пометки источников | [док], [сторонний] |
Наши артефакты: история, схема, требования | Координаты требований, а не факты о вариантах |
| Нулевой вариант | «Оставить как есть» | «Не делать» — обязательная колонка | «Вне пространства»: процесс может не быть распределённым вовсе |
| Как отвергают вариант | Дисквалификатором | Дисквалификатором | Отвергая требование, которое в него привело |
Второй тип опаснее первого: кандидатов легко построить все «интересными» и не заметить, что ничего делать не надо. Третий — самый узкий и самый строгий: полнота множества гарантирована, но и уйти из неудобной ячейки нельзя иначе, чем изменив вход.
Семь разделов — это полная форма, остальные сливают пару#
Обе «неполные» формы состоят из шести разделов, но сливают разные пары. Это не экономия места: в каждом случае два раздела перестают быть разными вопросами.
| Форма | Что происходит с разделами | Почему |
|---|---|---|
| Полная (7) | — | Варианты сопоставимы, решение однократно |
| Короткая (6) | Раздел 4 отсутствует; 5 и 7 слиты в «что мерить и когда вернуться» | Показатель и есть условие возврата: разносить их — способ не заметить ни того, ни другого |
| Перечисляемая (6) | 3 и 4 слиты в «пространство решений и наша ячейка» | Перечень вариантов и система координат — одна и та же таблица |
Правила заполнения#
Факт, а не оценка. В матрице пишется измеримое утверждение или «нет данных». Балл «4 из 5» скрывает, откуда он взялся, и позволяет подогнать итог под уже выбранный вариант.
Источник факта помечается, и у достоверности три степени, а не две. Это самая частая ошибка первых версий документов: они делили факты на «измеренные» и «неизвестные», а между ними лежит целый класс.
| Степень | Что это | Что разрешает |
|---|---|---|
[замер] |
Измерено на нашем профиле, с датой | Принять решение и считать ячейку закрытой |
[док], [сторонний] |
Документация поставщика или независимое измерение | То же, если условия измерения сопоставимы с нашими |
[замер сторонний] |
Измерено и опубликовано владельцем чужой системы: релизный цикл поставщика, доступность удостоверяющего центра, расписание коллегии | Принять решение — и записать, что обновляет этот факт не наш замер, а чужая публикация |
[расчёт] |
Выведено арифметически из известных величин | Принять решение — и записать, какой замер его подтвердит |
[нет данных] |
Не знаем | См. правило ниже |
Сторонний замер — не то же, что [сторонний]. [док] и [сторонний] описывают кандидата, которого мы выбираем, и потому проверяются вопросом «сопоставимы ли условия измерения с нашими»: при желании мы измерили бы то же сами. [замер сторонний] описывает чужую систему, которую мы не выбираем и не можем измерить никогда: точка измерения не у нас, и меняется факт тогда, когда решит его владелец. Поэтому у него другое условие годности — не сопоставимость, а дата публикации и кто её объявил, — и другой способ обновления: не наш замер, а наблюдение за чужой публикацией.
Принимает ли сторонний замер конкретный дисквалификатор — решает он сам и говорит об этом словами. Молчание читается как «не принимает»: это сохраняет прежнее поведение документов, написанных до появления пометки.
Различие между расчётом и догадкой принципиальное: «8 000 запросов в секунду против одного узла» выведено из объявленных чисел и проверяемо на бумаге; «кажется, упрёмся в базу» — нет. У системы, которой ещё не существует, пометки [замер] не бывает вовсе, и без степени [расчёт] такой документ нельзя заполнить честно. Но [замер сторонний] на гринфилде бывает: чужая система существует и тогда, когда нашей ещё нет. Это единственный твёрдый факт, доступный до первого запуска.
Словарь свой у каждого решения и объявляется в разделе 3. Там, где вендорской документации нет вовсе, [док] не встречается, а факты приходят из наших артефактов: [история N мес] — из репозитория или трекера за период, [схема] — из схемы данных и кода, [требования] — из инвариантов W0, [орг] — из состава команд и принятой терминологии. Универсально только правило: ячейка без пометки непроверена.
[нет данных] блокирует решение только в различающей оси. Пустая ячейка в оси, по которой все оставшиеся кандидаты одинаковы, безвредна: она не влияет на выбор и не стоит того, чтобы ради неё откладывать. Блокирует та пустота, что стоит там, где варианты расходятся. Записать, каким замером она закрывается, надо в обоих случаях.
«Нет данных» значит разное в зависимости от обратимости. В необратимом решении пустая ячейка — это «не решать, пока не измерим». В обратимом — наоборот: включить умолчание на части трафика и померить дешевле, чем анализ, который ту же цифру только оценит. Обратимость меняет смысл нехватки данных на противоположный.
В перечисляемом типе «нет данных» в координатном вопросе вообще не бывает: если непонятно, нужна ли атомарность, это не нехватка данных, а неопределённое требование, и возвращаться надо к W0, а не мерить.
На гринфилде вопрос об уже существующем становится решением. Вопросы вида «сколько копий уже есть», «что мы знаем о своих потребителях», «какая декомпозиция сложилась» написаны как опрос: предполагается, что ответ где-то лежит и его надо найти. Систему, которой ещё нет, не опрашивают — у неё такие ответы назначаются. «Сколько их уже есть» читается как «сколько мы заведём», и цена ошибки переезжает во времени: на работающей системе неверный ответ обнаруживается замером позже, на гринфилде он создаётся сейчас и станет фактом ровно потому, что так записали.
Отсюда три следствия. Ответ помечается как решение, а не как замер: [прогноз], [требования], [орг] — но никогда [замер]. Пустая ячейка означает «ещё не решили», а не «не нашли», и закрывается она выбором, а не измерением. И сам выбор попадает в ADR наравне с остальными: переиграть его потом будет стоить как перенос данных, а не как правка документа.
Это свойство набора, а не отдельного документа. На прогоне U-02 так прочитались подряд два: D-07 велит письменно ответить, сколько копий данных уже существует, D-11 объясняет, чего стоит узнать своих потребителей. На гринфилде копий нет — значит решается, сколько их завести; знание о потребителях не покупается — оно закладывается бесплатно. Третий такой документ найдётся, и оговорка в каждом дороже одного правила здесь.
Правило, неприменимое на стадии, помечается — молчать оно не должно. Вопрос или дисквалификатор, который на какой-то стадии не срабатывает, срабатывает всегда или читается наоборот, несёт местную пометку [стадия: <какой>] и объяснение, что происходит вместо. Пометка ставится на само правило, а не в преамбулу документа: преамбулу читают один раз, а правила перечитывают на каждом применении.
Без пометки такой случай не обнаруживается. Молчащее правило выглядит как пройденная проверка: ячейка «не сработал» в записи ничем не отличается от честного «проверено, не подходит». На прогоне U-02 это удалось заметить только потому, что параллельно писались замечания к методу, — то есть случайно.
| Что происходит с правилом | Что пишется в пометке |
|---|---|
| Не срабатывает — входа для него на этой стадии не существует | Чем правило заменяется и что проверяется вместо него |
| Срабатывает всегда — перестаёт различать варианты | Что оно перестаёт отсекать и во что превращается: обычно в работу до, а не в отказ |
| Читается наоборот — вопрос тот же, смысл ответа другой | Как читать; чаще всего это правило о гринфилде выше — ответ становится решением, а не замером |
Пометка не отменяет правило и не разрешает его пропустить. Она говорит, что на этой стадии оно даёт другой результат, и называет какой. Правило, от которого на стадии не остаётся ничего, — не помечается, а выносится в отдельный документ: так из D-02 вышел D-05.
Словарь стадий общий с полем шапки: гринфилд, работающая, под изменением. Третья в пометках почти не встречается — по правилу наследования она ведёт себя как работающая.
Дисквалификаторы первыми, организационные — впереди технических. На прогоне E-01 из десяти дисквалификаторов сработали только организационные — про команду, провайдера и зрелость эксплуатации, — а технические не сработали ни разу. Это не особенность кейса: технические ограничения задевают края возможного, а организационные действуют всегда. Проверять их первыми дешевле.
Жёсткие ограничения отсекают варианты без всякого сравнения. Обычно после них остаётся два-три кандидата, и взвешивать почти нечего. В короткой форме они несут основную нагрузку: ошибиться можно дёшево, но именно дисквалификаторы перечисляют ошибки, которые дёшево обойтись не могут.
Документ об обещании обязан нести дисквалификатор проверяемости. Первое правило этого шаблона, зависящее не от формы решения, а от его предмета. Если предмет — обещание, то есть то, что система обязуется дать другому (пользователю, потребителю интерфейса, собственной команде), среди дисквалификаторов обязан стоять такой:
Обещание, исполнение которого нечем установить, обещанием не является.
Четыре документа пришли к нему независимо и разными словами: D-06 — путь деградации ни разу не исполнялся; D-09 — откат ни разу не пробовали; D-10 — измеритель не показывает число сегодня; D-11 — срок объявлен тем, кого мы не видим. Правило стоит здесь, чтобы пятый не открывал его заново — и чтобы автор, не нашедший у себя такого дисквалификатора, проверил, обещание ли у него в предмете.
Чем это не является. Не делением документов на семейства: у границ и необратимостей собственных правил пока нет, и вводить структуру под одно наблюдение рано.
Баллы не суммируются. Если хочется свести к числу — это признак, что не хватает дисквалификатора.
Матрица — снимок, а не ссылка. В ADR заполненная матрица копируется целиком, с датой. ADR фиксирует, что решили тогда и при каких условиях; ссылка на живой документ означает, что обоснование молча изменится вместе с ним. Ссылкой прикладывается только метод — сам документ решения и дата его рыночного снимка. В перечисляемом типе копировать нечего: перечень ячеек не зависит от рынка и не меняется, поэтому снимком копируются ответы на координатные вопросы — они и есть условия момента.
Дисквалификация может оставить один вариант — тогда матрица не заполняется. Вместо неё пишется строка «дисквалификаторы сделали всю работу» с перечнем сработавших и тем, что каждый отсёк. Пустой раздел без этой строки выглядит как небрежность, хотя означает обратное: сравнивать было не с чем.
В матрице есть нулевой вариант. «Оставить как есть» или «не делать» — полноценная колонка, а не отсутствие решения. Без неё сравнение идёт между способами что-то сделать, и вопрос, надо ли вообще, не задаётся.
Документ называет, чего он не решает. Соседнее решение, оставшееся открытым, — не пробел, а граница ответственности. Без этой строки соблазн закрыть чужую задачу своим решением оказывается сильнее: на прогоне E-01 пришлось писать прямо в ADR, что выбор хранилища не отвечает за восемь тысяч чтений в секунду.
Матрица объясняет себя. В ней присутствуют все оси решения, и у каждой — колонка «что записывать в ячейку». Документ открывают те, кто видит его впервые; матрица из одних названий осей заполняется наугад или не заполняется вовсе. Ось, по которой варианты не различаются, вычёркивается; недостающая ось добавляется вместе со своим вопросом в раздел 1. Исключение — координатные оси перечисляемого типа: убрав одну, получаем не более простое решение, а неопределённую ячейку.
Форма#
# D-NN · <название решения>
Версия: <X.Y> · <дата> · по мастер-шаблону v<X.Y>
Известно также как: <синонимы, как это называют в других командах и источниках>
Этап: <W-шаги, на которых принимается>
Стадия: <гринфилд · работающая · под изменением — на каких документ применим>
Профиль: <обратимость> · <влияние>
Карточки: <ссылки на topics/ за механикой>
Не решает: <что соседнее остаётся открытым и где решается>
Не путать с: <документы-соседи, которые легко взять по ошибке>
## 1. Что выяснить
До сравнения вариантов. У каждого вопроса помечено, какую ось он заполняет,
и — где это возможно — где искать ответ, а не у кого спросить.
5–7 вопросов. Если вопросов больше — решение слишком крупное, делится на два.
Если варианты строятся, а не берутся с рынка — второй подраздел:
вопросы, порождающие кандидатов.
## 2. Оси и дисквалификаторы
Оси — то, по чему варианты различаются содержательно.
Дисквалификаторы — условия, при которых вариант выбывает без сравнения.
## 3. Матрица оценки
Строки — все оси, колонки — варианты, включая нулевой. Отдельная колонка
«что записывать в ячейку». В ячейках факты с пометкой источника;
словарь пометок этого решения объявляется здесь же.
Заполняется в проекте; сюда попадает форма и условный пример — с оговоркой,
что числа в нём выдуманы, а проверенные факты живут в разделе 4.
## 4. Из чего выбирают
Три формы — по типу решения.
Варианты берут: «Типовые решения · снято <дата>» — продукты, лицензии,
жёсткие лимиты, ссылки на первоисточники. Дата обязательна.
Варианты строят: «Типовые формы <решения>» — способы решить, признак,
по которому режут или делят, условие применимости,
чем оборачивается ошибка. Даты нет: формы не устаревают.
Перечисляет модель: раздел слит с третьим. Полный перечень сочетаний,
коды координат, чем живётся в каждой ячейке, плюс
таблица «чтобы уйти из ячейки, отпустить придётся вот это».
Колонка «статус у нас» в обеих: используем / не используем, почему /
не рассматривали. Второе — с датой и условием пересмотра.
## 5. Эвристики
Что делать при ничьей и при нехватке данных.
## 6. Запись в ADR
Сопоставление разделов документа с полями ADR — форма самого ADR лежит
в 01-adr-template.md. Матрица копируется снимком; ссылкой — только метод
с версией и, если он есть, дата рыночного снимка. Правка этого документа
не меняет принятых ADR: изменившее бы решение изменение — это новый ADR,
отменяющий старый.
## 7. Условия пересмотра
Что должно измениться, чтобы решение перестало быть верным.
## История версий
Таблица «версия · дата · изменение». Для MAJOR в записи сказано,
что перепроверить в ADR, написанных по старой версии.
Проверка перед тем, как считать решение принятым#
- Факты собраны, а не предположены — у каждой ячейки матрицы есть пометка источника
- Дисквалификаторы проверены до сравнения, а не после
- Рассмотрен вариант отложить решение, и записано, какие данные его снимут — в короткой форме «отложить» означает «включить умолчание и померить»
- Записано, что изменит решение
- У отвергнутых вариантов записана причина — иначе их предложат заново
Пять пунктов одинаковы для всех решений и живут здесь, а не в каждом документе.
Новый документ читает кто-то, кроме автора#
Правило. Прежде чем документ решения считается написанным, его читает тот, кто не видел, как он писался.
Откуда. D-11 прошёл такую проверку первым: семь находок, шесть проверяемых по источникам. Среди них — пересказ карточки в эвристике, потерянная оговорка о возрасте цифр, выброшенная половина распределения, координата в четырёх смыслах, три объявленные и незаполненные оси. Половина находок ловится правилом, которое документ сам провозглашает в шапке. Причина не в небрежности: автор не может проверить документ на пересказ карточки — он её только что читал.
Список рецензента. Проверять не всё подряд, а то, что автор пропускает по устройству работы.
| Что проверить | Почему именно это |
|---|---|
| Нет ли абзаца, пересказывающего карточку своими словами | Автор читал её час назад и повтора не видит |
| Совпадает ли каждое число с источником и не сильнее ли утверждение, чем источник | «Нередко» превращается в «вовсе», «четыре из пяти» — в «всё» |
| Едет ли с цифрой её возраст и популяция | Оговорки теряются при переносе из исследования в документ |
| Не выброшена ли половина распределения | Медиана без квартилей — самая незаметная подгонка |
| Одно ли значение у термина во всех разделах | Координата, определённая в третьем разделе и применённая иначе в шестом |
| Все ли объявленные оси заполнены | Объявить и не использовать — обычный остаток черновика |
| Нет ли частотных утверждений там, где частота не измерена | «Самая частая ошибка» без замера |
Чем это не является. Не заменой пяти пунктов выше: те проверяют решение, этот — документ. И не заменой самопроверки: список рецензенту нужен для повторяемости, а не вместо него.
Как это связано с остальным документом#
Шаг workflow перечисляет решения, которые на нём принимаются, и ссылается сюда. Карточки в topics/ объясняют механику и ссылаются на решение за выбором. Обратная ссылка обязательна: решение без входящей ссылки из шага недостижимо в работе.
Строка «не решает» читается до планирования работы, а не после. Каждый документ называет в шапке, чего он не решает и где это решается. Планируя разбор — прогон, ревизию, применение к задаче, — по этим строкам собирают список нужных документов прежде, чем начать. На узком прогоне U-01 этого не сделали: прогон планировался по двум документам, а понадобилось три, потому что строка «не решает, надо ли делить данные и по какой линии» стояла в шапке D-08 и не была прочитана. Ошибка была не в документах — граница между ними была записана.
Внутри decisions/ четыре роли:
| Файл | Роль |
|---|---|
00-template.md |
Этот файл: как устроен документ решения |
01-adr-template.md |
Форма записи принятого решения |
02-versioning.md |
Версии, статусы, что перепроверять в старых ADR |
D-NN-*.md |
Сами решения |
Источники метода: Atul Gawande — The Checklist Manifesto (форма проверки и ограничение объёма) · Michael Nygard — Documenting Architecture Decisions (запись решения) · 00-workflow.md, шаг W10 (оси сравнения и обратимость)
История версий#
| Версия | Дата | Изменение |
|---|---|---|
| 6.5 | 2026-09-22 | MINOR, по итогам прогона U-02, правка Р9.3·A плана ревизии. Введена местная пометка [стадия: …]: правило, которое на стадии не срабатывает, срабатывает всегда или читается наоборот, помечается на месте и объясняет, что происходит вместо. Названы три формы и сказано, что пометка не отменяет правило; правило, от которого на стадии не остаётся ничего, помечать нельзя — оно выносится в отдельный документ, как D-05 из D-02. Старым ADR перепроверять нечего: пометка делает видимым то, что и так было верно, и ни один исход от неё не меняется. Поставлена в трёх документах — D-01, D-06, D-09 |
| 6.4 | 2026-09-22 | MINOR, по итогам прогона U-02, правка Р9.1·C плана ревизии. В шапку добавлено поле «Стадия» и назван словарь из трёх значений. Записано правило наследования: «под изменением» — режим работающей системы, а не третья стадия, и документ, применимый к работающей, применим и под изменением, если не сказал иного. Это отменяет самообъявление D-08 и D-09 «документами третьей стадии» как описание места в наборе — предметом D-08 переход остаётся. Стадия дублируется строкой «Документы шага» в рабочем процессе, и расхождение ловит машина. Старым ADR перепроверять нечего: поле описывает область применения, которая у документов не менялась — она была рассыпана по прозе и теперь собрана в одну строку |
| 6.3 | 2026-09-22 | MINOR, по итогам прогона U-02, правки Р3, Р4 (словарная часть) и Р10 плана ревизии. Гринфилд превращает опрос в решение: вопрос «сколько их уже есть» читается как «сколько мы заведём», пустая ячейка значит «ещё не решили», и ответ помечается как решение, но никогда [замер]. Добавлена пометка [замер сторонний] — измерено и опубликовано владельцем чужой системы; годность проверяется датой публикации, а не сопоставимостью условий, и обновляет её чужая публикация. Принимает ли её дисквалификатор — решает он сам; молчание читается как «не принимает», поэтому прежнее поведение документов сохраняется и правка остаётся MINOR. Артефакты, уезжающие наружу, считаются в одном месте и входят в охват обещания. Старым ADR: перепроверять нечего — первые две правки меняют заполнение документов на гринфилде, где старых ADR нет, третья требует сводить перечень, а не пересматривать выбор |
| 6.2 | 2026-09-21 | MINOR, по итогам вычитки Ш1. Исправлена строка пары «миграция и выкат» в таблице связанных решений: общими названы окно и дата, а точка невозврата и откат — только пока приёмник данных наш. Прежняя безусловная формулировка опровергнута прогоном U-01 и разделом 2 D-08 v2.0, написанными в один день с ней. Признак связанности не изменился, пара по-прежнему записывается одним ADR: старым ADR перепроверять нечего |
| 6.1 | 2026-09-18 | MINOR, по итогам узкого прогона U-01. Записано правило: строка «не решает» читается до планирования работы, и по ней собирается список нужных документов. Граница между D-07 и D-08 была записана в шапке и не прочитана при планировании; прогон, задуманный по двум документам, потребовал трёх |
| 6.0 | 2026-09-18 | MAJOR, по итогам мини-исследований М1–М3 и написания D-11. Первое правило, зависящее от предмета, а не от формы: документ об обещании обязан нести дисквалификатор проверяемости — четыре документа пришли к нему порознь. Добавлен подвопрос о жанре к третьему вопросу: механизм или то, чего нельзя переиграть; внесён вопросом, а не правилом, до предсказательной проверки. Формула третьего типа обобщена: произведение числа значений координат, а не только 2^N. Введён шаг «новый документ читает кто-то, кроме автора» со списком рецензента. Старым документам: перепроверять нечего — все четыре документа-обещания требуемый дисквалификатор уже несут, остальные правки касаются того, заводить ли документ и как его проверять, а не того, как в нём принимается решение; обновляется только строка совместимости |
| 5.0 | 2026-09-17 | MAJOR, по итогам исследования поля. В «когда заводить документ» добавлен третий вопрос — не делает ли существующая карточка большую часть работы: два случая из тридцати закрылись именно так, и оба раза документ был бы пересказом. Добавлен раздел о связанных решениях: у них общий параметр, бюджет или окно, и записываются они одним ADR — три независимых случая. Старым документам: проверить, не пересказывает ли решение существующую карточку, и не записаны ли порознь решения с общим параметром |
| 4.0 | 2026-09-16 | MAJOR, по итогам прогона E-01. Три степени достоверности факта вместо двух — появился [расчёт]. [нет данных] блокирует только в различающей оси. Организационные дисквалификаторы проверяются раньше технических. Дисквалификация может оставить один вариант, и тогда матрица не заполняется. Короткая форма и короткая запись разделены. В шапку добавлены «Не решает» и «Не путать с». Исправлено неверное утверждение о нулевом варианте в перечисляемом типе. Старым ADR: перепроверять нечего — ни одно правило не меняет исход, все они делают заполнение честнее; ADR прогона намеренно оставлены по прежним версиям |
| 3.0 | 2026-09-16 | MAJOR: добавлен третий тип решений — варианты перечисляет модель (закрытое полное множество). У него сливаются разделы 3 и 4, координатные оси не вычёркиваются, вариант отвергается отклонением требования, а снимком в ADR идут ответы на координатные вопросы. Сформулировано общее правило: семь разделов — это полная форма, обе остальные сливают пару. Старым ADR: ничего; у D-01 и D-02 тип не изменился, D-04 — первый перечисляемый |
| 2.0 | 2026-09-16 | MAJOR: короткая форма описана как собственная форма из шести разделов, а не «полная минус 3, 4, 6, 7». Матрицу в ней заменяет умолчание с таблицей отклонений, «что мерить» и «условия пересмотра» слиты, запись — пять строк вместо ADR. Правило «нет данных» стало зависеть от обратимости. Перепроверять нечего: короткая форма впервые применена в D-03, документов по прежнему описанию не существует |
| 1.0 | 2026-09-16 | Введено версионирование. Содержание на этот момент: отбор по осям «цена изменения × влияние», два типа решений (варианты берут или строят), шесть правил заполнения, семь разделов формы, пять пунктов проверки |