Привет! Это снова я, Паша Лукьянов. Я по-прежнему deputy CTO в AGIMA и по-прежнему рассказываю о принципах работы архкомитета у нас в компании. В первой части статьи я объяснил, из каких критериев состоят наши Definition of Ready (DoR) и Definition of Done (DoD), а также что представляет собой наша статусная модель. А теперь поговорим об этапах проработки архитектурных документов. Если вы внедряете архитектурный комитет в своей компании и прописываете процессы — вам сюда.
Под архитектурным документом мы обычно понимаем всю проектную документацию по архитектуре системы. Сюда входят обзоры, диаграммы, описания решений, оценки рисков, соответствие требованиям, а также приложения: чек-листы, результаты анализов и исследований, ссылки на ADR и т. п. Процесс рассмотрения и принятия такого документа мы у себя разделили на этапы с четко определенными ролями и критериями.
Роли участников процесса
Основные участники:
Автор архитектуры (ответственный архитектор проекта) — тот, кто разработал архитектурный документ. Это может быть solution architect, ведущий разработчик или тимлид проекта. Его задача — подготовить документ к ревью, представить его на комитете, отвечать на вопросы, внести правки по замечаниям.
Архитектурный комитет — коллегиальный орган. Здесь главный архитектор (обычно технический директор, он же председатель комитета), архитекторы, руководители департаментов, представители смежных областей: DevOps, специалист по ИБ, аналитики, лиды обратившейся команды, представитель бизнеса или менеджер продукта (если решение затрагивает бизнес-требования).
Координатор/секретарь комитета. Часто его функцию выполняет кто-то из архитекторов. В нашей команде это я. Он следит за процедурой: принимает заявки на ревью, планирует повестку встреч, заранее рассылает материалы, ведет протокол заседания. Его задача — обеспечить соблюдение регламентов. Также он публикует протокол и обновляет статус задачи в таск-трекере.
Этапы проработки архитектурной документации
Этап 1. Предварительная подготовка и подача заявки
Автор проекта готовит архитектурный документ по шаблону, а затем инициирует ревью. Он создает задачу типа «Рассмотрение архитектурного документа» на канбан-доске комитета и прикрепляет документ. Главное, чтобы чек-лист Definition of Ready был учтен и заполнен. Также автор пишет прямо в задаче краткую справку: цель проекта, какие ключевые решения приняты в архитектуре, какие вопросы он выносит на комитет.
Тут важно:
Малые проекты: могут иметь облегченный документ (но ключевые разделы всё равно должны присутствовать).
Средние/крупные проекты: полный документ, возможно, предварительно просмотренный внутренним архитектурным наставником.
Когда секретарь комитета получает уведомление о новой заявке, он его проверяет. Если чего-то не хватает, возвращает задачу на доработку автору до включения в повестку (то есть не переводит в статус Ready).
На этом этапе можно проводить предварительную проверку безопасности. Например, архитектор по безопасности просматривает раздел threat model и раздел по защите данных. Если сразу выявляются критические несоответствия политике безопасности, документ возвращается на доработку до вынесения на общее обсуждение. Это экономит время. Команда DevOps тоже может проверить раздел инфраструктуры на соответствие гайдлайнам заранее.
Когда заявка готова, секретарь назначает ее в повестку ближайшего собрания. Материалы (архдок, чек-листы, предварительные отзывы безопасности/DevOps) рассылают членам комитета за несколько дней до встречи. Мы закладываем три дня.
Этап 2. Индивидуальное ознакомление (pre-review)
Члены комитета самостоятельно изучают архитектурный документ заранее. Это обязательная практика, чтобы на самой встрече не тратить время на чтение. Каждый проверяет документ по своей части. По желанию, можно оставить комментарии прямо в документе.
Также комитет может использовать чек-лист для ревью — это стандартный перечень вопросов для каждого архитектурного документа. Вот пример такого чек-листа:
Соответствует ли архитектура нефункциональным требованиям?
Есть ли критичные единственные точки отказа?
Как обеспечена масштабируемость при росте нагрузки X10?
Учтены ли требования информационной безопасности?
Интегрируется ли система с существующим ландшафтом?
Не дублируется ли функциональность?
Оценена ли стоимость решения и соотнесена ли она с бизнес-ценностью?
Этот список у нас лежит в Wiki, и каждый может пробежаться по нему перед встречей.
Этап 3. Проведение заседания (архитектурное ревью)
В назначенное время комитет собирается — очно или онлайн. Для заседания стоит забронировать постоянный слот. У нас это пятница, 15:00. Вообще встречи проводятся по запросу. Если обсуждать нечего — встречаться, конечно, не обязательно.
В самом начале автор архитектуры выступает с краткой презентацией — обычно 10–15 минут. В своем выступлении он:
напоминает контекст проекта: цели, ключевые показатели, сроки внедрения;
показывает архитектурные представления: например, контекстную диаграмму или схему деплоя — и перечисляет технологии, выбранные для каждого компонента;
проговаривает ключевые решения и обосновывает их выбор;
указывает, какие есть открытые вопросы или сложности, по которым особенно важна экспертиза комитета;
озвучивает результаты анализа рисков.
После доклада члены комитета могут задать вопросы, если еще не получили ответы на подготовительных этапах. Председатель следит за регламентом и направляет дискуссию, чтобы она охватывала все важные аспекты. Если видит, что какой-то аспект упущен, поднимает этот вопрос. Также задача ведущего — держать тайминг.
Все замечания мы фиксируем в черновом протоколе. Выглядит это примерно так: «ИБ: требуется добавить двухфакторную аутентификацию для админов» или «Архитектор: подумать над упрощением интеграции с системой Billing, текущее решение сложно поддерживать».
Дальше всё предсказуемо:
Если на все вопросы есть ответы, а архитектура выглядит здравой и соответствует всем требованиям, комитет одобряет документ. Возможны мелкие замечания, но это не критично.
Если выявлены существенные проблемы, но они решаемы, комитет формулирует список доработок. В этом случае решение получает статус «Требует доработки».
Если подход концептуально неверен — такое редко, но бывает — комитет может отклонить предложенную архитектуру. Тогда проектной команде рекомендуют либо разработать новый вариант, либо эскалировать вопрос.
Комитет старается прийти к консенсусу. По идее можно использовать голосование, но чаще решение принимается на основе общей поддержки. Если никто из ключевых членов не возражает, председатель формулирует итог. В сложных случаях возможна формулировка условного одобрения: «Документ одобрим, если в течение двух недель будут исправлены пункты A, B, C, что проверят такие-то члены комитета».
После обсуждения председатель озвучивает итог. Звучать это может так: «Решение: архитектура условно одобрена. Необходимо до 20 апреля внести изменения, указанные в протоколе, после чего считать документ утвержденным без повторного созыва комитета. Ответственный — Иванов (архитектор проекта), проверяющие — Петров (ИБ) и Сидоров (DevOps)».
Все согласованные формулировки фиксируются секретарем.
Этап 4. Обратная связь и доработки
После встречи автор архитектуры получает протокол. Если документ одобрен сразу — на этом этапе автор может выдохнуть. Ему остается внести только косметические правки: орфография, уточнения. Больше изменений не требуется.
Если нужны доработки — начинается работа над исправлениями. Критично, чтобы все требования комитета были выполнены либо явно учтены. Если какое-то замечание по объективным причинам выполнить не удалось, автор должен объяснить это комитету. И затем комитет решит, приемлемо ли отклонение от рекомендаций.
В рамках обратной связи комитет может рекомендовать оформить ADR на какие-то ключевые изменения, выявленные при ревью. Мы фиксируем это примерно так: «Отказ от Traefik в пользу Envoy Proxy — оформить как ADR с обоснованием». После этого мы заводим задачу на создание ADR.
Этап 5. Принятие решения и фиксация
Когда документ полностью удовлетворяет комитет (после первого заседания или после правок), происходит уже формальное утверждение архитектурного документа. Это обычно означает:
Документ получает статус Approved. Если фиксируется версионность документов, то можно поставить соответствующую отметку на Confluence-странице — «Утверждено комитетом», дата, версия.
Ответственный архитектор ставит электронную подпись/отметку. Например, в Confluence можно добавить поле «Одобрено: ФИО, дата».
В задаче на доске ставим резолюцию Approved или просто комментарий: «Архитектура проекта X утверждена решением АрхКом №12 от 05.04.2025».
Если документ был условно утвержден ранее, сейчас фиксируется, что условия выполнены и решение окончательно положительное.
Если решение отрицательное (отклонено), протокол фиксирует отказ в утверждении и дальнейшие шаги. Комитет может также сообщить об этом спонсорам проекта, если это критично.
Статус всех ADR, связанных с документом, обновляется. ADR, лежащие в основе, остаются в Accepted. Новые ADR, созданные в ходе доработок, должны быть доведены до статуса Accepted. Если какие-то решения зафиксированы как отдельные ADR, их нужно приложить к документу или перечислить.
Этап 6. Документация и распространение
Завершающий этап — формализация результатов.
Протокол. Секретарь комитета готовит финальный протокол заседания. Он включает: дату и список участников, повестку, резюме по каждому пункту. Также для утвержденных — условия/замечания, для отклоненных — причины и рекомендации. Отдельно — перечень новых действий. Председатель утверждает протокол, а затем его и рассылают участникам.
Архитектурный документ. Когда он утвержден, его статус мы фиксируем в Wiki. Однако можно фиксировать и в Gitlab MR, если вы следуете подходу Documentation as code. Дальнейшие правки документа обычно либо запрещены без согласования, либо ведутся с контролем версий. Документ доступен для всех сотрудников (но без права редактирования).
Реестр архитектурных документов. В корпоративном реестре, если такой есть, обновляется запись: для проекта X добавлена ссылка на утвержденный документ версии Y.
Связанные проектные артефакты. Команда разработки теперь может использовать утвержденный документ как руководство. Все разработчики проекта должны ознакомиться с ним. Менеджер проекта может обновить план, зная, что архитектура утверждена. В Agimaban ментор ставит соответствующую галочку.
Контроль исполнения. Комитет может постановить, что некоторые пункты, указанные в документе, должны быть реализованы на определенных этапах. Тогда эти моменты идут в action items. Например: «До запуска в прод провести нагрузочное тестирование согласно архитектуре». Эти действия могут быть заведены задачами на проектной доске, но с пометкой «Контроль от архкома».
Теперь всё, что мы обсудили и постановили, задокументировано. Это облегчает жизнь новым сотрудникам и аудиторам: есть четкая история архитектуры проекта.
Этап 7. Последующий мониторинг и улучшение процесса
Даже уже приняв архитектуру, комитет не забывает о ней.
Если проект длительный, комитет может запросить отчет о состоянии архитектуры через некоторое время. У нас в Agimaban для этого есть отдельный чек-лист.
В случае значительных изменений или отклонений в ходе реализации, проектная команда должна снова уведомить комитет.
Сам процесс ревью комитет периодически анализирует на ретроспективе: всё ли прошло гладко, что можно улучшить. Такой анализ может происходить раз в квартал или по мере накопления опыта.
Гибкость процесса
Описанный процесс достаточно формален для средних и крупных проектов. Для проектов с незначительными рисками и маленькими команда его можно сильно упростить:
Состав комитета может быть меньше: только 2–3 архитектора без привлечения всех областей, если проект внутренний и некритичный.
Допускается совместить этапы: предварительная проверка может быть неформальной, сам документ короче, обсуждение короче.
Возможно утверждение заочно: комитет читает документ и дает комментарии в задаче на доске, а если замечаний критичных нет — документ одобряется без созыва заседания. Однако протокол всё равно лучше оформить.
Для высоконагруженных, стратегически важных проектов процесс может включать:
Дополнительные сессии архитектурных проверок по конкретным направлениям.
Более подробный архитектурный документ.
Участие Enterprise Architecture Board (то есть над-системного архитектурного совета) для утверждения принципов, если проект влияет на всю компанию.
Обязательное пилотирование/прототипирование определенных частей до полного утверждения.
Несмотря на такие вариации, база сохраняется:
поступил документ → проверили → обсудили → дали решение → оформили
Это выстраивает стандарт архитектурного ревью в организации и повышает предсказуемость: команды знают, чего ждать от комитета и как подготовиться, а руководство уверено, что архитектуры проходят качественный контроль.
Концепция ADR: применение, хранение и расширенный шаблон
ADR (Architecture Decision Record) — это короткий документ об одном конкретном архитектурном решении, который включает в себя в том числе и обоснование этого решения. Это легковесный способ фиксировать ключевые архитектурные решения без написания громоздкой документации.
В командах разработки ADR фиксирует полезные архитектурные артефакты, что особенно важно при работе на долгих и больших проектах. Компании же это позволяет фиксировать важные и стратегические IT-решения, общие для всех команд — например, GitFlow для всех разработчиков или изменение техрадара.
Применение ADR в процессе разработки и ревью
Команда создает ADR каждый раз, когда принимает архитектурно значимое решение. К таким относятся выбор базы данных, паттерна интеграции, способа развертывания, принятие ограничения или допущения. Решение считается архитектурно значимым, если оно заметно влияет на структуру системы, ее качества или последующие решения.
Не нужно оформлять ADR для каждого шага. Делать это важно только для решений с длительными последствиями. Например, выбор технологического стека, важных компонентов, взаимодействия модулей, стандартов, которые команда будет соблюдать. |
Преимущества ADR
Они декомпозируют архитектурный документ на отдельные независимые записи. Легче поддерживать небольшой файл (ADR) в актуальном состоянии, чем править большой архдок.
ADR рассказывает историю решений, так как ADR нельзя удалить — можно только заместить. Благодаря этому всегда можно посмотреть последовательность ADR и понять эволюцию архитектуры.
Новые участники команды могут быстро вникнуть, прочитав ADR: они увидят контекст и причину, по которой решение принято, а не будут гадать на кофейной гуще.
ADR поощряет обдумывание альтернатив: при написании мы фиксируем все доступные опции и аргументы «за» и «против». Это структурирует мышление архитекторов.
ADR — элемент корпоративной памяти. Даже если проект завершен, ADR хранятся и могут быть переиспользованы.
Практика хранения ADR
Расхожее требование — хранить все ADR рядом с кодом, то есть в репозитории, чтобы они версионировались вместе с проектом. Оптимально завести в каждом репозитории проекта папку /docs/architecture/adr/ и складывать ADR туда, нумеруя файлы последовательно: 001-решение1.md, 002-решение2.md и т. д. Это гарантия, что при изменении кода команда не забудет обновить или добавить ADR.
Также можно хранить в Wiki — это удобнее менеджерам. Поэтому компании часто делают и то, и другое: хранят ADR как Markdown в Git, а в Wiki они автоматически подтягиваются или дублируются для удобства поиска. Главное — чтобы не расходились версии.
Связь с архитектурным комитетом
ADR и архитектурный комитет тесно связаны. Когда команда готовится к заседанию комитета с архитектурным документом, многие ключевые решения уже должны быть оформлены в виде ADR. Комитет проверяет ADR так же, как большие документы. Просто фокус у ADR на конкретном решении.
Иногда ADR рождается из обсуждений на комитете: например, возник новый вопрос – комитет поручил оформить его как ADR. В повседневной разработке команда может принимать ADR самостоятельно, но для критических решений стоит привлекать комитет.
Жизненный цикл ADR
Первоначально Proposed (предложен) — когда автор его написал, но, возможно, не согласовал.
После обсуждения/одобрения становится Accepted (принят). Но в некоторых случаях может быть и отклонен.
Если через время решение изменилось, старый ADR помечают как Superseded (заменен новым ADR) либо как Deprecated (устарел, больше не актуален).
В новый ADR указывают номер замененного. Все ADR сохраняются в истории. Удалять их запрещено — прошлые решения важны, потому что напоминают, от какого решения и почему ушли. Да и в целом мы склонны накапливать данные о компании внутри собственной DWH-системы.
Расширенный шаблон ADR
Классический шаблон ADR включает несколько разделов: Title, Context, Decision, Status, Consequences. Расширенный шаблон адаптируется к потребностям корпоративной команды и архитектурного комитета.
Вообще можно предложить такой шаблон ADR:
ID и Заголовок (Title). Уникальный идентификатор решения и краткое название в форме короткой фразы.
Статус (Status). Текущий статус ADR: Proposed / Accepted / Rejected / Superseded / Deprecated.
Контекст и Постановка проблемы (Context and Problem Statement). Описание предпосылок и мотивов решения.
Альтернативы (Considered Options). Перечень альтернативных решений, которые рассматривались. Желательно по каждому указать основные плюсы и минусы. Это показывает, что выбор был взвешенным.
Решение (Decision). Выбранный вариант и описание сути решения. Формулируется примерно так: «Мы решили сделать X, потому что ...» Если решение принимает архкомитет, можно добавить фразу «Одобрено Архитектурным комитетом (протокол №...)».
Обоснование (Justification). Расширенный шаблон может включать явный раздел «Обоснование выбора». Здесь поясняем, почему выбранное решение считается лучшим.
Последствия (Consequences). Описание последствий принятого решения: положительные, отрицательные и нейтральные. По сути, фиксируем, что изменится в проекте из-за этого решения.
Статус внедрения, план действия. Можно добавить секцию о том, как решение будет реализовано, хотя это не обязательно. В расширенном шаблоне, ориентированном на комитет, можно описывать следующие шаги.
Дата и участники. В конце ADR обычно указывают дату принятия решения. В расширенной версии имеет смысл добавить авторов и участников обсуждения: кто оформил ADR, кто утвердил.
Связи и ссылки. В конце можно перечислить ссылки на связанные ADR, на внешние документы и на ресурсы.
Расширенный шаблон делает ADR чуть длиннее, но лучше стремиться к лаконизму. В идеале это одна-две страницы текста.
Практика в команде
Внедрение ADR — это во многом культурный момент. Важно, чтобы:
Команда понимала ценность ADR, а не рассматривала документ как лишнюю бюрократию. Для этого архитектурный комитет может обучить команды: провести небольшой воркшоп, привести примеры хороших ADR, показать, как они экономят время.
Сделать ADR частью Definition of Done в разработке. Например, «фича считается завершенной, если для значимых решений по ней оформлены ADR». Это можно прописать в процессе и чек-листах. Такой же пункт можно добавить и в чек-листы на GitLab: «Сверился с ADR, решение ему не противоречит».
Регулярно просматривать ADR: раз в спринт архитектор проекта или тимлид может проверять, нет ли решений, которые уже были приняты, а ADR по ним нет.
Со временем, накопив много ADR по разным проектам, архитектурный комитет может провести анализ и выделить общие рекомендации. Например, если по 10 проектам ADR показывают, что все выбрали Kafka для очередей, можно оформить это как стандарт: «в компании используем Kafka для межсервисной коммуникации». Тогда новые проекты могут сразу следовать стандарту, и ADR потребуется только если они хотят отступить от него. Таким образом, ADR служат входом в базу знаний корпоративной архитектуры.
Что в итоге
Концепция ADR — важная часть архитектурного процесса. Она обеспечивает легковесность документации и непрерывность архитектурных знаний. Расширенный шаблон ADR, адаптированный под архитектурный комитет, помогает фиксировать решения, принятые коллективно, в структурированном виде, удобном для дальнейшего использования.
А еще благодаря ADR ни одно решение не будет забыто или потеряно. Поэтому эта практика лежит в фундаменте устойчивой и прозрачной архитектуры всех продуктов компании.
На этом всё. Напомню, что это уже вторая статья, посвященная работе архитектурного комитета. Первая рассказывала о Definition of Ready и Definition of Done, а также про статусную модель на доске архитектурного комитета. Если у вас остались вопросы — буду рад ответить в комментариях. Также жду вас в телеграм-канале нашей тимлидской команды и в моем личном.