Подниму тему, которую на Инфостарте, кажется, еще не обсуждали. В большом мире разработки про ADR пишут уже лет десять, а у нас в 1С-сообществе про него почти не слышно. И зря.
Сейчас объясню, почему.
Знакомая история?
Приходит к вам коллега (или вы сами через год) и спрашивает: «А почему вот этот обмен у нас сделан через HTTP-сервис, а не через типовую синхронизацию? И почему данные складываем в регистр сведений, а не в справочник?»
Вы смотрите на код. Код рабочий, понятный, имена говорящие (комментариев, разумеется, нет - мы же не варвары). Но почему было принято именно такое решение - не помнит никто. Автор уволился, задача в трекере закрыта и неинформативна, переписка в чате утонула, а тот, кто все помнил, ушел на пенсию. Остался только результат. Причины испарились.
И тут начинается самое интересное. Новый разработчик смотрит на «странное» решение, не понимает его мотивов, и одно из двух:
- либо аккуратно обходит его стороной, делая костыли вокруг («ну раз так сделано, значит, наверное, зачем-то надо»);
- либо смело переделывает «как правильно» - и через неделю выясняется, что наступил ровно на те грабли, от которых исходное решение как раз и защищало.
Знание о том, почему мы сделали именно так, - самое хрупкое знание в проекте. Код живет в репозитории, данные живут в базе. А причины решений живут только в головах. Головы, как известно, увольняются и забывают.
ADR - это лекарство ровно от этой болезни.
Что такое ADR
ADR расшифровывается как Architecture Decision Record - запись об архитектурном решении.
Суть простая: каждое значимое архитектурное решение мы фиксируем в виде короткого документа. Никаких толстых томов проектной документации, которые никто не читает и которые устаревают в день подписания. Маленькая заметка на полстранички - вот и весь формат.
Одно решение - один документ. Документы складываем рядом с кодом, нумеруем по порядку и больше не трогаем (об этом ниже, это важный момент).
Сам код отвечает на вопрос «как это работает». ADR отвечает на другой вопрос - «почему мы решили сделать именно так».
Почувствуйте разницу:
- Документация описывает, как устроена система сейчас.
- ADR описывает, почему она устроена именно так, и какие альтернативы мы отвергли.
Кто это придумал
Чтобы сразу снять вопрос «а кто это вообще придумал и можно ли этому доверять».
ADR - давно устоявшаяся индустриальная практика. С конкретными авторами, со стандартными форматами. Появилась она не вчера.
- Майкл Нюгард (Michael Nygard), 2011 - статья «Documenting Architecture Decisions». Это канонический первоисточник, именно здесь сформулирован тот самый формат, который мы разбираем ниже. Хотите прочитать что-то одно про ADR в оригинале - читайте эту статью.
- ThoughtWorks Technology Radar - авторитетный отраслевой «радар технологий» от большой международной IT-компании. Именно он в свое время вывел ADR в мейнстрим, присвоив практике статус «Adopt» (рекомендовано к повсеместному применению). После этого про ADR заговорили все.
- MADR (Markdown Architectural Decision Records) и репозиторий Joel Parker Henderson - это уже про готовые шаблоны. MADR — популярный формат записи ADR в markdown. Огромная коллекция шаблонов, примеров и ссылок собрана в репозитории Joel Parker Henderson, а «домашняя страница» практики со стандартными шаблонами живет на adr.github.io.
Велосипед изобретать не нужно. Есть первоисточник, есть готовые шаблоны на любой вкус - от минималистичного нюгардовского до развернутого MADR. Берете и применяете.
Как выглядит ADR
Классический ADR состоит из нескольких обязательных секций. Их немного, и придумывать ничего не надо.
Заголовок. Номер и краткая суть. Например: "ADR-0012: Адресное хранение на штатном ячеистом складе ERP, без отдельной WMS".
Статус. Одно из: "Предложено", "Принято", "Отклонено", "Устарело", "Заменено на ADR-NNNN". Статус - это вся «жизнь» решения. Решение приняли - статус «Принято». Через два года отказались - документ не удаляем, ставим «Устарело» и пишем новый ADR со ссылкой на старый.
Контекст. Что происходит, какая задача стоит, какие ограничения. Тут описываем ситуацию максимально полно: какая версия платформы, какие требования бизнеса, что у нас уже есть, чего нельзя трогать.
Решение. Что именно мы решили сделать. Коротко и однозначно.
Последствия. Что мы получаем и чем за это платим. Тут самая ценная часть - перечислить минусы. Любое архитектурное решение - это компромисс. Идеальных решений не бывает, бывают подходящие под контекст.
Иногда добавляют еще секцию Рассмотренные альтернативы - что еще мы обдумывали и почему отказались. Лично я считаю эту секцию чуть ли не самой полезной: именно она спасает будущего разработчика от соблазна «а давайте переделаем как правильно».
Пример из жизни
Возьму конкретный пример. Ситуация знакома всем, кто внедрял складской учет: на складе бардак, и встает вопрос - отдельная WMS-система или штатные возможности ERP?
# ADR-0012: Адресное хранение на штатном ячеистом складе ERP, без отдельной WMS
## Статус
Принято (2026-02-10)
## Контекст
На складе бардак: товар ищут вручную, новички не знают, где что лежит.
Бизнесу нужно прежде всего знать, в какой ячейке находится конкретный товар. Сложные складские процессы на текущем объеме не требуются.
Уже внедрена 1С:ERP 2.5.22.137, склад работает в той же базе.
## Решение
Включаем и настраиваем типовой механизм адресного (ячеистого) хранения в 1С:ERP. Отдельную WMS-систему не внедряем.
## Последствия
+ Не плодим еще одну систему и интеграцию с ней - меньше точек отказа и ниже стоимость владения.
+ Адресный склад работает «из коробки», данные о ячейках - в той же базе, отдельный обмен не нужен.
+ Решаем главную задачу бизнеса: всегда видно, где лежит товар.
- Функционально беднее полноценной WMS (тонкое управление складскими процессами, сложные алгоритмы отбора).
- Нужно дорабатывать рабочие места кладовщиков, штатные не всем удобны.
## Рассмотренные альтернативы
- Отдельная WMS (например, класса Axelot) - отклонено: избыточно для текущих задач.
Управлять складскими процессами бизнесу пока не нужно, а интеграция и сопровождение второй системы стоят дорого.
Полстранички. Пять минут на написание. А теперь представьте, что через год новый разработчик (или новый РП, который рвется «внедрить уже нормальную WMS») открывает этот файл - и ему не нужно никого допрашивать. Он сразу видит, что вопрос WMS уже обдумывали, на каких объемах решение принималось и при каких условиях его стоит пересмотреть.
Архитектор - это тот, кто принимает решения
Отвлечемся от файлов и шаблонов. Кто вообще все это пишет?
Если спросить, чем занимается архитектор, ответы будут разные: «рисует схемы», «знает платформу вглубь», «согласовывает доработки», «гоняет на ревью». Все так. Но если выпарить лишнее, останется одно: архитектор - это человек, который принимает архитектурные решения. Это и есть суть профессии. Код он тоже пишет, схемы тоже рисует, но главное в его работе - на развилках выбрать дорогу и отвечать за выбор.
А теперь смотрите, что получается. Если работа архитектора - это принятие решений, то ADR - буквально материальный результат его труда. Зафиксированное решение. Та самая «деталь», которую архитектор произвел на свет.
Подумайте: у разработчика результат работы виден и осязаем - это коммиты и работающий функционал, который можно потыкать. А что предъявить архитектору? «Я тут подумал и решил, что обмен надо делать вот так»? Решение, которое нигде не записано, - это решение, которого как будто и не было. Его нельзя ни перечитать, ни оспорить, ни передать, ни вспомнить через год.
ADR превращает невидимую работу архитектора в видимый артефакт. Это визуализация решения - то, что можно положить в репозиторий, показать команде, обсудить на ревью, передать преемнику. Без ADR архитектура живет в голове одного человека и умирает вместе с его увольнением. С ADR она становится активом проекта.
Так что для архитектора ADR — естественная форма того, что он и так делает каждый день. Никакая не обязанность сверху. Просто перестаем выбрасывать результат в воздух и начинаем его сохранять.
Почему это особенно актуально для 1С
Знаете, что я заметил? В мире 1С особенно много решений, которые принимаются «по умолчанию» и потом удивляют новичков.
- Дорабатывать типовую или делать расширение?
- Одно большое расширение или много маленьких? (это решение потом аукнется отдельными приключениями)
- Отказаться от хранилища в пользу git, работать в конфигураторе или EDT?
- Свой регистр или подсистема из БСП?
Каждый из этих вопросов - это развилка. На развилке мы выбираем дорогу, и у выбора есть причины. Но причины эти мы обычно проговариваем вслух на созвоне, киваем друг другу - и забываем. А расхлебывает потом тот, кто пришел в проект позже.
У нас вообще не принято фиксировать «почему». Выгружать конфигурацию в git умеем, CI настраиваем, автотесты гоняем, рассказываем на инфостарте, какие мы крутые. А сам процесс принятия решений остается устным фольклором, который передается от старожила к новичку у виртуального костра. ADR превращает этот фольклор в письменность.
Где хранить ADR
Тут моя позиция простая: храните ADR рядом с кодом, в git.
Раз уж мы выгружаем конфигурацию в репозиторий (а вы ведь выгружаете, правда?), то заведите там папку docs/adr/ и складывайте туда обычные markdown-файлы:
docs/adr/
0001 Выбор механизма обмена.md
0002 Отказ от хранилища.md
0003 Структура расширений.md
...
Почему именно так, а не в Confluence, не в вики, не в Notion и не в «общей папке на сервере»:
- ADR лежит там же, где код, и попадает к разработчику вместе с командой git clone. Никуда ходить не надо.
- ADR версионируется вместе с кодом. По истории git видно, когда и в каком контексте появилось решение.
- Markdown читается откуда угодно - хоть в браузере на GitHub/GitLab, хоть в VS Code, хоть просто в блокноте.
- Не требует покупки и внедрения еще одной системы.
Если хочется автоматизации — есть утилиты adr-tools (создание новой записи одной командой) и Log4brains (собирает из ваших markdown-файлов статический сайт со всеми решениями). Но это уже опционально. Начать можно вообще без инструментов, с одного текстового файла.
А есть ли что-то родное, прямо внутри 1С? Да. Если хотите вести ADR, не выходя из экосистемы 1С, посмотрите подсистему АрхиТопос - православный инструмент для архитектора прямо в конфигурации 1С. Среди прочего там есть справочник «Реестр архитектурных решений», по сути та же концепция ADR: он позволяет фиксировать и документировать архитектурные решения по информационной системе или проекту. Подход тут другой, решения хранятся внутри базы, а не в git-репозитории. У этого есть и плюсы (все под рукой у архитектора в привычном интерфейсе, доступно аналитикам без git), и минусы (ADR живет отдельно от исходников и не едет вместе с git clone).
Что вам ближе, git-way или 1С-way, решайте сами. Главное - чтобы решения вообще фиксировались, а уж чем именно, дело десятое.
«Это же лишняя бюрократия!»
Собрал возражения.
«У нас нет времени на писанину». На написание ADR уходит 5-10 минут. Решение вы все равно уже обдумали и обсудили - остается записать то, что и так звучало вслух. Сравните это с часами, которые потом уходят на археологические раскопки «а почему тут так?».
«И так все знают, зачем документировать очевидное». Все знают - сегодня. Через год половина команды сменится, а оставшаяся половина забудет. «Очевидное» - это самое опасное слово в разработке. То, что очевидно автору в момент написания, абсолютно неочевидно тому, кто читает код через два года в шесть вечера в пятницу.
«У нас же есть задачи в трекере». Задача в трекере описывает, что надо сделать. Она не описывает, почему выбран именно такой способ, и почти никогда не содержит отвергнутых альтернатив. Трекеры к тому же меняются (вспомните, сколько раз вы мигрировали с одной системы на другую - и где теперь те старые задачи?). А ADR живет вместе с кодом ровно столько, сколько живет код.
«Это для больших команд, а я один». Вот тут самое интересное. «Команда из одного человека» - это команда из вас сегодняшнего и вас через год. И поверьте, "вы через год" - совсем другой человек, который смотрит на ваш сегодняшний код с искренним недоумением. ADR - это письмо самому себе в будущее.
Чего ADR не заменяет
Чтобы не впасть в другую крайность, ADR - не серебряная пуля. И не замена всей остальной документации.
ADR не отменяет:
- проектную документацию и ТЗ
- описание API и справку по функциям
- пользовательские инструкции
- схемы интеграций и регламенты эксплуатации
ADR фиксирует только архитектурные решения - те, что трудно и дорого изменить потом. Заводить ADR на каждый чих не надо. Переименовали реквизит -не ADR. Выбрали стратегию обмена между базами - вот это ADR. Чутье на значимость решения придет быстро.
С чего начать прямо сегодня
Не надо ждать понедельника и одобрения начальства. Сделайте так:
1. Заведите в репозитории папку docs/adr/.
2. Скопируйте шаблон из этой статьи в файл "0001-template.md" (или возьмите готовый, форматов в интернете полно).
3. Вспомните последнее серьезное архитектурное решение в вашем проекте и опишите его задним числом. Прямо сейчас, по горячим следам.
4. Договоритесь с собой (и командой, если она есть) - следующее значимое решение фиксируем сразу.
Все. Никакого внедрения, никакого нового софта. Один markdown-файл — и вы уже на шаг впереди подавляющего большинства 1С-проектов.
Заключение
Мы, 1С-ники, научились многому: выгружать в git, делать ревью, строить CI/CD. И при этом продолжаем терять самое ценное - причины наших решений.
Код храним бережно, а мотивы выбрасываем.
ADR - дешевый (буквально полстранички и пять минут) способ перестать это делать. Он не требует ни денег, ни разрешения. Только привычки.
Попробуйте завести хотя бы один ADR на ваш текущий проект. А через год напишите, пригодилось или нет. Интересно, приживется ли эта практика в нашем 1С-мире.
А пока расскажите в комментариях: вы фиксируете причины своих архитектурных решений? Или тоже полагаетесь на устный фольклор и память старожилов?