av
bf6a173115
- DECISIONS.md (4040 строк, 65 тем) → decisions/, файл на тему плюс указатель; - буквенные метки решений заменены сквозными Р1–Р234, следствия получили префикс С при прежних номерах: схема букв выродилась до пятибуквенных и сломалась — `АЕАКЛ` была занята и темой 53, и темой 65; - 42 перекрёстные ссылки переписаны под новые номера и стали живыми; где номер означал тему, а слово стояло «решение», формулировка исправлена.
107 lines
8.1 KiB
Markdown
107 lines
8.1 KiB
Markdown
# 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 шагов)
|
||
и `<tasks>/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` растворяется в `<tasks>/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/<capability>/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`.
|