Карта документов: от vision до критериев приёмки

Сцена · почему здесь две очереди

Ты приходишь в проект. В репозитории двести тысяч строк, и среди них две разные очереди сообщений: половина событий едет через RabbitMQ, половина через таблицу в Postgres. Ты спрашиваешь: почему две? Тимлид пожимает плечами: так было до меня. git blame приводит к коммиту с подписью refactor. В мессенджере находится тред на триста сообщений, который обрывается фразой «созвонимся и решим». Итог созвона не записал никто.

Через месяц команда тратит два дня на то, чтобы заново принять то же самое решение. И наступает на те же грабли, о которых знал ушедший автор: он уже пробовал перевезти всё на одну очередь и откатился. Знание было, но жило в голове, а голова уволилась.

В уроке про принципы архитектуры мы говорили, что архитектура это декомпозиция, именование и связывание. Этот урок про четвёртую силу: память. Архитектура живёт не в коде, а в решениях, и документы фиксируют «почему».

Карта урока · что заберёшь

• Словарь жанров: ADR, RFC, BCP, NFR, PRD, HLD и LLD, кто из них до решения, а кто после.
• Два режима документа: нарратив для людей и структура для машин.
• Этаж стратегии: vision, roadmap, stakeholders, риски и допущения.
• Этаж требований: от формулировки проблемы до критериев приёмки в Gherkin.
• Сквозной пример: одностраничная спека на вход по магик-линку.

Код отвечает «что», документ отвечает «почему»

Код это исчерпывающий ответ на вопрос «что система делает сейчас». Прочитал функцию, узнал поведение. Но на три вопроса код не отвечает вовсе:

1. Почему так? Почему две очереди, почему Postgres, а не Mongo, почему токен живёт пятнадцать минут. В коде видна только победившая ветка истории, проигравшие альтернативы исчезли.
2. Зачем это? Какую проблему пользователя решает модуль. Код описывает механизм, не намерение.
3. Что дальше? Куда продукт движется, что обещано клиентам, что сознательно отложено.

Документ это кэш ответов на вопросы, которые иначе будут задавать тебе. Лично, в чате, по десять раз. Хорошая спека на страницу экономит сотню одинаковых разговоров. Это не бюрократия, это археология наоборот: ты оставляешь раскопанным то, что иначе придётся раскапывать потомкам.

Словарь · шесть аббревиатур

Жанров документов десятки, но шесть аббревиатур встречаются так часто, что их стоит знать как таблицу умножения:

Аббревиатура	Расшифровка	Что фиксирует	Когда пишется
ADR	Architecture Decision Record	одно принятое решение и его причины	после выбора
RFC	Request For Comments	предложение до решения	до выбора
BCP	Best Current Practice	как мы здесь делаем типовые вещи	по мере накопления практики
NFR	Non-Functional Requirements	требования к качествам системы	вместе с требованиями
PRD	Product Requirements Document	что строим и для кого	до разработки
HLD / LLD	High / Low Level Design	устройство системы крупно и в деталях	при проектировании

Запомни главную пару: RFC до решения, ADR после. RFC спрашивает «давайте обсудим, как нам сделать X». ADR утверждает «мы решили сделать X вот так, вот почему, вот что отвергли». Подробно обе формы разберём в уроке про design records и ADR.

Два режима: нарратив для людей, структура для машин

Записи делятся на два режима. Нарративные читают люди: история, контекст, аргументы, голос автора. Структурированные парсят машины: фиксированные поля, предсказуемый формат, можно прогнать скриптом.

Раньше второй режим был нужен только инструментам вроде генераторов changelog. Теперь структурированные записи читают и AI-агенты: глоссарий домена, реестр фич-флагов, каталог событий в репозитории превращаются в контекст, по которому агент отвечает на вопросы о системе. Документ, который раньше окупался за год, теперь окупается за неделю: его читает не только новичок на онбординге, но и каждый запуск агента.

Практический вывод: ключевые решения держи в репозитории рядом с кодом, в предсказуемом формате. Вики, где страницы умирают без хозяина, и чаты, где решения тонут, для этого не подходят.

Здание документов · пять этажей

Дальше пойдём по зданию. Представь документы как этажи: чем выше этаж, тем реже он меняется и тем дальше он от кода. Этот урок проходит два верхних, остальным посвящены следующие уроки раздела.

┌─────────────────────────────────────────────────┐
│ Стратегия      vision · roadmap · риски         │ ← этот урок
├─────────────────────────────────────────────────┤
│ Требования     PRD · user story · приёмка       │ ← этот урок
├─────────────────────────────────────────────────┤
│ Design         C4 · RFC · ADR                   │ ← урок 06
├─────────────────────────────────────────────────┤
│ Исполнение     README · CI/CD · план отката     │ ← урок 07
├─────────────────────────────────────────────────┤
│ Качество       SLO · postmortem · governance    │ ← урок 08
└─────────────────────────────────────────────────┘
  Контракты между командами (урок 09) скрепляют
  этажи, как лифтовая шахта.