ARCHITECTURE_CURRENT.md описує today, а не бажане завтра
`ARCHITECTURE_CURRENT.md` має відтворювати фактичну current-state architecture: підсистеми, потоки, межі, configuration і залежності, які підтверджені кодом та іншими джерелами. Це не місце для desired architecture, backlog або рекламного опису системи.
Якщо code і старі docs суперечать одне одному, code є authoritative для фактичної поведінки, але саму розбіжність потрібно зафіксувати. `ARCHITECTURE.md` не переписуйте автоматично: збережіть його як historical documentation і явно покажіть, що треба перевірити.
Три рівні впевненості
Не змішуйте ці рівні в одному реченні. Читач документа повинен одразу бачити, що є фактом, що виведено з непрямого сигналу, а що ще потребує ручного запуску або питання до owner.
| Мітка | Що означає | Приклад |
|---|---|---|
| Confirmed fact | є прямий evidence anchor | PaymentRetryService викликає конкретний retry client у source code |
| Assumption / inferred | логічне припущення, яке ще не підтверджене | ownership команди inferred з CODEOWNERS або Git history |
| Manual verification | потрібна перевірка поза static reading | timezone precedence або повний pause/resume flow у running environment |
Рекомендована структура current-state документа
- для кожної підсистеми вкажіть boundary, entry points, залежності та evidence;
- для кожного потоку опишіть input, рішення, side effects і output;
- inferred ownership позначайте явно як
inferred, а не як підтверджений факт; - додавайте дату або revision context, якщо behavior може змінюватися.
# ARCHITECTURE_CURRENT.md
## Що це за документ
## Підсистеми
## Критичні потоки
## Підтверджені факти
## Припущення
## Що потрібно перевірити вручну
## Розбіжності з історичною документацієюПовʼязані карти не дублюють одна одну
CODEBASE_INVENTORY.md відповідає на питання «де що лежить», MODULE_INVENTORY.md — «які межі та відповідальні області», CRITICAL_FLOWS.md — «як проходить runtime-сценарій», а ARCHITECTURE_CURRENT.md — «як ці частини фактично складаються в систему». RISK_MAP.md додає вимір рішення: що робити з невизначеністю та впливом.
`BEHAVIOR_INVENTORY.md` дивиться з боку бізнес-потоків і observable behavior. Він може посилатися на current architecture, але не повинен перетворюватися на список класів.
Документування без вигадування
- Зберіть evidence anchors із source, tests, configuration і logs.
- Запишіть підтверджені факти окремо від припущень.
- Винесіть code/docs discrepancies у власну секцію.
- Сформулюйте manual verification як конкретний сценарій або питання до owner.
- Попросіть reviewer перевірити, чи current-state опис не підмінено бажаним дизайном.
- Звʼяжіть документ із risk map і behavior inventory.
Канонічне джерело уроку · JavaRush
Відкрити матеріал JavaRush