Архитектурные решения (ADR) с записи ревью: «почему» рядом с кодом

2026-10-18

В любой кодовой базе есть часть, которая следующему читателю кажется ошибкой. Процесс-ретранслятор, который никто не помнит, как добавляли; таблица, которую каждую неделю очищают; очередь там, где хватило бы прямого вызова. Причины когда-то прозвучали вслух на архитектурном ревью, а люди, которые их называли, давно перешли в другие команды. У нового инженера два пути: неделю расспрашивать всех вокруг или «починить».

Есть путь короче. Запишите архитектурное ревью, нажимайте горячую клавишу, когда звучит решение, компромисс или отвергнутый вариант, и отправьте запись в канал Architecture. Отметки остаются на фразах, со временем и именем говорящего. Сразу после ревью AI-ассистент в Claude Code, Cursor или Claude читает эти отметки по MCP и пишет черновик Architecture Decision Record (ADR, запись об архитектурном решении) для репозитория. Через месяцы обсуждение всё ещё на месте — для любого, кто спросит «почему».

Руководство описывает приложение Speak-Y для macOS, сверено 18 октября 2026 года, и рассчитано на техлида, чья команда уже делится встречами в воркспейсе. Если воркспейса ещё нет, сначала создайте его.

Почему на вопрос «зачем так сделано?» нет ответа

Решение описали ещё в 2011 году. Пост Майкла Нюгарда Documenting Architecture Decisions (сверено 18 октября 2026 года) предлагает короткую запись для каждого значимого решения — название, контекст, решение, статус, последствия, — которая хранится в репозитории рядом с кодом. Его довод — ровно та проблема, что выше: новичок в проекте, который не знает, почему решение было принято, может только слепо его принять или слепо отменить. Сайт сообщества ADR называет набор таких записей журналом решений проекта.

Команды, которые ввели ADR, всё равно теряют «почему», и в трёх предсказуемых местах:

• Контекст восстанавливают задним числом. Запись пишут после ревью, по памяти, тот, у кого нашлось время. Ограничения, которые определили решение, забываются первыми.
• Отвергнутые варианты сжимаются до строчки. «Рассматривали CDC» ничего не говорит о том, почему он проиграл, а именно это нужно следующему, прежде чем предлагать его снова.
• Запись так и не пишут. Ревью, которое заканчивается в 16:00, соревнуется с кодом, который нужно сдать завтра.

Запись встречи сохраняет все три. Отметки делают их находимыми, а ассистент превращает их в черновик, пока детали не стёрлись.

Разовая настройка: три отметки и канал Architecture

Отметки. В Speak-Y изначально есть один тип заметок — Отметить момент на ⌥1. Добавьте три своих в разделе Настройки → Заметки: нажмите Добавить тип заметки, введите Decision в поле Название типа, нажмите Сохранить, затем Назначить клавишу и нажмите ⌥2. Повторите для Trade-off на ⌥3 и Rejected на ⌥4. Каждая отметка ложится на раздел записи:

• Decision — что команда договорилась строить. Становится решением в ADR.
• Trade-off — цена, которую команда приняла вместе с ним. Становится последствиями.
• Rejected — вариант, который проиграл, вместе с причиной. Становится рассмотренными альтернативами.

Контекст — это обсуждение вокруг отметок; ассистент берёт его из транскрипта. В формате Нюгарда отдельного раздела для отвергнутых вариантов нет; в шаблоне MADR он есть — Considered Options.

Канал. Один публичный канал для архитектурных ревью под названием Architecture, в который может вступить любой инженер. В меню ⋯ воркспейса выберите Новый канал. Ревью дизайнов, чувствительных к безопасности, — модель угроз, схема аутентификации — отправляйте в приватный канал; что выбрать, разобрано в статье кто что видит в каналах встреч.

На ревью: назовите компонент, затем нажмите клавишу

Запустите запись встречи в Speak-Y, когда начинается ревью. Никакой бот к звонку не подключается: Speak-Y записывает микрофон и звук звонка на вашем Mac, поэтому всё работает одинаково в Zoom, Google Meet, Teams или в переговорной. Скажите всем, что ревью записывается.

