Transition guide — миграция на RENAR без big-bang

Команды редко начинают с чистого листа. Эта глава — про то, как перевести существующий проект с ручного workflow ТЗ → код на RENAR постепенно, уровень за уровнем, без остановки разработки. Каждый уровень даёт конкретные benefits; команда выбирает, до какого RENAR-N доходить исходя из реальной ценности, не из стремления к «полному соответствию».

Предпосылки: RENAR Core, standard/12-maturity-model (закрытый список уровней RENAR-1..RENAR-5), guide/07-failure-modes — для понимания, чего избегать при миграции.

1. Assessment: где команда сейчас

Прежде чем мигрировать, оцените текущее состояние. Чек-лист «pre-RENAR»:

ПризнакPre-RENARRENAR-1 минимум
ТЗ существует как артефактВ чате / Google Doc / NotionЗафиксировано в substrate как файл
Кто-то ведёт требованияТолько в трекере (Jira / Linear)В substrate как BR / SR / ADAPT
Откуда взялось требованиеПо памяти / переспрашиваемЛюбой может найти источник в substrate
Изменения требованийУстно на дейлиЧерез явный change-set (delta-ТЗ)
ТестыВ коде, привязки к требованиям нетTC как артефакты или хотя бы в коде с упоминанием SR-ID

Если 3+ строк в колонке «Pre-RENAR» — команда до RENAR-1. Это нормальная стартовая точка для большинства проектов.

1.1 Сигналы готовности

Команда готова к миграции, если:

  • Болит, что требования теряются между чатами / тикетами / документами.
  • Disputed acceptances случаются регулярно — «мы не это просили».
  • При onboarding нового инженера месяцы уходят на восстановление контекста.
  • Используется AI для генерации требований / кода, но нет систематической проверки.

Если ничего из этого не болит — RENAR может быть преждевременной оптимизацией. См. §8 «когда не нужен».

2. Этап 1 — войти в RENAR-1 (Ad-hoc)

Цель уровня: требования живут в substrate, не в чате; для каждого ТЗ есть ADAPT.

Типичная длительность: 1-2 недели.

2.1 Что добавляется

  1. Заводится substrate (директория <project>.req/ в репозитории, или Raven workspace, или другое — выбор substrate-agnostic; см. capabilities V1-V6).
  2. Существующее ТЗ копируется в substrate как immutable артефакт (с датой и подписями).
  3. Для каждого ТЗ создаётся ADAPT — bridge artefact с forward (как мы поняли) + backward (вопросы клиенту).
  4. Новые требования заносятся как BR / SR файлы в substrate, не только в трекер.

2.2 Что НЕ требуется на этом этапе

  • Стандартизированный frontmatter (минимум — id + title).
  • Lifecycle статусы (draft/approved/…) — артефакты могут жить без явных переходов.
  • TC как отдельные артефакты.
  • Substrate hooks.
  • Substrate-нативный COVERAGE.

2.3 Типичные блокеры

  • «У нас уже есть тикеты в Jira» — оставьте. RENAR-1 не требует миграции; tracker и substrate могут сосуществовать. Главное — substrate теперь источник истины для новых требований.
  • «ADAPT — лишняя работа» — на одно ТЗ ADAPT занимает 1-2 часа. Это окупается на первом же спорном acceptance.
  • «Где хранить?» — substrate-agnostic выбор. См. guide/03-tool-guide-git или guide/04-tool-guide-raven.

2.4 Когда переходить на RENAR-2

Когда новые требования перестали уходить в чаты и начали стабильно появляться в substrate. Это занимает 4-6 спринтов привычки.

3. Этап 2 — перейти на RENAR-2 (Documented)

Цель уровня: структура и frontmatter; delta-ТЗ как явный change-set.

Типичная длительность: 2-4 недели после RENAR-1.

3.1 Что добавляется

  1. Каждый BR / SR получает frontmatter с обязательными полями (см. reference/02-schemas).
  2. Папки структурируются: br/, sr/, adapt/, dpia/, …
  3. Изменения требований — только через delta-ТЗ (новый immutable артефакт), не через прямое редактирование.
  4. ТЗ зафиксировано как immutable (изменения только через delta-ТЗ).

3.2 Pattern: легализация существующих требований

Старые требования (которые уже были в substrate с RENAR-1) — пройти ревью и проставить frontmatter «как есть» без пересмотра содержания. Это legalization, не rewrite:

---
id: BR-12
title: "Регистрация сотрудника через корпоративный email"
status: approved          # уже работает в проде
created-at: "2025-12-01"  # ретроактивно
priority: must            # ретроактивная оценка
legacy: true              # маркер: требование не проходило ADAPT с нуля
---

Поле legacy: true опционально, но рекомендовано — отличает «исторические» требования от новых, которые с самого начала прошли весь RENAR-пайплайн.

3.3 Типичные блокеры

  • «Frontmatter на 100 требований — это месяц» — да. Делайте в фоне, по 10-15 требований / неделю; новые требования сразу с frontmatter.
  • «Delta-ТЗ замедляет» — на первых неделях да. После 2-3 итераций обычно становится быстрее, чем «давай просто поменяем».
  • «Не понимаем, какой priority ставить ретроактивно» — оставьте priority: should для всего legacy; явно must ставится только при подтверждении со stakeholder.

