ADR 0001: Хранение гипотез отладки в одном JSON-файле¶

Статус: Accepted
Дата: 2026-04-02

Связанные ADR¶

ADR	Роль
0003	вкладка «Гипотезы» в нижней панели Debug (не колонка чата).

Контекст¶

Нужно персистентное представление списка гипотез (текст, статус, идентификаторы) для сценария отладки, согласованного с Cursor-подобным workflow: гипотезы могут дополняться из IDE и при необходимости из MCP. Рассматривались потоковые форматы и человекочитаемые документы.

Решение¶

Использовать один JSON-файл на открытый workspace, с корневым полем версии схемы и массивом записей гипотез, например:

корень: { "version": 1, "hypotheses": [ … ] };
у каждой записи — среди прочего поле статуса; миграции схемы — через инкремент version.

Статусы (смысл для UI и текста): в продуктовом языке «вынесена» (гипотеза сформулирована, вердикта ещё нет) — это то же, что в данных open («открыта»). Отдельного четвёртого состояния «вынесена» не нужно: оно не дублирует open. Два остальных вердикта — не подтвердилась / подтвердилась (в коде enum можно назвать, например, rejected и confirmed; точные имена — при реализации, главное три семантических слота).

Типичное расположение (как у прочих артефактов IDE): .cascade-ide/debug-hypotheses.json в корне workspace (точный путь фиксируется в коде/доке фичи).

Где смотреть список в UI: в режиме Debug — вкладка «Гипотезы» в нижней панели (рядом с «Отладка»); подробности и запасной вариант — раздел «Гипотезы: зона UI» в 0003.

Последствия¶

Простая загрузка/сохранение целиком, обновление записи по id без построчного поиска в логе.
При частых сохранениях перезаписывается весь файл — для ожидаемого числа гипотез (десятки–сотни) это приемлемо.
Git-диффы читаемы как изменения в одном JSON; при желании позже можно добавить отдельный append-only лог событий без смены основного хранилища.

Отклонённые альтернативы¶

NDJSON / JSON Lines как основное хранилище текущего списка — отклонено: смена статуса той же гипотезы усложняет модель (перезапись строки или индекс) при том же UI со списком; формат остаётся уместным для опционального журнала событий, не для единственного источника правды по состоянию.
Markdown / секции — отложено: хуже для строгой машинной модели и автоматических обновлений из MCP без договорённости о разметке.