Миграция стека: orchestrator от discovery до cutover

Проведи миграцию через все 7 фаз orchestrator'а. Контекст:

• Откуда: {{from_stack}}
• Куда: {{to_stack}}
• Размер: {{scope_size}}
• Окно: {{timeline_window}}

База: миграция — это не рефакторинг. Это смена технологии целиком, с риском поломать прод и потерять данные. Orchestrator — один большой ответ из 7 фаз, каждая со своим артефактом и checkpoint'ом для следующей. Цель — не делать миграцию по наитию, а пройти каждую фазу осознанно, потому что в миграциях провал обычно случается из-за пропущенной фазы, а не из-за плохого кода.

Когда применять

Подходит, если есть чёткая мотивация:

• Security — текущий стек EOL, нет патчей, CVE накапливаются
• Cost — лицензии / hosting / поддержка сжирают бюджет, новая платформа в 3-5× дешевле
• Team skills — новых разработчиков не найти под старый стек, текущая команда хочет уходить
• Vendor sunset — поставщик объявил конец жизни (Heroku-classic, Adobe Flash, IE11)
• Performance / scale — упёрлись в потолок текущей архитектуры, оптимизации больше не дают
• Compliance — регуляторное требование (data residency, encryption, audit)

НЕ мигрировать, если:

• Миграция как self-aggrandizement — «хочу пописать на Rust», нет measurable outcome
• «У всех в индустрии так» — fashion-driven, без реальной боли в текущем стеке
• Нет ресурса довести до конца — миграция на полпути хуже, чем не начатая (двойная инфра, двойной support)
• Нет владельца с авторитетом протолкнуть cutover — миграция застрянет в перепалке стейкхолдеров
• Текущий стек работает, и его боль ниже стоимости миграции — посчитай TCO до старта

7 фаз orchestrator'а

Phase 1: Discovery

Что: инвентаризация — точно понять, что именно в кодбазе использует {{from_stack}} и как. Без этого Phase 2 (риски) делается по фантазии.

Структура:

• Inventory grep + AST — все импорты / вызовы / упоминания {{from_stack}}: команды grep + ts-morph / ast-grep / sourcegraph. Цифры: сколько файлов, сколько вызовов, сколько уникальных API surface
• Зависимости — что подтягивается через {{from_stack}} (transitive). Часто пугает: формально мигрируем jQuery, а под капотом 30 плагинов на jQuery UI
• Usage patterns — 5-10 типичных способов, которыми кодбаза использует {{from_stack}}. Конкретные примеры из кода (snippet + путь), не «ну, в основном для DOM-манипуляций»
• Hotspots — где самая высокая концентрация {{from_stack}} (top-10 файлов по count). Эти файлы будут больно мигрировать
• Dead code — что из {{from_stack}}-usage уже мёртвое (никем не зовётся, флаги выключены). Это можно удалить ДО миграции, сократив scope

Output: ## Phase 1: Discovery — таблица inventory (файлов / вызовов / surface), список зависимостей, 5-10 типичных паттернов с code snippets, top-10 hotspots, dead code candidates. ~50-80 строк.

Phase 2: Risks

Что: что сломается при переходе. Каждый риск — конкретный, с likelihood × impact × mitigation.

Категории:

• API contract change — публичные эндпоинты / экспорты / CLI меняют поведение → ломают потребителей. Кто потребители? Знают ли они о миграции?
• Runtime characteristics — latency / memory / throughput / cold start у {{to_stack}} другие. Бывает в 2× быстрее, бывает в 2× медленнее под нагрузкой
• Security model — auth / authz / encryption / secrets handling работают иначе. Часто открывает дыры, которых не было в {{from_stack}}
• Transitive deps — плагины / экосистема {{from_stack}} не имеют аналогов в {{to_stack}} → собственная реализация или потеря фичи
• Data model / migrations — если затрагивает БД (schema, encoding, timezone, locale) — это отдельный класс рисков с risk of data loss
• Operational — observability / logs / metrics / alerts перенастраивать. Старые dashboards перестанут работать
• Compliance / audit — если регулируемая отрасль — pass-through audit для новой системы (отдельный проект на месяцы)

Output: ## Phase 2: Risks — risk matrix (Likelihood {Low/Med/High} × Impact {Low/Med/High} × Mitigation) для 10-15 рисков. Top-3 риска вынеси отдельным блоком с детальным mitigation. ~60-80 строк.

