Методология

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

Зачем нужен этот документ

Предыдущие итерации роадмапа в Obsidian Canvas и Excalidraw разрастались до ~200 узлов и теряли навигабельность. Mermaid-графы L1+L2 inventory тоже начинали дрейфовать в ту же сторону — в граф попадал конкретный тулинг (Prometheus, Grafana, Terraform и т.п.), а компетенции дублировались между ветвями (Knowledge Management, Capacity Planning, Disaster Recovery, SLO-семейство).

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

Принцип разделения ветвей

Критерий, по которому компетенция относится к ветви, — главный объект деятельности.

Ветвь	Главный объект	На что направлена деятельность
SRE Culture	Люди и нормы	Договорённости, отношения, обмен опытом, метрики как инструмент разговора
SRE Engineering	Технические артефакты	Код, инфраструктура, инструменты наблюдаемости и автоматизации
SRE Practices	Процессы и ритуалы	Последовательность действий, операционная зрелость, повторяемые сценарии

Формулировка проверочного вопроса: «Что именно изменяется в результате этой деятельности — отношения между людьми, состояние системы или ход процесса?» Ответ определяет ветвь.

Как разрешаются пересечения

Компетенция, которая на первый взгляд относится к нескольким ветвям, разводится одним из трёх способов:

Перенос. Применяем критерий «главный объект» и помещаем компетенцию в одну ветвь. Пример: Capacity Planning имеет главным объектом инфраструктуру → SRE Engineering. Упоминание в IT Management под Culture снимается.
Разделение на разные концепты. Если за одним именем скрываются методологически разные сущности, они получают разные имена и разводятся по ветвям. Пример: Postmortem как ритуал (формат встречи, action items) → Practices; Postmortem Culture как норма (blameless-принцип, психбезопасность) → Culture.
Cross-link с обоснованием. Если компетенция действительно живёт на стыке и развести её — значит исказить смысл, она остаётся в одной ветви, а в другой появляется ссылка на тот же лист с явной пометкой «cross-link». Это исключение, а не правило; каждый случай документируется в inventory/overlaps.md в репозитории.

Дубль имени компетенции в двух ветвях без явной пометки cross-link — дефект, который чинится по таблице пересечений.

Политика контроля детализации

Цель — удержать роадмап в формате читаемой карты, а не графа на 200 узлов.

Форма графа

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

Уровни графа. Под ветвью два уровня: Branch → L1 → L2. Всё, что просится на третий, — уже не узел карты, а содержание leaf-страницы.
Уровни листьев. Лист подключается к L1 либо к другому листу — уточнением уже написанной практики (Runbooks → Playbooks). Уровень уточнений один, и это не соглашение, а тип в roadmap.ts: у подлиста нет поля children, второй уровень не пройдёт bun run check. Просится третий — значит родитель дорос до L1 и повышается.

Переполненный узел лечится разбиением, а не отказом заводить новый: так из Information Security с девятью листьями в одном списке выделился Secure Development.

Что не попадает в граф

Конкретный тулинг. Названия продуктов (Prometheus, Grafana, Loki, Tempo, Terraform, ArgoCD, k6, Gatling и т.п.) не являются узлами графа. Они живут в секции «Материалы» соответствующего листа.
Языки, утилиты, форматы. bash, jq, sed, awk, конкретные дистрибутивы Linux — материалы, не узлы.
Внешние стандарты. SFIA-уровни, методики SRE Book — не узлы, а атрибуты листьев и контекст документа.

В графе живут концепты компетенций: «Metrics», «Distributed Tracing», «IaC», «Load Testing», «SLI-based Alerting». Один концепт — один узел.

Размер ветвей

Ветви заведомо неравные: Engineering шире по техническому стеку, Culture уже. Это нормально и выравнивания не требует — сравнивать ветви по числу узлов не с чем.

Две независимые оси развития

Роадмап оперирует двумя ортогональными осями: priority (обязательность для роли) и SFIA (уровень зрелости инженера). Компетенция может быть Must Have даже на L3 (Junior) или Nice to have на L6+ (Principal). Не путать.

Priority — обязательность для роли

🔴 Must Have — без компетенции инженер не может выполнять основную работу.
🟡 Mandatory — компетенция, которой ожидаемо владеет любой SRE на стабильном этапе работы.
🟢 Nice to have — расширяет возможности, но не блокирует.
🔵 On Demand — изучается, когда проект требует.

Priority L1 живут только в src/data/roadmap.ts (поле priority). Цветовая разметка на странице Приоритеты генерируется из этого поля автоматически.

SFIA — уровень зрелости инженера

Хранится во frontmatter каждой leaf-страницы (поле sfia), уровни 3..7 соответствуют Junior → Principal. См. фреймворк SFIA.

В данных roadmap.ts SFIA-уровни не отражаются: это ось про инженера, а граф описывает компетенции. Поэтому sfia — одно из двух полей, которые лист хранит у себя; второе — status. Всё остальное в блоке метаданных под заголовком листа рендерится из графа компонентом LeafMeta.astro.

Что обе оси не описывают

Priority и SFIA — про инженера: что он обязан уметь и на каком уровне зрелости. Порядок, в котором практики строятся в сервисе, ни одна из осей не задаёт; для этого используется иерархия надёжности Дикерсона — см. Порядок построения. Она не влияет на данные графа и ничего не размечает в roadmap.ts.