3.4 Когда переходить на RENAR-3

Когда frontmatter валиден для 80%+ артефактов и команда привыкла к delta-ТЗ.

4. Этап 3 — перейти на RENAR-3 (Tracked)

Цель уровня: автоматическая валидация + lifecycle enforcement + TC покрытие для priority=must.

Типичная длительность: 4-8 недель после RENAR-2.

4.1 Что добавляется

  1. Substrate hooks валидируют frontmatter по schema на каждое изменение. Невалидные — блок integration.
  2. Lifecycle статусы используются реально: каждый артефакт в одном из закрытых состояний (draft / approved / verified / deprecated / obsolete).
  3. TC создаются для всех priority=must BR / SR / SPEC.
  4. Substrate-нативный COVERAGE report auto-generated на каждый promote-transition.
  5. Reference-validation hook: создание BR / SR с ссылкой на ADAPT в статусе ниже approved — блок.
  6. Реализация ссылается на BR / SR / SPEC с pinned verifies[].version.

4.2 Pattern: TC backfill

Для всех priority=must требований без TC:

  1. Отсортировать по «частоте упоминания в incident reports» — где TC даст максимум value.
  2. Покрывать по 3-5 требований / спринт, не пытаясь backfill сразу всё.
  3. TC создаются как substrate-артефакты с verified-by cross-link.

4.3 Типичные блокеры

  • «Старые требования упрямо не приводятся к schema» — оставьте их в legacy-папке; новые сразу schema-valid. Substrate hook применяется только к новым / изменяемым артефактам.
  • «Hooks замедляют PR cycle» — измерьте: если > 30s — оптимизируйте hooks (parallelization, caching); не «отключить».
  • «Команда обходит hooks через --no-verify» — это organizational failure pattern; root cause — hooks слишком медленные / шумные. Чините, не запрещайте.

4.4 Когда переходить на RENAR-4

Когда COVERAGE для priority=must = 100%, frontmatter валиден везде, lifecycle действительно работает.

5. Этап 4 — перейти на RENAR-4 (Verified)

Цель уровня: все approved артефакты имеют passing TC; QG-2 enforced substrate-нативно; pos/neg парность; ai-provenance.

Типичная длительность: 6-12 недель после RENAR-3.

5.1 Что добавляется

  1. 100% approved артефактов имеют verified-by ссылку на ≥ 1 TC.
  2. Pos/neg парность для каждого нормативного утверждения.
  3. QG-2 enforced substrate hooks: promote в verified блокируется без всех passing TC на текущей requirement-version.
  4. Все TC автоматизированы или явно manual-pending с deadline.
  5. Для tc-type: ux — VLM-judge isolation.
  6. Для tc-type: eval — judge-модель ≠ модель реализации.
  7. ai-provenance для AI-сгенерированных артефактов: минимум generated-by + generated-at.
  8. Source citation — каждое нормативное утверждение имеет pointer на источник в ТЗ или ADAPT.
  9. Reconciliation hook запускается substrate-нативно ≥ еженедельно.
  10. Spot-check 5 случайных passing TC раз в спринт.

5.2 Pattern: phased coverage

Достижение 100% verified-by покрытия — не одним PR. Подход:

  1. Сначала pos-only TC для всех priority=must (бенефит — быстрая обратная связь).
  2. Затем neg-TC pairs (бенефит — отлов test-fitting drift).
  3. Затем tc-type extensions (ux / eval / contract / security) по мере необходимости.

5.3 Типичные блокеры

  • «Изоляция judge-модели дорого» — это правда. Но это структурный rate limit на AIR-06 test-fitting drift — нельзя обойти без потери verification integrity.
  • «Source citation замедляет авторов» — автоматизируйте: AI-генератор должен сразу выдавать citation; ручная авторизация — только для legacy backfill.
  • «Reconciliation findings заваливают команду» — tunable thresholds; начинайте с conservative defaults, постепенно ослабляйте.

5.4 Когда переходить на RENAR-5

Когда RENAR-4 стабильно работает 2-3 квартала, метрики стабильны, команда не «горит» от reconciliation noise.

6. Этап 5 — перейти на RENAR-5 (Optimized)

Цель уровня: adversarial review как gate; multi-model agreement для priority=must; cost/latency budgets; knowledge graph как primary search; continuous evaluation для AI-критических компонентов.

Типичная длительность: 12+ недель после стабильного RENAR-4.

6.1 Что добавляется

  1. Adversarial critic — обязательный gate для draft → approved. Critic — модель, отличная от модели генерации.
  2. Multi-model agreement для priority=must: артефакт генерируется ≥ 2 моделями; расхождения помечены и обязательны к разбору.
  3. Cost / latency budget per artifact; превышение → автоматическая декомпозиция.
  4. Knowledge graph как primary search для AI-агентов.
  5. Continuous evaluation для SPEC-AI.
  6. Метрика Hallucination Rate < 1%.
  7. Метрика Multi-model Disagreement Rate отслеживается.
  8. Возврат улучшений шаблонов в requirements-library — стандартная практика.