Транскрипт знает только то, что было сказано, поэтому окупаются три привычки:

1. Называйте компонент, прежде чем его обсуждать. «Публикатор платёжных событий в payments-service» делает каждую следующую отметку находимой по тому названию, которое инженер потом будет искать.
2. Дайте прозвучать причине, потом нажимайте. Отметка охватывает последние 15 секунд транскрипта до нажатия, так что фраза со словом потому что попадает внутрь отметки.
3. Отмечайте и проигравших. Отметка Rejected на фразе «двойная запись теряет события, если сервис падает между двумя записями» — та самая строка, которая сэкономит следующему ревью полчаса.

Обычно записывает и нажимает клавиши техлид, который ведёт ревью. Горячие клавиши работают из любого приложения, схема или код остаются перед глазами.

После ревью: имена, теги, В канал

Две минуты в окне записи, пока всё свежо в памяти:

1. Укажите имена спикеров. Нажмите Speaker 1, Speaker 2 и так далее и введите настоящие имена. Отметка полезна ровно настолько, насколько полезно имя рядом с ней.
2. Поставьте теги. Добавьте название сервиса и номер записи, которую вы собираетесь написать, например payments-service и adr-0012. По этим тегам ревью найдут и ассистент, и коллеги.
3. Проверьте отметки. Плашки над транскриптом считают их по типам: Все заметки · 8, Decision · 3, Trade-off · 3, Rejected · 2.
4. Отправьте запись. Нажмите В канал под транскриптом и выберите Architecture. В канал уходят транскрипт с именами и временными метками, итоги от AI и action items, со сквозным шифрованием; аудио остаётся на вашем Mac.
5. Покажите отметки. По умолчанию отметки личные. Нажмите плашку Личные над транскриптом и выберите Показать в # Architecture — увидят участники канала, чтобы отметки ушли вместе с записью.

Черновик ADR из отметок

Подключите ассистента к MCP-серверу Speak-Y один раз: откройте Подключить ИИ-ассистента в меню аккаунта внизу боковой панели или Настройки → Интеграции и нажмите Подключить рядом с Claude, ChatGPT или Cursor. Для Claude один клик настраивает и Claude Desktop, и Claude Code. Сервер бесплатен на любом тарифе.

Затем в репозитории попросите:

Напиши черновик ADR 0012 по ревью payments-service с тегом adr-0012: контекст, решение, последствия и отвергнутые варианты. Укажи, кто и когда сказал каждый пункт.

Ассистент находит ревью по тегу и читает его. Вместе с транскриптом Speak-Y передаёт ему отметки списком — у каждой смещение от начала записи, тип, спикер и первые слова фразы, — поэтому черновик приходит с тремя решениями, тремя принятыми издержками и двумя отвергнутыми вариантами, у каждого — имя и время. В Cursor ассистент спрашивает разрешения перед запуском каждого инструмента, если вы это не поменяете.

Отредактируйте черновик, прежде чем коммитить. Три поля — ваши, а не ассистента:

• Статус. Proposed или accepted — это решение команды, транскрипт его не подскажет.
• Ответственный. Кто ответит на вопросы о нём в следующем квартале.
• Обратная ссылка. Напишите, где лежит обсуждение, — канал, дата и тег, — чтобы следующий читатель мог восстановить ход рассуждений. Запись в канале защищена сквозным шифрованием, поэтому ссылка работает для коллег в воркспейсе, а не для публики.

Через месяцы: новый инженер спрашивает «почему»

ADR в репозитории на одной странице отвечает на вопрос что. Когда этого мало, обсуждение в одном шаге.

В приложении. Приглашённые коллеги вступают бесплатно на любом тарифе. Новый инженер, вступивший в воркспейс, видит публичный канал Architecture со всей историей. Откройте его, нажмите лупу в шапке канала и введите название компонента, например outbox. Поиск читает транскрипты всех ревью канала и показывает совпавшие строки с их временем.

В редакторе. В Cursor или Claude Code, с открытым кодом:

