Применимость: Cloud. Названия пунктов и доступность функций зависят от версии, плана и типа проекта. Проверяйте изменения на тестовом окружении. Описанные рабочие процедуры — предлагаемый подход, а не гарантии поставщика.
Когда одной схемы недостаточно
Команда выбрала очередь сообщений, но через полгода никто не помнит, почему отказались от прямого HTTP-вызова. На схеме видно текущее устройство, однако аргументы потерялись в переписке. Создайте отдельную запись архитектурного решения, часто называемую ADR. Для нашего сценария вопрос формулируется так: как передавать события заказа между двумя сервисами при временной недоступности получателя. Не начинайте с названия выбранного продукта: сначала опишите проблему, ограничения и заинтересованные стороны. Тогда будущая команда сможет понять, остались ли исходные условия актуальными и что именно разрешает пересмотреть решение.
Запишите критерии и альтернативы
В документе нужны контекст, рассматриваемые варианты, критерии оценки, выбранный вариант и последствия. Критерии должны быть проверяемыми: допустимая задержка, требования к повторной доставке, сложность эксплуатации и границы ответственности. Не подменяйте их общими словами «современно» или «масштабируемо». Для каждой альтернативы объясните конкретный компромисс. Например, очередь уменьшает прямую зависимость по доступности, но требует обработки повторных сообщений и мониторинга накопления. Числа и гарантии подтверждайте экспериментом вашей системы. Запись решения не должна выдавать желаемые свойства архитектуры за уже достигнутые эксплуатационные показатели.
Создайте понятный шаблон записи
В Confluence Cloud собственные шаблоны помогают сохранять одинаковую структуру материалов. Подготовьте шаблон ADR с полями автора, участников обсуждения, состояния и даты. Состояния «предложено», «принято» и «заменено» здесь являются договорённостью команды, а не универсальным встроенным процессом согласования. Добавьте подсказку для последствий: указать и преимущества, и новые обязательства. В конце оставьте ссылки на эксперимент, задачи реализации и предыдущее решение. Создайте тестовую запись и попросите коллегу заполнить её по другому вопросу. Если он не понимает поле без устного объяснения, перепишите подсказку.
Отделите обсуждение от принятого итога
Комментарии удобны для вопросов, но итоговый текст должен самостоятельно объяснять принятое решение. После обсуждения автор переносит существенные аргументы в соответствующие разделы и фиксирует ответственного за итог. Не называйте решение согласованным только потому, что никто не ответил. У команды должен быть явный порядок принятия решения, особенно при влиянии на безопасность и эксплуатацию. Если есть несогласие, сохраните его с понятной причиной. Для критичных решений используйте принятый компанией механизм подтверждения. Confluence является местом хранения записи, а организационная ответственность не возникает автоматически от наличия страницы или красивого статуса.
Свяжите запись с работающей системой
В задаче реализации добавьте ссылку на ADR, а в ADR — ссылки на ключевые изменения и проверочные результаты. После релиза сравните фактическое поведение с критериями. Например, проверьте повторную обработку события и восстановление после недоступности получателя. Если эксперимент опроверг предположение, исправьте запись и укажите новое основание выбора. Не переписывайте старое решение так, будто альтернативы никогда не рассматривались. Новое решение может заменить предыдущее с явной ссылкой. История версий обычной страницы помогает проследить редакционные изменения, но не заменяет понятную связь между последовательными решениями.
Проверьте пользу на передаче проекта
Попросите инженера, не участвовавшего в выборе, ответить по записи: какую проблему решали, от чего отказались, какие обязанности появились и при каком условии выбор стоит пересмотреть. Если ответы приходится искать в чате, документ ещё не завершён. На стартовой странице архитектуры соберите небольшой индекс действующих решений, используя согласованные метки или обычные ссылки. Устаревшую запись сохраняйте как историческую с указанием замены. При ошибочном редактировании восстановите текст через историю и повторно проверьте связи. Качественная ADR экономит время на будущих обсуждениях, потому что объясняет границы выбора, а не только его название.
Эксперимент перед окончательным выбором
Для решения об обмене событиями полезен небольшой проверочный эксперимент. Опишите тестовую нагрузку, временно недоступного получателя и повторную отправку одного события. Заранее задайте ожидаемое поведение: отсутствие потери, определённый порядок обработки там, где он нужен, и корректную реакцию на повтор. Сохраните сценарий и результаты рядом с записью решения, но отдельно от основного объяснения. Если опыт не подтверждает критерий, команда должна скорректировать реализацию или сам выбор, а не просто смягчить формулировку. Попросите эксплуатацию оценить, какие новые сигналы мониторинга потребуются после внедрения. Так документ описывает не только технический механизм, но и будущую работу сопровождения. Через несколько месяцев повторите один важный тест, если изменились нагрузка, зависимость или требования. Запись решения должна оставаться понятной даже после смены состава команды и исчезновения исходной переписки.
Официальная документация
Применить это к вашей системе
Обсудим контекст, ограничения и безопасный порядок изменений.
Обсудить задачу