Phase 3: Strategy

Что: выбрать подход к миграции, явно, с обоснованием. Это не «как мы будем кодить» — это «как мы будем переключать трафик / state / users».

Опции:

• Big bang — все одновременно. Быстро, но риск катастрофы. Подходит только для маленьких систем или жёсткого deadline (vendor sunset через неделю)
• Strangler fig — новая система рядом со старой, постепенно «удушает» старую, route-by-route. Эталон для backend / API
• Branch by abstraction — внутри одного приложения вводится абстракция, под ней две реализации; переключаем флагом. Подходит для библиотек / framework migration
• Parallel run — обе системы получают трафик, результаты сравниваются (shadow traffic). Параноидально для финансовых / критичных систем
• Frontend rewrite-in-place — старые экраны постепенно заменяются новыми компонентами в том же роутере. Подходит для jQuery→React, AngularJS→Angular

Reversibility:

• Reversible — можно вернуться к {{from_stack}} за минуты (feature flag, route swap)
• Hard to reverse — миграция БД, изменение data format → нужна откатная миграция, заранее протестированная
• Irreversible — после cutover назад уже нельзя (например, мигрировали с проприетарного на open-source и закрыли лицензию) → cutover требует особенно осторожной подготовки

Phase boundaries: каким куском мигрируем за раз — по route / по сервису / по фиче. Не больше того, что команда может довести до прод за 1-2 недели.

Output: ## Phase 3: Strategy — выбранная стратегия (одна из пяти, с rationale), reversibility classification, phase boundaries (как режем работу на куски). 30-50 строк.

Phase 4: Plan

Что: превратить стратегию в последовательность фаз с milestones, dependency order и success criteria каждой фазы.

Структура:

• Phases — упорядоченный список (часто 4-10 sub-phases): «Phase A: Auth migration», «Phase B: API routes 1-10», «Phase C: Frontend chunk 1», и т.д.
• Dependency graph — что от чего зависит. Часто Auth должен быть первым. БД-миграции должны быть до cutover, не после
• Team allocation — кто на какой фазе. Не «миграцию делает Вася» — «Phase A: Вася + Маша; Phase B: Петя»
• Success criteria каждой фазы — измеримые: «100% requests на /api/users проходят через {{to_stack}} без regressions в error rate / p99 latency / data correctness»
• Rollback plan каждой фазы — конкретные шаги отката, протестированные в staging. Не «откатим коммит» — «выключить flag X, перезапустить сервис Y, проверить дашборд Z»
• Communication plan — кому и когда сообщаем (внутренние команды, клиенты, маркетинг, поддержка)

RACI matrix: Responsible / Accountable / Consulted / Informed для каждой фазы.

Output: ## Phase 4: Plan — список phases с milestones и dates, dependency graph (ASCII), team allocation, success criteria + rollback plan на фазу, RACI table. ~80-120 строк.

Phase 5: Execution

Что: playbook на каждую sub-phase. Это не «кодите как привыкли» — это что именно делается на каждой sub-phase, чтобы миграция не превратилась в free-form coding sprint.

Per-phase checklist:

• Code changes — конкретный список файлов / модулей. Атомарные коммиты, каждый ревьюабельный за <30 мин
• Tests — миграция = удвоенное покрытие тестами. Старая система покрыта тестами (regression baseline), новая покрыта параллельно. Перед cutover любой sub-phase — тесты прогоняются на обеих
• Monitoring — на проде включаем метрики и для старой, и для новой. Latency / error rate / throughput / business KPI бок-о-бок
• Observability — логи новой системы должны быть structured и сопоставимы со старой (correlation id сквозной)
• Feature parity verification — checklist фич, который сверяем до cutover. Не «вроде всё работает», а «проверили 47 пунктов, 3 не работают — это в Phase 6 cleanup»
• Comparison metrics — конкретные числа: «p50 latency старой / новой», «error rate старой / новой», «cost per request старой / новой». Если новая хуже — стоп, разбираться

Output: ## Phase 5: Execution — playbook (один шаблон, переиспользуется для каждой sub-phase) + конкретное наполнение для первой sub-phase как образец. 80-120 строк.

Phase 6: Cutover

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

Этапы:

