Универсальный шаблон RFC / Design Doc

Рекомендация: 

• для маленьких задач — мини‑RFC на 1–3 страницы (сжать разделы, можно убрать «Alternatives» и «Risks»);
• для крупных проектов или платформенных решений — использовать весь шаблон.

RFC: Краткое название

• Статус: Draft | In review | Approved | Rejected | Superseded by RFC-XXXX
• Дата: YYYY-MM-DD
• Автор(ы): @author1, @author2
• Команда: <team / product area>
• Тип: Feature / Refactor / Infra / ADR (решение с широким эффектом)

1. TL;DR / Abstract

1–3 абзаца: что делаем, зачем и какой ожидаемый эффект для бизнеса/пользователя/инженерии. Это должен прочитать менеджер или соседняя команда и понять суть без деталей.

Объяснение: 

• Это аналог «Abstract» у Uber и краткого описания у ADR: быстрый вход для всех, включая тех, кто не читает весь документ.

2. Контекст и проблема

• Текущая ситуация (как система работает сейчас, какие ограничения, существующие решения).
• Формулировка проблемы: где болит, какие метрики/кейсы говорят, что нужно изменение.
• Исторические решения и почему они перестали устраивать (если есть).

Объяснение: 

• Объединяет Google‑раздел «Context and scope» и ADR‑«Problem/History», чтобы читателю не нужно было копать по wiki, чтобы понять, откуда взялась инициатива.

3. Цели и не‑цели

• Goals:
• G1: конкретный достигаемый результат (например, уменьшить p95 latency X→Y, снизить MTTR, добавить новый use‑case).
• Non‑goals:
• NG1: вещи, которые звучат разумно, но сознательно не решаются в данном RFC.

Объяснение: 

• Секция из Google‑доков, критична для управления ожиданиями и защиты от «scope creep»; помогает ревьюерам понимать рамки.

4. Варианты решений (Alternatives)

Для каждого варианта:

• Option N — краткое название
• Идея: 2–3 предложения о сути подхода.
• Плюсы.
• Минусы / риски.
• Почему в итоге не выбран (если это не основной вариант).

Объяснение: 

• Это явная реализация «Alternatives considered» из Google и ADR‑раздела «What alternatives did we explore?», которая и даёт документу максимальную ценность «на будущее» и для новых людей.

5. Выбранное решение (Decision)

• Формулировка решения в 2–3 предложениях: что именно принимаем.
• Класс решения (если уместно в духе ADR):
• Best practice / Novel pattern / Directive (обязательное для всех).
• Почему этот вариант лучше других при данных целях и ограничениях (ссылка на раздел 4).

Объяснение: 

• Это «Decision» из ADR и центральная часть RFC: одно место, где можно увидеть финальный выбор и логику.

6. Детальный дизайн

Здесь — ядро инженерной части, но без превращения документа в мануал по реализации.

6.1. Архитектура и системный контекст 

• Краткое описание новой/изменённой архитектуры.
• System context diagram (словами или картинкой/ссылкой): какие сервисы/компоненты взаимодействуют, какие внешние зависимости.

6.2. API / контракты 

• Основные эндпоинты, события, очереди, схемы сообщений, контракты между сервисами.
• Только те детали, которые важны для понимания трейд-оффов (без полного swagger/schema).

6.3. Данные и хранение 

• Какие данные добавляются/меняются, где и как хранятся.
• Важные моменты: миграции, индексы, консистентность, TTL.

6.4. Алгоритмы / ключевые механики 

• Описание нестандартных алгоритмов или логики (без полного кода).
• Ссылки на прототипы/спайки в репозитории.

Объяснение: 

• Включает рекомендуемые разделы Google («System-context-diagram», API, Data storage, Code), но фокусируется на тех деталях, которые важны для понимания риска и стоимости решения.

7. Кросс‑срезы (Cross‑cutting concerns)

Отдельными подпунктами:

• Надёжность и производительность: ожидаемая нагрузка, SLAs/SLOs, деградационные сценарии, rate limiting, fallbacks.
• Безопасность: аутентификация, авторизация, секреты, доступ к данным, возможные атаки.
• Конфиденциальность и данные пользователей: PII, минимизация, retention, маскирование.
• Наблюдаемость: логирование, метрики, трассировка, алерты; какие дашборды будут.
• Локализация/региональные особенности (если релевантно).
• UX / UI (для клиентских фич): high-level UX, accessibility, аналитика.

Объяснение: 

• Это прямое развитие секции «Cross-cutting concerns» у Google и списков Uber-шаблонов (SLAs, load testing, security, metrics, accessibility), чтобы эти вопросы никогда не «терялись».

8. План внедрения (Rollout plan)

• Этапы:
• Milestone 1: прототип / эксперимент.
• Milestone 2: ограниченный rollout (feature flag, % трафика).
• Milestone 3: полный rollout, удаление legacy.
• План миграции данных/клиентов (если есть).
• Флаги, конфигурация, возможность отката.

Объяснение: 

• Развивает блоки «Testing & rollout» у Uber и практику ADR, где обязательно описывается, какие действия нужно предпринимать после принятия решения.

9. Риски и открытые вопросы

• Риски (технические, продуктовые, организационные) и как они будут снижаться.
• Открытые вопросы, по которым требуется вход от ревьюеров или других команд.

Объяснение: 

• Помогает честно зафиксировать неопределённость и делает ревью более целевым: видно, где автору нужны чужие решения/опыт.

10. Влияние и последствия (Consequences)

• Позитивные эффекты: качество, скорость разработки, снижение долга, бизнес‑метрики.
• Негативные/побочные: рост сложности, новых обязанностей команд, затрат.
• Чего теперь нельзя/не надо делать (например, какие паттерны считаются устаревшими после этого RFC).

Объяснение: 

• Этот раздел вдохновлён ADR‑«Consequences» и важен для понимания долгосрочных компромиссов (например, рост операционных расходов в обмен на упрощение разработки).

11. План ревью и участие

• Обязательные аппруверы (by role):
• Техлид команды.
• Платформенный/архитектор.
• Представитель затронутых команд (пример: мобильная команда, если трогаете API).
• Опциональные, но желательные ревьюеры (domain experts).
• Каналы и дедлайны ревью:
• PR в репозитории rfcs/ с тегами.
• Обсуждение в issue/комментариях.
• Планируемая дата «последнего call for comments».

Объяснение: 

• Объединяет Uber‑подход с явными reviewers и Stitch Fix‑подход с фазами сбора фидбэка, плюс практику Caitie McCaffrey хранить всё в git и ревьюить через обычный PR‑флоу.

12. Имплементация и дальнейшее сопровождение

• Ссылки на задачи/эпики (Jira, Linear и т.п.).
• Критерии «готово» (Definition of Done) для этого RFC.
• Как и где будет поддерживаться актуальность:
• Обновление этого RFC или новый RFC/ADR в качестве «amendment», если дизайн сильно меняется.

Объяснение: 

• Учитывает lifecycle из Google (creation → review → implementation → maintenance) и ADR‑практику хранения в центральном репозитории.