Files

T

журнал решений: разложен по теме на файл, метки решений стали номерами

- DECISIONS.md (4040 строк, 65 тем) → decisions/, файл на тему плюс указатель;
- буквенные метки решений заменены сквозными Р1–Р234, следствия получили
  префикс С при прежних номерах: схема букв выродилась до пятибуквенных и
  сломалась — `АЕАКЛ` была занята и темой 53, и темой 65;
- 42 перекрёстные ссылки переписаны под новые номера и стали живыми; где номер
  означал тему, а слово стояло «решение», формулировка исправлена.

2026-08-13 12:40:56 +03:00

8.1 KiB

Raw Blame History

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 (поддержание): точная формулировка триггера промоута в ADR; нужен ли механический check раскладки документов, раз пути жёсткие; как не потерять остаток при постепенной чистке architecture.md.

8.1 KiB Raw Blame History Unescape Escape