Legacy — це невизначеність, а не просто вік
Legacy-система не визначається лише роком створення або старою технологією. Важливішими сигналами є слабко задокументована поведінка, незрозуміле ownership і висока ціна помилки. Навіть відносно новий модуль стає legacy-зоною, якщо команда не може впевнено пояснити його контракти та наслідки змін.
Мета discovery — не знайти винного і не довести, що код треба переписати. Потрібно зібрати достатньо evidence, щоб розділити підтверджені факти, unknowns і області, де зміна потребує додаткового контролю.
- weakly documented behavior: реальна поведінка відома переважно з коду або усних пояснень;
- unclear ownership: незрозуміло, хто підтвердить business rule або прийме ризик;
- high failure cost: помилка впливає на гроші, доступ, дані або критичний операційний процес.
Що потрібно знайти до будь-якої зміни
Перевіряйте не тільки source code. Tests показують закріплені очікування, configuration — умови запуску, logs — фактичні runtime-сигнали, а Git history — зони частих змін і попередні рішення. Жоден із цих шарів не є достатнім сам по собі.
| Область discovery | Питання | Можливе evidence |
|---|---|---|
| Підсистеми | Які модулі беруть участь у потрібному сценарії? | каталоги, entry points, imports, service boundaries |
| Critical runtime flows | Який шлях проходять input, рішення та output? | код, логи, integration tests, configuration |
| Change-risk areas | Де мала зміна може мати широкий або дорогий вплив? | shared utilities, retries, flags, dates, money paths |
| Existing coverage | Які сценарії вже перевіряються і на якому рівні? | unit/integration tests, coverage report, CI checks |
| Unknowns | Що залишається непідтвердженим? | відсутній owner, суперечливі docs, manual verification |
Read-only discovery з evidence anchors
- Зафіксуйте scope і заборону редагування в discovery-note.
- Побудуйте список ключових підсистем та entry points.
- Простежте critical flows через code, tests, configuration і logs.
- Перевірте Git history, ownership та наявні coverage signals.
- Для кожного матеріального твердження додайте evidence anchor: шлях, символ, команду, log-сигнал або commit.
- Винесіть непідтверджені питання в окремий список unknowns.
- Лише після discovery підготуйте draft
RISK_MAP.md; код не змінюйте.
Фокус для навчального legacy-сценарію
Як приклад для дослідження можна взяти `mrr-engine`, `payments`, retry logic, configuration і feature flags. Окремо перевірте `legacy/`, pause/resume та timezone calculations. Повідомлена 8% MRR discrepancy є input для розслідування, але не доведеним root cause: її потрібно привʼязати до конкретних даних, коду або log evidence.
Discovery-note зручно вести таблицею: «Підсистема», «Що підтверджено», «Які тести є», «Що неясно», «Чому це ризик». У кінці додайте перелік джерел і рішення, які ще потребують owner або ручної перевірки.
Вихід discovery
- CODEBASE_INVENTORY.md дає навігаційну карту, а MODULE_INVENTORY.md — деталізацію меж і ownership;
- CRITICAL_FLOWS.md показує runtime-потоки, які не можна випадково втратити;
- discovery-note відділяє facts, assumptions та unknowns;
- draft RISK_MAP.md перетворює зібрані сигнали на наступні рішення;
- жоден висновок не називайте підтвердженим без anchor на evidence.
Канонічне джерело уроку · JavaRush
Відкрити матеріал JavaRush