Почему payments-service пишет события в таблицу outbox, а не публикует их в Kafka напрямую? Что отвергли?

Ассистент ищет по записям, которые видны этому инженеру, находит ревью и отвечает по нему: решение, кто возражал против двойной записи и почему и что команда приняла взамен. Тот же подход к вопросам о коде в целом описан в статье контекст встреч для голосового программирования в Cursor.

Чего запись ревью не заменяет

Запись хранит рассуждения. Четыре вещи по-прежнему живут в другом месте:

• Схема. Доски, слайды и диаграммы последовательностей в запись не попадают. Укажите их ссылкой в ADR.
• Окончательный статус. Отметка Decision фиксирует, что все в комнате согласились; было ли решение потом заменено — смотрите в записях репозитория.
• Решения, принятые в переписке. Выбор, сделанный в обсуждении pull request, до ревью не дошёл. Впишите его в ADR напрямую.
• Сам код. Если код и ADR расходятся, работает код. Обновите запись или код — запись встречи говорит только о том, что было задумано.

Ограничения и стоимость

• Длительность. По данным speak-y.com на 18 октября 2026 года, Free останавливает запись встречи на 30 минутах, Pro ($10 в месяц) — на 60, Pro+ ($15) и Max ($30) — на четырёх часах. Для долгой дизайн-сессии нужен Pro+ или перерыв через час.
• Один записывающий. Если одно ревью записывают двое, получатся два половинчатых списка отметок.
• Каналы — на Mac. Воркспейсы и каналы есть в приложении для macOS. Для создания воркспейса нужен Pro или выше; коллеги вступают бесплатно на любом тарифе.

Коротко

Три типа заметок — Decision, Trade-off, Rejected — на ⌥2, ⌥3 и ⌥4. На ревью: назовите компонент, дайте прозвучать причине, нажмите клавишу. После него: имена, теги, В канал → Architecture, показать отметки. Затем один вопрос ассистенту в репозитории — и вы правите черновик ADR, а не пишете его по памяти. На странице Teams — обзор воркспейсов и каналов, а статья журнал решений, который ведётся сам применяет ту же идею к продуктовым решениям.

FAQ

Как сохранить, почему было принято архитектурное решение?

Запишите архитектурное ревью в Speak-Y и нажимайте горячую клавишу, когда вслух звучит решение, компромисс или отвергнутый вариант. Отправьте запись в командный канал, например Architecture. В канале обсуждение хранится с именами и временными метками, а AI-ассистент, подключённый по MCP, превращает отметки в черновик Architecture Decision Record для репозитория.

Может ли Claude Code или Cursor написать ADR по записи встречи?

Черновик — да. Ассистент, подключённый к MCP-серверу Speak-Y, находит ревью по тегу, читает транскрипт и список отметок с типом, временем и спикером и заполняет контекст, решение, последствия и отвергнутые варианты. Статус, ответственный и окончательная формулировка остаются за инженером, который коммитит файл.

Как новому инженеру узнать, почему сервис устроен именно так?

Двумя способами. Откройте канал Architecture в приложении Speak-Y для macOS и найдите в нём название компонента или спросите ассистента в редакторе, например Cursor или Claude Code, почему сервис делает то, что делает. Ассистент ищет по записям, которые видны этому инженеру, и отвечает, кто что сказал и когда.

Записывает ли Speak-Y доску или схемы, которые показывали на ревью?

Нет. Speak-Y записывает звук на Mac, который запустил запись: микрофон и звук приложения для звонков. Схем, слайдов и досок в записи нет. Называйте компонент вслух, прежде чем его обсуждать, а схему укажите ссылкой в ADR.

Сколько это стоит?

MCP-сервер бесплатен на любом тарифе. Для создания командного воркспейса нужен Pro или выше, а коллеги вступают бесплатно на любом тарифе. По данным speak-y.com на 18 октября 2026 года, Free останавливает запись встречи на 30 минутах, Pro ($10 в месяц) — на 60, Pro+ ($15) и Max ($30) — на четырёх часах.