6.2 Когда RENAR-5 нужен

  • Регулируемые отрасли (финтех, healthcare, AI-системы high-risk per AI Act).
  • Когда продукт критически зависит от качества AI-генерации (генеративные продукты).
  • Когда есть бюджет на continuous evaluation infrastructure.

Многие проекты могут остановиться на RENAR-4 — это conformant уровень. RENAR-5 не «лучше», а «дороже + строже». Выбирайте по реальной потребности.

7. Migration legacy requirements

Существующие тысячи требований в Jira / Confluence — как втягивать?

7.1 Стратегия не-миграции

Если legacy требования не активно меняются — не мигрируйте. RENAR применяется только к новым требованиям и активно изменяемым. Legacy остаётся в исходном месте как read-only «исторический контекст».

7.2 Стратегия выборочной миграции

Для legacy, которые активно меняются:

  1. На момент первого change — затянуть в substrate как BR/SR с legacy: true маркером и минимальным frontmatter.
  2. Применить change как delta-ТЗ.
  3. Через 1-2 итерации требование «созревает» — становится full-RENAR (без legacy маркера, с полным frontmatter и TC).

7.3 Стратегия bulk-import

Когда нужно мигрировать сразу > 100 требований (например, при organizational reorganization):

  1. Скриптовая выгрузка из tracker → frontmatter скелет (id, title, минимум).
  2. Все импортированные требования — legacy: true + status: approved (как есть в проде).
  3. Backfill TC и full frontmatter — спринт за спринтом, не блокируя current work.

8. Когда RENAR НЕ нужен

RENAR — overhead. Не применяйте к:

  • One-off скриптам и прототипам — не доходят до production, или становятся production только через rewrite.
  • Очень маленьким командам (1-2 человека) — overhead substrate-управления может превышать benefit.
  • Проектам без AI-генерации требований / тестов — главная ценность RENAR (защита от AI-specific failure modes) теряется.
  • Краткосрочным экспериментам (≤ 1 спринт) — не успеете окупить ADAPT-setup.

Минимальный порог окупаемости: проект с ≥ 3 итерациями требований, ≥ 2 разработчиков, использует AI где-либо в pipeline (генерация требований / кода / тестов / документации).

9. Migration anti-patterns

Чего избегать:

9.1 Big-bang migration

Симптом: Команда останавливает разработку на 2 спринта чтобы «перейти на RENAR». Через 2 спринта получают burnout и брошенную миграцию.

Vместо: Гибридный режим. Новые требования сразу в RENAR, старые — по мере касания. Долго, но устойчиво.

9.2 Level-skipping

Симптом: «Давайте сразу на RENAR-4». Команда пропускает RENAR-2/3, ставит full hooks + ai-provenance + adversarial critic, но frontmatter не валиден и lifecycle хаотичен.

Vместо: Уровни идут по порядку. RENAR-4 без RENAR-3 базы — не работает.

9.3 Perfect-frontmatter paralysis

Симптом: Команда тратит недели на полирование одного frontmatter — «а правильно ли я выбрал priority?» Реальная работа стоит.

Vместо: Frontmatter — «достаточно хорошо». Ошибки правятся в delta-ТЗ. Главное — что-то быть в substrate, а не вылизанность.

9.4 Partial-substrate adoption

Симптом: Половина требований в substrate, половина — всё ещё в Jira. Никто не знает, где источник истины.

Vместо: Single source of truth должен быть сразу. Если нельзя перенести всё — перенесите только новые, явно объявите substrate владельцем «всего нового».

9.5 Tooling-first approach

Симптом: Команда полгода пишет внутренние tooling вокруг RENAR (свой validator / своя CI / своя UI), не используя сам стандарт.

Vместо: Сначала практика на минимальном substrate (даже плоская папка с markdown). Tooling — когда становится больно вручную.

10. Cross-references

  • standard/12-maturity-model — нормативные определения RENAR-1..RENAR-5 уровней (closed list).
  • 00-quickstart — 30-минутный sample для маленького проекта.
  • 01-walkthrough — полный example на одном проекте.
  • 07-failure-modes — что может пойти не так при миграции; organizational failure patterns §4.
  • reference/02-schemas — frontmatter schemas, обязательные для RENAR-2+.
  • 03-tool-guide-git — substrate-specific guide для git.
  • 04-tool-guide-raven — substrate-specific guide для Raven CouchDB.

11. Open questions

  • Migration timeline для крупных команд (50+ инженеров): какие специфичные паттерны? Сейчас гайд написан под teams 5-15.
  • Tooling support для legacy backfill: нужен ли normative «бypass» для bulk-import (skip frontmatter validation на initial import)?
  • Когда «откатываться» назад с уровня (например, RENAR-3 → RENAR-2) — допустимо ли, и как фиксировать?
  • Cross-org migration: разные команды на разных уровнях RENAR одновременно — как координировать?