# 2. Канон документов проекта (2026-08-03) ## Что было Измерено по обоим проектам: - **«Почему» не теряется — оно не находится.** `design.md` пишется почти всегда (jellybit 39 из 43 архивных change, healthlog 9 из 9 — ≈285 КБ за две недели) и имеет секции `Context` / `Goals / Non-Goals` / `Decisions` / `Risks / Trade-offs`, то есть является ADR по структуре. Против этого ADR руками: **6 записей у jellybit, четыре из них 13 июня — в день старта**; между 15 июня и 23 июля прошло ~40 изменений и ноль ADR. У healthlog ADR нет вовсе, а настоящее ADR-рассуждение (отказ от DuckDB) лежит в разделе «Открытые вопросы» файла `architecture.md`, потому что больше некуда. - **Два плана.** `docs/plan.md` healthlog («порядок и его обоснование», 11 шагов) и `/PLAN.md` из `av-dev-tasks` («цели с обоснованием очереди прозой») — один артефакт под двумя именами. - **Дубли спек у jellybit.** Из шести файлов `docs/specs/` три (`recognition`, `review-ux`, `workflow`) описывают поведение, уже покрытое capability в `openspec/specs/`. - **`docs/drafts/` раскладывается без остатка:** `roadmap.md` → цели в «порядок», `conventions-backlog.md` → задачи `[idea]`, `logical-title-model.md` (293 строки, итог «сущность `title` не вводим») → намеренный отказ, то есть ADR. ## Решено **Р4. «Почему» — ADR как промоут поверх архива.** Обоснование по-прежнему пишет `design.md`; ADR — короткая запись, цитирующая решение и ссылающаяся на архивный `design.md`. Заводит её **шаг «синк документации» пайплайна по названному триггеру** (дорогой откат / намеренный отказ от очевидного / пересмотр прежнего решения), а не человек по вдохновению. *Причина:* ручной ритуал эмпирически не выжил — 6 записей на 52 изменения. Автоматический (`opsx:propose` пишет `design.md` всегда) работает и производит на порядок больше. Чинить надо не дом, а индекс и критерий промоута. **Р5. `docs/plan.md` растворяется в `/PLAN.md`.** Файл удаляется, 11 шагов становятся целями в «порядке», ссылки в `CLAUDE.md` и паспорте переводятся. **Р6. Пути жёсткие, оба проекта приводятся к одному виду.** Плагин знает раскладку поимённо; указателя вида `.docs.json` нет. *Причина (словами владельца):* «так проще ориентироваться во множестве проектов, а не видеть слегка похожую, но разную структуру в каждом. Все проекты малого и среднего размера, проще подогнать их под одну структуру. Кроме того, у OpenSpec тоже структура строгая». Цена принята сознательно: плагин перестаёт быть переносимым на чужой репозиторий, а `adopt` из «поправь указатели» превращается в «перенеси файлы». **Р7. Конвенции и разведка — каталогами с README-индексом.** `docs/conventions/` и `docs/research/`: путь жёсткий, нарезка внутри свободна. Схема хранилища — **отдельный** `docs/database.md` (своя каденция: меняется миграцией, а не архитектурным решением; гейт healthlog уже сверяет миграции с документацией). Конвенции идентификаторов и именования — не схема, они в `conventions/`. **Р8. Слота для черновиков нет.** Идея → задача `[idea]`; намеренный отказ → ADR; порядок работ → `PLAN.md`; незрелое размышление → `opsx:explore` внутри change. ## Канон ``` CLAUDE.md памятка агенту: что это, стек, инварианты, команды, слоты docs/ passport.md зачем и для кого; чем НЕ является; сценарии; референсы architecture.md как сложено — обзор: принципы, компоненты со ссылками на capability, внешние границы, раскладка, деплой database.md схема хранилища (там, где есть БД) conventions/README.md + <тема>.md как пишем код; README держит правило промоута research/README.md + <тема>.md что показала реальность: чужие форматы, живые данные adr/README.md + template.md + ADR-*.md почему — промоут поверх архивных design.md review-journal.md промахи конвейера ревью ← уточнено в теме 3 review-brief.md предмет ревью — см. тему 3 ← отменено в теме 3 tasks/ av-dev-tasks: items/, PLAN.md, BACKLOG.md, SPRINT.md, REJECTED.md openspec/ config.yaml только нужды генерации + ссылки specs//spec.md что система делает — нормативно changes/archive/ журнал изменений с design.md — сырьё для ADR ``` Слотов **нет** у: `docs/drafts/`, `docs/specs/`, `docs/plan.md`, `BRIEF.md`, `docs/backlog/`, `docs/review/journal.md`. ## Что из этого следует **С9. Переезд healthlog:** `architecture.md` 1611 → обзор (поведение уезжает в `openspec/specs` по разделу за задачу); `conventions.md` → `conventions/README.md`; `local-research.md` 1829 → `research/`; `plan.md` → `docs/tasks/PLAN.md`; `backlog/` → `docs/tasks/`; завести `docs/adr/`. **С10. Переезд jellybit:** `BRIEF.md` → `docs/passport.md` (заодно обновить — не трогался с 13 июня); `docs/specs/architecture.md` → `docs/architecture.md`; `docs/specs/database.md` → `docs/database.md`; `docs/specs/jellyfin-layout.md` → `docs/research/`; `docs/specs/{recognition,review-ux,workflow}.md` сверить с capability и удалить как дубли; `docs/review/journal.md` → `docs/review-journal.md`; `drafts/` растворить по H; `docs/backlog/` → `docs/tasks/`. **С11. `adopt` меняет природу** — теперь он переносит файлы, а не правит указатели. Разбирается в теме про старт проекта. **С12. Открыто до [темы 6](06-docs-upkeep.md) (поддержание):** точная формулировка триггера промоута в ADR; нужен ли механический `check` раскладки документов, раз пути жёсткие; как не потерять остаток при постепенной чистке `architecture.md`.