• Dark launch — новая система запущена в проде, но трафик на неё не идёт (только shadow / synthetic). Цель: убедиться, что развёртывание не падает само по себе
• Canary — 1% → 5% → 25% → 50% → 100% реального трафика. На каждой ступени — пауза (минимум 1 час, для критичных систем — 24 часа), проверка метрик
• Rollback triggers — конкретные условия, при которых cutover откатывается автоматически или вручную: «error rate > X», «p99 latency > Y ms», «business KPI Z упал на N%»
• Comm to stakeholders — за 7 дней / за 1 день / в момент cutover / после cutover. Шаблоны сообщений
• Watch period — после 100% трафика на новой — 7-30 дней мониторинга, пока старая система ещё стоит. Никаких удалений до окончания watch
• Cutover checklist — пошагово, кто что нажимает, в каком порядке, что проверяет. На случай, если cutover делает не автор плана

Output: ## Phase 6: Cutover — cutover checklist (пронумерованные шаги с owner + verification), canary schedule, rollback playbook (что нажать, чтобы вернуться), comm templates. 60-100 строк.

Phase 7: Cleanup

Что: убрать старое. Без этой фазы миграция не закончена — кодбаза остаётся раздутой, и тех долг × 2.

Чек-лист:

• Удаление старого кода — все импорты / файлы / модули {{from_stack}} физически вынесены из репо. Grep подтверждает 0 occurrences
• Удаление переключателей — feature flags, A/B branches, дублирующая логика. Не «оставим на всякий случай» — на всякий случай ничего не остаётся вечно
• Удаление параллельной инфраструктуры — старая БД / старые сервисы / старые dashboards / старые алерты выключены, ресурсы освобождены (это часть cost savings, ради которых мигрировали)
• Документация обновлена — README, runbooks, onboarding-доки больше не упоминают {{from_stack}} как актуальный. Только в разделе «история» / changelog
• Lessons learned — postmortem: что пошло хорошо / что плохо / что бы сделали иначе. Это вход в будущие миграции
• Cost / benefit verification — посчитать фактические числа: реальная экономия / реальный perf gain. Сверить с обещаниями из мотивации (Phase «Когда применять»)

Output: ## Phase 7: Cleanup — checklist удаления (с owner + done-by-date), lessons doc draft, cost/benefit numbers vs обещанных в начале. 40-60 строк.

Контракт между фазами

Каждая фаза заканчивается checkpoint — компактным резюме, явно передаваемым в следующую. Без checkpoint'а нельзя переходить к следующей фазе.

В каждой фазе первая строка — входящий checkpoint от предыдущей. Так читатель видит цепочку, а не пересказы.

Формат вывода

В одном ответе — все 7 фаз последовательно с заголовками ## Phase N: Name. Каждая фаза = один минимально полный артефакт.

Длинный output (300-800 строк) ОК и ожидаем — миграция это серьёзный проект, и его план не помещается в один экран. Цель — план, который команда может взять и начать исполнять без дальнейших уточнений.

Закончи блоком ## Definition of Done — 7-item checklist («Phase N done because…») + явное указание, когда вся миграция Done (не cutover, а Phase 7 cleanup завершён + cost/benefit подтверждён).

Anti-patterns

• ❌ Skip Phase 1 (discovery) → «узнаём по ходу» → blockers всплывают на последнем этапе, когда переделать уже больно
• ❌ Big-bang без revert plan → инциденты на проде с невозможностью откатить → часы / дни downtime
• ❌ Параллельный код вечно → tech debt × 2, обе системы гниют, никто не знает, где источник истины
• ❌ Cleanup «потом» → переключатели остаются на годы, кодбаза в 2 раза больше, новые разработчики путаются
• ❌ Миграция без observability → не узнаёшь, что новая версия работает хуже, пока пользователи не начнут жаловаться
• ❌ Без freezing scope — миграция растягивается в редизайн («раз уж мы переписываем, давайте ещё и UX поменяем»)
• ❌ Без stakeholder comm — surprise downtime, surprise breakage у клиентов → потеря доверия дороже самой миграции
• ❌ Перепрыгивание Phase 2 → Phase 4 без Phase 3 (стратегия) → команда кодит, но непонятно, как переключать → cutover превращается в импровизацию
• ❌ Cutover без canary → 100% трафика на untested system → инцидент по полной программе
• ❌ Cleanup без verification of cost/benefit → нет доказательства, что миграция окупилась → следующая миграция в компании не будет одобрена