Документ how it works today для legacy

1. Назначение документа «как оно работает сегодня»

Когда вы работаете с legacy, довольно быстро выясняется неприятная, но полезная правда: кодовая база почти всегда знает о себе больше, чем документация. А документация знает что-то — но про более молодую и оптимистичную версию системы. Поэтому документ how it works today нужен не как украшение репозитория, а как карта местности перед входом в туман.

Главная идея очень простая: вы описываете не то, как система должна работать, а то, как она работает сейчас. Звучит почти обидно просто, но именно здесь на практике чаще всего и начинается путаница. Видите странное поведение, вспоминаете красивый ARCHITECTURE.md — и рука тянется написать «ну очевидно, пауза подписки должна исключать её из MRR». Нет. Если в коде пауза остаётся в active MRR, фиксируете именно это.

У legacy-документации очень приземлённая задача: уменьшить стоимость следующего шага. Новый инженер быстрее понимает систему, ревьюер видит слабые места в потоке денег и данных, а тот, кто полезет менять mrr-engine, видит: какие правила доказаны кодом, какие предполагаются, а какие надо проверять руками. Не архитектурная проза — слой безопасности перед изменениями.

На CashFlow Dashboard это особенно заметно. Старый BILLING_RULES.md говорит, что paused subscription не считается в активном MRR. Но если MrrFormulas.java делает обратное, документ лоялен к коду, а не к мечте о прекрасном прошлом. Legacy не терпит романтизма. Оно предпочитает доказательства.

2. Факты, предположения и ручная проверка

Одна из самых полезных привычек в работе с legacy — перестать смешивать доказанное и предполагаемое в один гладкий текст. Когда всё написано одним ровным абзацем, документ выглядит солидно, а доверять ему нельзя. Поэтому хороший current-state документ раскладывает выводы на три корзины: подтверждённые факты, предположения и то, что нужно проверить вручную.

Подтверждённый факт — это утверждение, у которого есть evidence anchor. Не «Claude уверен», не «похоже по названию метода», а конкретный файл, функция, тест, конфиг, лог или команда. Снимок MRR запускается в jobs/MrrSnapshotJob.java; paused subscription остаётся в active MRR по ветке в mrr-engine/MrrFormulas.java. Можете показать пальцем на код — это факт.

Предположение — это не ошибка документации, а честная фиксация границы знания. После успешного retry подписка, вероятно, считается непрерывной, но теста нет, и в логах вы такого сценария не встречали. Значит, не факт. Не маскируйте это словом «скорее всего» — вынесите в отдельный раздел и назовите предположением, требующим проверки.

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

Наглядно поток выглядит так:

flowchart TD
    A[Код, тесты, конфиги, логи] --> B[Черновые выводы Claude]
    B --> C[Проверка по evidence]
    C --> D[Подтверждённые факты]
    C --> E[Предположения]
    C --> F[Проверить вручную]
    D --> G[ARCHITECTURE_CURRENT.md]
    E --> G
    F --> G

А короткий фрагмент документа — так:

## Подтверждённые факты
- Ежедневный снимок MRR запускается по расписанию `02:00 UTC`
  (`jobs/MrrSnapshotJob.java:21`).
- Пауза подписки не исключает её из active MRR
  (`mrr-engine/MrrFormulas.java:88`).

## Предположения
- После успешного retry подписка считается непрерывной,
  но отдельного теста на это нет.

## Что нужно проверить вручную
- Поведение расчёта на границе месяца для подписки в статусе `paused`.

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

3. Claude Code как ассистент по извлечению знаний

Здесь очень легко свернуть не туда. Claude Code быстро собирает черновики, находит файлы, суммирует поведение. Но дайте ему свободу «объясни архитектуру» — и он с удовольствием сделает текст красивым раньше, чем точным. В legacy-документации Claude Code — ассистент по knowledge extraction, а не автор фантастического романа по мотивам вашего репозитория.

Практически это означает две вещи. Первое: discovery и документирование ведёте в логике только чтения — plan mode, поиск, Git history, анализ тестов и логов. Второе: сразу задаёте строгий формат вывода. Claude работает лучше, когда вы не просите «описать систему», а называете нужные секции и способ маркировать выводы.

Рабочий запрос под такой режим:

Собери current-state note для модуля `mrr-engine`.
Для каждого важного утверждения укажи файл и строку.
Раздели ответ на:
1. Подтверждённые факты
2. Предположения
3. Что нужно проверить вручную
Не предлагай изменений в коде и не описывай желаемое поведение.

Такой формат одновременно ускоряет сбор черновика и не даёт Claude незаметно подменить текущее поведение желаемым. Особенно важно в CashFlow Dashboard, где старые документы уже конфликтуют с кодом. Не запретили описывать «как должно быть» — Claude начнёт чинить реальность прямо в тексте. А нам нужен не ремонт, а честный снимок.

Если у вас уже есть Workflow Kit с read-only агентом вроде discovery-explorer или аккуратным documenter — отлично. Но и в этом случае принцип не меняется: агент помогает собрать материал, а не утверждает его за вас. Под каждой значимой фразой всё равно код, тест, конфиг или лог. Иначе это просто красиво оформленная гипотеза.

4. Артефакты, которые действительно нужны

Очень хочется сложить всё в один большой ARCHITECTURE.md на двенадцать экранов, с тремя таблицами, двумя диаграммами и печальным лицом того, кто будет это читать. Лучше так не делать. К этому моменту у вас уже есть широкий CODEBASE_INVENTORY.md из первого знакомства с репозиторием, discovery-note из текущего входа в legacy-сервис и короткий signal log с technical signals. Последние два — сырой рабочий слой. Из него собираете устойчивый current-state слой, на который обопрутся RISK_MAP.md и BEHAVIOR_INVENTORY.md.

