Руководство SENAR: Внедрение SENAR в устаревших кодовых базах

Большинство софта — не greenfield. У вас 200 000 строк недокументированного кода, а правило 9.11 говорит: «документация, достаточная для понимания назначения модуля AI». Вы не станете документировать всё до начала работы. Вот как внедрить SENAR поэтапно.

Принцип: следующая задача, а не полная модернизация

Не нужно «сенарить всё». Начните со следующей задачи. Задача затрагивает модуль — задокументируйте его. Следующая задача затрагивает другой модуль — задокументируйте тот. Со временем фронт документации продвигается вместе с реальной работой.

Чего НЕ делать: Не устраивайте «спринт документации» на 3 недели. Он произведёт документацию, которую никто не читает. Документация в отрыве от реализации устаревает ещё до завершения.

Фаза 1: Начать с привычек (День 1)

Внедрите 6 привычек быстрого старта немедленно. Они не требуют подготовки кодовой базы:

  1. Писать цель + критерии приёмки перед каждой задачей для AI (даже в legacy-коде)
  2. Устанавливать границы области действия («изменять ТОЛЬКО этот файл, не рефакторить модуль»)
  3. Проверять результат по критериям приёмки, а не по интуиции
  4. Документировать тупики (особенно важно в legacy — «пробовали X, не получилось из-за Y»)
  5. Запускать тесты
  6. Фиксировать знания

Границы области действия (привычка 2) критичны для legacy: AI-агенты попытаются «улучшить» окружающий код, если не оградить их.

Фаза 2: Документировать при контакте (Неделя 1+)

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

"""
Module: user_auth
Purpose: Handles login, registration, and session management.
Public API:
  - login(email, password) -> Session
  - register(email, password, name) -> User
  - verify_session(token) -> User | None
Dependencies: database (PostgreSQL), redis (session store)
Boundaries: Does NOT handle OAuth (see oauth_provider module).
"""

На это уходит 5 минут на модуль. Этого достаточно для выполнения правила 9.11 на уровне SENAR Core. С этого момента задачи AI, затрагивающие этот модуль, требуют меньше явного контекста в цели задачи — docstring обеспечивает его.

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

Фаза 3: Построение базы знаний из племенного знания (Неделя 2+)

В legacy-кодовых базах есть «племенное знание» — то, что люди знают, но не записали. По мере столкновения с ним при работе по SENAR:

  • Тупик (Dead End): «Нельзя использовать async в модуле авторизации, потому что он зависит от цепочки синхронного middleware» — задокументировать
  • Подводный камень (Gotcha): «Поле статуса заказа использует целые числа 1–7, а не enum — legacy-миграция так и не была проведена» — задокументировать
  • Решение (Decision): «Мы используем сырой SQL вместо ORM в модуле отчётов из-за сложных JOIN-запросов» — задокументировать

Всё это становится записями базы знаний для будущих AI-сессий. Каждый задокументированный подводный камень предотвращает один будущий пропущенный дефект ценой $105.

Фаза 4: Связи требований для новой работы (Месяц 1+)

Новые фичи на legacy-кодовых базах часто лишены чётких требований — кто-то говорит «почини ту штуку», и вы разбираетесь. Исследование по SENAR (раздел 6.1) помогает:

  1. Начните исследование (ограниченное по времени расследование)
  2. Когда поймёте, что нужно сделать, — создайте задачу с целью + критериями приёмки
  3. Свяжите задачу с историей или BR — даже если BR звучит как «снизить количество обращений в поддержку по теме X»

Для исправления ошибок в legacy-коде:

  • BR: исходная бизнес-потребность, которую нарушает баг (например, «пользователи должны иметь возможность сбрасывать пароли»)
  • TR: конкретное исправление с критериями приёмки (например, «POST /reset-password возвращает 200 для несуществующих email — без утечки информации»)

Фаза 5: Шлюзы качества для legacy (Месяц 2+)

QG-0 работает сразу на legacy: каждая задача имеет цель + критерии приёмки перед началом.

QG-2 может потребовать адаптации:

  • «CI проходит» требует наличия CI. Если его нет — добавьте минимальный CI как единовременную инвестицию.
  • «Тесты проходят» требует наличия тестов. Для непротестированных legacy-модулей минимум: добавить тесты для кода, который вы меняете. Не тестируйте то, что не трогаете.
  • «Типы чисты» может не применяться к динамически типизированному legacy. Используйте то, что доступно (mypy для Python, TypeScript strict для миграций с JS).

QG-3 и QG-4 — это уровни Командная+ и Корпоративная — отложите до тех пор, пока SENAR Core не будет твёрдо отработан.

Что вы получаете

После 3 месяцев SENAR Core на legacy-кодовой базе:

  • Фронт документации продвигается вместе с реальной работой (не гниёт в вики)
  • База знаний подводных камней, предотвращающая повторные сбои
  • Измеримый FPSR, показывающий, улучшается ли качество контекста
  • Тупики, экономящие часы за сессию
  • Никакого «большого взрыва» документации, никакого нарушения процессов

Антипаттерн: Спринт документации

Проблема: Руководитель говорит: «Давайте потратим 2 недели на документирование всего, прежде чем включать AI.» Почему не работает: Документация без контекста реализации абстрактна и мгновенно устаревает. Человек, документирующий модуль X, не работал с ним 6 месяцев — он упустит подводные камни. Подход SENAR: Документировать при контакте. Тот, кто документирует модуль X, — тот же человек, который прямо сейчас пишет задачу в этом модуле. Он знает ровно то, что нужно знать AI, потому что только что это выяснил.

← Инженерия требований Практический пример →