| 1 | # ADR 0001: Хранение гипотез отладки в одном JSON-файле |
| 2 | |
| 3 | **Статус:** Accepted |
| 4 | **Дата:** 2026-04-02 |
| 5 | |
| 6 | ## Связанные ADR |
| 7 | |
| 8 | | ADR | Роль | |
| 9 | |-----|------| |
| 10 | | [0003](0003-debug-ui-mode-separate-from-power.md) | вкладка **«Гипотезы»** в нижней панели Debug (не колонка чата). | |
| 11 | |
| 12 | --- |
| 13 | ## Контекст |
| 14 | |
| 15 | Нужно персистентное представление списка **гипотез** (текст, статус, идентификаторы) для сценария отладки, согласованного с Cursor-подобным workflow: гипотезы могут дополняться из IDE и при необходимости из MCP. Рассматривались потоковые форматы и человекочитаемые документы. |
| 16 | |
| 17 | ## Решение |
| 18 | |
| 19 | Использовать **один JSON-файл** на открытый workspace, с **корневым полем версии схемы** и массивом записей гипотез, например: |
| 20 | |
| 21 | - корень: `{ "version": 1, "hypotheses": [ … ] }`; |
| 22 | - у каждой записи — среди прочего поле **статуса**; миграции схемы — через инкремент `version`. |
| 23 | |
| 24 | **Статусы (смысл для UI и текста):** в продуктовом языке «**вынесена**» (гипотеза сформулирована, вердикта ещё нет) — это то же, что в данных **`open`** («открыта»). Отдельного четвёртого состояния «вынесена» не нужно: оно не дублирует `open`. Два остальных вердикта — **не подтвердилась** / **подтвердилась** (в коде enum можно назвать, например, `rejected` и `confirmed`; точные имена — при реализации, главное три семантических слота). |
| 25 | |
| 26 | Типичное расположение (как у прочих артефактов IDE): **`.cascade-ide/debug-hypotheses.json`** в корне workspace (точный путь фиксируется в коде/доке фичи). |
| 27 | |
| 28 | **Где смотреть список в UI:** в режиме Debug — **вкладка «Гипотезы»** в **нижней панели** (рядом с «Отладка»); подробности и запасной вариант — раздел **«Гипотезы: зона UI»** в [0003](0003-debug-ui-mode-separate-from-power.md). |
| 29 | |
| 30 | ## Последствия |
| 31 | |
| 32 | - Простая загрузка/сохранение целиком, обновление записи по `id` без построчного поиска в логе. |
| 33 | - При частых сохранениях перезаписывается весь файл — для ожидаемого числа гипотез (десятки–сотни) это приемлемо. |
| 34 | - Git-диффы читаемы как изменения в одном JSON; при желании позже можно добавить отдельный append-only лог событий без смены основного хранилища. |
| 35 | |
| 36 | ## Отклонённые альтернативы |
| 37 | |
| 38 | - **NDJSON / JSON Lines** как **основное** хранилище текущего списка — отклонено: смена статуса той же гипотезы усложняет модель (перезапись строки или индекс) при том же UI со списком; формат остаётся уместным для **опционального** журнала событий, не для единственного источника правды по состоянию. |
| 39 | - **Markdown / секции** — отложено: хуже для строгой машинной модели и автоматических обновлений из MCP без договорённости о разметке. |
| 40 | |