CODEBASE_INVENTORY.md

ARCHITECTURE_CURRENT.md

MODULE_INVENTORY.md, CRITICAL_FLOWS.md

RISK_MAP.md

BEHAVIOR_INVENTORY.md

Хитрость в том, что current-state слой здесь один — основной ARCHITECTURE_CURRENT.md. MODULE_INVENTORY.md и CRITICAL_FLOWS.md не обязаны жить как две независимые вселенные. Это просто удобные разрезы того же слоя, когда в одном файле стало тесно.

Кусок module inventory может выглядеть так:

| Модуль | Назначение сегодня | Владелец | Evidence |
|---|---|---|---|
| `subscriptions` | жизненный цикл: trial → active → paused → cancelled | inferred: unclear | `SubscriptionService.java` |
| `mrr-engine` | ежедневный расчёт MRR/ARR | inferred: high churn | `MrrCalculator.java`, `MrrFormulas.java` |
| `payments` | PSP, retry, audit | platform team | `PaymentService.java`, `PaymentRetryService.java` |

Обратите внимание на поле владельца. Если ownership вы вывели из Git history, старых комментариев и привычки одного разработчика чинить этот модуль в три часа ночи, так и пишите: inferred. В legacy очень полезно не притворяться, будто вы знаете больше, чем знаете.

5. Старый ARCHITECTURE.md — оставляем как историю

Тут почти всегда возникает соблазн «исправить документацию». Звучит благородно, но чаще всего это плохое решение. Старый ARCHITECTURE.md — исторический артефакт. Он может быть устаревшим, неточным, местами даже наивным, но всё равно фиксирует, как команда когда-то думала о системе. Удалять его или переписывать поверх — всё равно что стирать старый чертёж и делать вид, будто здание всегда строилось по новой версии.

Гораздо полезнее сохранить старый документ как исторический источник, а рядом создать current-state версию. Название файла может отличаться: ARCHITECTURE_CURRENT.md, ARCHITECTURE.today.md, ARCHITECTURE_NOW.md. Имя вторично. Принцип первичен: вы не затираете историю, а добавляете честный снимок текущего состояния.

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

Например, так:

## Расхождения с исторической документацией
- `ARCHITECTURE.md`: paused subscriptions не входят в active MRR.
- Текущее поведение в коде: paused subscriptions остаются в active MRR
  (`mrr-engine/MrrFormulas.java:88`).
- Статус: факт подтверждён кодом, правило в документации устарело.

Такой раздел делает две полезные вещи. Во-первых, он защищает следующего инженера от ложного доверия к старому документу. Во-вторых, убирает вечную командную драму «но ведь в доке написано иначе». Спорить, кто прав, больше не нужно: док говорит одно, код делает другое, и это честно задокументировано.

6. Черновик current-state для CashFlow Dashboard

Когда у вас уже есть discovery-находки, debt-сигналы и первые evidence anchors, собрать черновик ARCHITECTURE_CURRENT.md становится намного проще. Вы не придумываете архитектуру заново — переводите накопленные факты в более стабильную форму. И да, именно здесь становится видно, насколько полезно было не смешивать всё в кучу на прошлых шагах.

Для CashFlow Dashboard начните с такой структуры:

# ARCHITECTURE_CURRENT.md

## Что это за документ
Краткое описание: фиксирует текущее поведение системы, а не целевую архитектуру.

## Подсистемы
- subscriptions
- billing
- payments
- refunds
- mrr-engine
- reporting

## Критические потоки
- расчёт MRR
- retry платежа
- partial refund
- scheduled exports

## Подтверждённые факты

## Предположения

## Что нужно проверить вручную

## Расхождения с исторической документацией

Если current-state слой спокойно помещается в один файл, MODULE_INVENTORY.md и CRITICAL_FLOWS.md остаются разделами здесь же. Отдельными файлами — только когда это действительно упрощает чтение.

Дальше вы уже наполняете его содержанием из конкретных модулей. По mrr-engine можно написать короткий current-state блок, не впадая в эпос:

## mrr-engine — как работает сегодня

### Подтверждённые факты
- Ежедневный расчёт запускается из `jobs/MrrSnapshotJob.java:21`.
- Основной вход в вычисления — `mrr-engine/MrrCalculator.java:42`.
- Пауза подписки не исключает её из active MRR
  (`mrr-engine/MrrFormulas.java:88`).

### Предположения
- После успешного retry подписка остаётся непрерывной по MRR,
  но отдельного теста на это не найдено.

### Что нужно проверить вручную
- Поведение расчёта на границе месяца для paused subscription.
- Поведение после upgrade в день биллинга.

Хороший знак, если этот документ выглядит чуть менее красиво, чем маркетинговая презентация, и чуть полезнее, чем общая диаграмма «у нас есть backend и database». Legacy current-state должен быть приземлённым. Его сила не в стиле, а в плотности правды на квадратный абзац.

И здесь появляется, пожалуй, самый приятный эффект всей лекции. Как только есть честный current-state по mrr-engine, payments и subscriptions, команда перестаёт спорить с системой на уровне ощущений. У CashFlow Dashboard по-прежнему могут быть странные правила, устаревшие зависимости и нервный характер — но это уже не смутное коллективное чувство, а привязанная к коду реальность, с которой работают дальше без археологии на каждом шаге.

1

Задача

Claude code, 26 уровень, 2 лекция

Недоступна

Current-state doc через команды внутри Claude CLI

Current-state doc через команды внутри Claude CLI

Открыть

1

Задача

Claude code, 26 уровень, 2 лекция

Недоступна

Документ `ARCHITECTURE_CURRENT.md` по фактическому поведению

Документ `ARCHITECTURE_CURRENT.md` по фактическому поведению

Открыть