заведены README.md и CLAUDE.md

- README описывает термины, команды, два режима и вывод проверки; модель не пересказывается — истина остаётся в репозитории набора - CLAUDE.md фиксирует распределение языков, инварианты кода и решения, которые уже приняты и не пересматриваются без просьбы - отдельным разделом перечислены известные остатки, чтобы их не искали заново
2026-07-27 11:58:49 +03:00
parent 8331aa1ca5
commit 4615de6e86
2 changed files with 288 additions and 0 deletions
@@ -0,0 +1,147 @@
+# convy
+
+CLI для управления конвенциями разработки: ведёт набор конвенций и собирает
+копии в проектах.
+
+Модель, которую инструмент реализует, описана не здесь, а в репозитории набора
+(`dev-conventions`): `README.md` — устройство набора и копий, `LANGUAGE.md` —
+форма правила, `GUIDE.md` — правила ведения набора, `TOOL.md` — решения об этом
+инструменте. При расхождении истина там.
+
+## Термины
+
+| Уровень | Что это |
+|---|---|
+| набор | репозиторий с конвенциями, манифестом `suite.toml` и обвязкой |
+| тема | набор правил об одном фокусе разработки; единица подписки |
+| слой | один файл темы: базовый, языковой или стековый |
+| компонент | адресат сборки в проекте: один язык, один стек, один вид приложения |
+| префикс | четыре заглавные латинские буквы, адрес правила: `GTIM-3` |
+
+Тему и ось слоя объявляет шапка файла, а не путь: `topic:`, `lang:`, `stack:`.
+Слой без ключей оси — базовый, он попадает в копию всегда.
+
+## Установка
+
+Внешняя зависимость одна (`BurntSushi/toml`), сборка обычная:
+
+```
+go install git.vakhrushev.me/av/convy@latest
+```
+
+или из клона репозитория:
+
+```
+go build -o convy .
+```
+
+Способ раздачи готовых бинарей пока не выбран — вопрос открыт в `TOOL.md`.
+
+## Команды
+
+```
+В наборе:
+  convy suite init    завести набор: директория и манифест
+  convy suite add     завести конвенцию: файл, тема и префикс
+  convy suite rule    дописать правило: следующий номер, блоки по порядку
+  convy suite retire  снять правило, конвенцию или тему — без переиспользования
+  convy suite list    что в наборе и что возьмёт компонент
+  convy suite check   целостность набора: префиксы, темы, оси, ссылки, форма
+
+В проекте (пока не реализовано):
+  convy add <тема>    подписаться и собрать
+  convy pull          пересобрать подписанное
+  convy list          что подключено и что доступно
+  convy check         проверить форму того, что здесь
+```
+
+Контекст определяется по манифесту рядом: `suite.toml` — набор,
+`.conventions.toml` — проект. Наугад не делается ничего: команда не того уровня
+отказывает и подсказывает нужную.
+
+## Два режима
+
+Команды, которые что-то меняют, работают в двух режимах, и режим читается по
+командной строке.
+
+**Без аргументов — диалог.** Каждое поле спрашивается с подсказкой о том, что
+туда кладут и почему. Это для человека.
+
+```
+$ convy suite add
+
+The focus the rules are about: time, config, db-schema. A topic is the unit of
+subscription — a consumer takes it whole. The name never changes and is never reused.
+Topic: logging
+
+It goes into the manifest and builds the table of conventions in a consumer's README.
+One line about the topic: логирование: уровни, структура записи
+...
+```
+
+**С флагами — автоматика.** Всё передаётся сразу, вопросов не задаётся, все
+недостающие поля называются разом. Это для агентов и скриптов.
+
+```
+$ convy suite add --topic logging --about "логирование: уровни" \
+    --prefix SLOG --title "Логирование"
+```
+
+Без терминала пустой вызов отказывает, а не виснет в ожидании ответа, которого
+некому дать.
+
+## Проверка набора
+
+```
+$ convy suite check
+conventions/lang/go/logging.md
+  error:5  extends points at "arch/time.md" with topic "time", while the file
+           carries topic "logging": the layers of one topic declare one name [spread]
+
+suite: 13 files, 8 topics, language version 1 (ru)
+errors: 1, warnings: 0
+```
+
+Строка находки — `уровень:строка  что не так [семейство]`. Семейств четыре:
+
+- **manifest** — префиксы, темы, объявленные файлы, незарегистрированные файлы;
+- **form** — форма правила: нумерация, блоки, модальные слова, словарь.
+  Проверяется в любом файле, который язык употребляет;
+- **spread** — то, что относится к отъезду к потребителю: тема в шапке, ось,
+  `extends`, пути канона, самодостаточность нормы. Только в конвенциях;
+- **links** — разрешение ссылок вида `PREFIX-N`.
+
+Третья часть списка проверок языка — взаимоисключительность строк таблицы,
+покрытие области действия, отвечает ли обоснование на «что сломается» — разбором
+текста не даётся и остаётся работой читателя.
+
+Коды возврата: `0` — чисто, `1` — есть ошибки, `2` — команда набрана неверно или
+не в том контексте.
+
+## Ступени и словарь
+
+Слова, которыми записаны модальность и метки, — свойство версии языка и
+естественного языка набора, а не самого набора. Инструмент знает их сам, и
+`suite.toml` их не дублирует: достаточно `[language] version` и `lang`.
+
+Поэтому ступень называется категорией, а не словом:
+
+```
+--modality requirement | prohibition | recommendation | not-recommended | permission
+```
+
+`prohibition` в русском наборе превращается в `**НЕ ДОЛЖЕН.**`, в английском —
+в `**MUST NOT.**`. Вызывающему не нужно знать, на каком языке записан набор.
+
+По той же причине `convy` умеет написать строку о версии языка, и созданный им
+файл проходит `suite check` без единой правки.
+
+## Чего инструмент не делает
+
+- не сливает трёхсторонне и не разрешает конфликты: правка выше маркера
+  локальной части теряется, и это заявленное поведение;
+- не ведёт лок-файл: копии закоммичены, ответ на «что было в прошлый раз» даёт
+  git;
+- не хранит список подписчиков: подписка — свойство проекта;
+- не переносит правки из проекта в набор: операция ручная и редкая;
+- не перенумеровывает правила: номер — идентификатор, а не позиция.