Skip to main content
Запись архитектурного решения — это не документация функции. Она фиксирует выбор, который ограничивает дальнейшую работу, отвергнутую альтернативу, цену этого выбора и условие, при котором кто-то будет прав, вернувшись к нему. Описательные страницы — Обзор архитектуры и Технологический стек — рассказывают, чем Omniflow является сегодня. Эти записи объясняют, почему ему позволено быть таким и никаким другим. Они существуют потому, что дорогие ошибки в платформе, которая двигает деньги, — не те, о которых кто-то спорил. Это те, о споре по которым никто не помнит, и которые отменяет участник, у которого не было ни одного способа узнать, что причина была.

​
Записи

​
Формат

У каждой записи одни и те же четыре раздела, и они намеренно короткие. Запись, которую никто не дочитывает, ничего не ограничивает.
  • Контекст — ситуация, потребовавшая выбора, в терминах, верных на тот момент.
  • Решение — что выбрано, сформулированное так, чтобы рецензент мог понять, нарушает ли его пул-реквест.
  • Последствия — чего это стоит, включая то, что теперь стало сложнее. Запись, перечисляющая только выгоды, — это агитация, а не решение.
  • Когда пересматривать — наблюдаемое условие, при котором возврат к вопросу будет уместен. «Когда это станет проблемой» — не условие; «когда очередь заданий придётся разделить между двумя установками» — условие.
У каждой записи есть статус. Принято означает, что она ограничивает текущую работу. Заменено NNNN означает, что более поздняя запись её заменила: исходный текст никогда не правят под новое решение, потому что рассуждение, оказавшееся неверным, — это как раз то, что стоит сохранить.

​
Когда добавлять запись

Добавляйте запись, когда изменение будет дорого откатывать, а его обоснование не видно в коде, который из него получается. На практике это: новое надёжное хранилище, новая внешняя зависимость на пути запроса, изменение того, кто владеет категорией данных, новая граница доверия или снятие защиты, на которую что-то рассчитывало. Не заводите запись ради замены библиотеки, рефакторинга или решения, обоснование которого читатель восстановит по диффу. AGENTS.md называет два изменения, которые вообще нельзя вносить без принятой записи: введение брокера сообщений и добавление фреймворка внедрения зависимостей. Механика — расположение файла, русское зеркало и запись в навигации — такая же, как у любой другой страницы, и описана в Документации. Нумеруйте файл следующим свободным четырёхзначным префиксом; номера не переиспользуются, в том числе номера заменённых записей.

​
Смежное

Обзор архитектуры

Процессы, путь запроса и то, как изменение состояния фиксируется вместе со своим долговременным заданием.

Технологический стек

Каждый компонент, почему он здесь вместо очевидной альтернативы и чего намеренно нет.

Владение данными

Какая система авторитетна для каждой категории данных.

Документация

Как добавить страницу и не рассинхронизировать русское дерево.