Чек-лист перед коммитом изменений в граф или листья

Новый узел проходит по критерию «главный объект деятельности» — однозначно одна ветвь.
Узел не дублирует уже существующий в другой ветви (если дублирует — фиксируется в inventory/overlaps.md и решается переносом / разделением / cross-link).
Узлов графа не больше двух уровней под ветвью; иначе содержимое уходит в leaf-страницу.
В графе нет названий продуктов; тулинг помещён в материалы листа.

Источники структуры

Структура графа компетенций распределена по нескольким файлам, каждый отвечает за свой срез. Это важно знать, чтобы при правках не дублировать данные и не вызывать рассинхрон.

Файл	За что отвечает	Чего там НЕТ
`src/data/roadmap.ts`	L1-узлы каждой ветви и их порядок, priorities L1, инвентарь L2 каждого L1, leaves под L1 и их подлисты	SFIA-уровни
`src/content/docs/{culture,engineering,practices}.mdx`	обзор ветви: интро и карта; карточки L1 рендерятся из данных	описания L1, L2 концепты, leaves
`src/content/docs/<branch>/<l1-id>.mdx`	описание одного L1 прозой	priorities, L2, leaves (рендерятся из `roadmap.ts` через `L2Concepts.astro` и `NodeCards.astro`)
`inventory/overlaps.md` (в репозитории, не на сайте)	решения по пересечениям компетенций между ветвями	сами компетенции
`src/content/docs/<branch>/<slug>.md`	содержимое одного листа: умения / материалы / best practices / связанные; во frontmatter — `sfia` и `status`	ветвь, путь и priority (там — в `roadmap.ts`, рендерятся `LeafMeta.astro`)

Инвариант L1. У каждого L1 из roadmap.ts должна быть страница src/content/docs/<branch>/<l1-id>.mdx — её адрес выводится из данных функцией l1Href(). При добавлении или переименовании L1 страница заводится или переименовывается тем же PR, иначе карточка на странице ветви ведёт в никуда. Порядок L1 задаёт только roadmap.ts: страницы ветвей и сайдбар рендерят карточки и группы из данных.

Priorities L1 живут только в roadmap.ts. Цветовая разметка на странице /priorities/ генерируется автоматически.

L2 концепты живут в roadmap.ts полем l2 у своего L1. Это инвентарь домена: и то, что уже расписано листом, и то, что пока только названо. Отдельного флага «расписано» нет — концепт, у которого есть лист с таким же именем, рендерится ссылкой на него, остальные остаются текстом. Инвариант «каждый лист назван в l2 своего L1» держит tools/data/check.ts, он же ловит L1 без страницы и лист без файла.

Leaves регистрируются в roadmap.ts под соответствующим L1 — либо, если лист уточняет уже написанную практику, в поле children этой практики. Исходники в обоих случаях лежат в каталоге ветви, src/content/docs/<branch>/<slug>.md, рядом с hub-страницами её L1, и URL остаётся плоским: /<branch>/<slug>/. Перевесить лист под другой L1 — правка одной строки в roadmap.ts, без редиректов: адрес листа от родителя не зависит. Отсюда два ограничения. Подлист живёт в той же ветви, что и родитель, потому что ветвь берётся из URL. И slug листа не может совпасть с id L1 своей ветви: они делят одно пространство имён, а /<branch>/<name>/ разбирается по данным — сначала ищется L1, потом лист. Совпадение ловит tools/data/check.ts.

Навигация строится из тех же данных: src/data/sidebar.ts разворачивает roadmap.branches в дерево, которое рисует src/components/NavTree.astro. Каждый узел дерева — одновременно ссылка на свою страницу и родитель своих детей, поэтому левая панель повторяет ту же цепочку, что и хлебные крошки. Та же структура отдаётся в секцию sidebar конфига Starlight — оттуда Starlight берёт порядок страниц для пагинации. Отдельного списка страниц для навигации нет: новый лист появляется в сайдбаре сразу после регистрации в roadmap.ts. Хлебные крошки и блок «↑» в подвале берут цепочку «ветвь → L1 → лист → подлист» оттуда же, через findPageContext().

Внешние источники методологии

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

Google SRE Book — каноничная книга про SRE-практики и принципы.
Google SRE Workbook — прикладные приёмы (SLO, alerting on SLOs, on-call); главный источник по SLI-based алертингу.
SFIA — DevOps View — формальная рамка уровней зрелости компетенций; используется в листьях как поле sfia.
DORA Research — эмпирика производительности команд доставки; источник DORA-метрик и базы для разделения ветвей.

Эти ссылки — фундамент, на котором строится граф и листья. Конкретные материалы по каждой компетенции (книги, статьи, доклады, инструменты) живут в секции «Материалы» соответствующего листа, а не здесь.

Связанные документы

Мотивация — зачем существует проект, для кого, дисклеймер.
Формат проекта — как устроена карта, шаблон листа, правила контрибуции.
Порядок построения — иерархия надёжности сервиса: в каком порядке практики имеет смысл внедрять.
inventory/overlaps.md — все известные дубли L1/L2 и принятые решения (рабочий артефакт в репозитории).
inventory/tlroadmap-review.md — что у соседнего проекта берём, что не берём (рабочий артефакт в репозитории).
Шаблон листа — inventory/leaf-template.md в репозитории (лежит вне каталога контента и на сайт не попадает).