# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Всё содержимое репозитория и общение по нему — на русском. ## Что это Канон конвенций разработки для личных проектов. Сами конвенции лежат в `conventions/{arch,lang/<язык>,stack/<стек>}/`; обвязка канона (`README.md`, `LANGUAGE.md`, `GUIDE.md`, `READING.md`, `.conventions-suite.toml`) живёт в корне. К потребителю из неё едет только `READING.md` — короткое описание языка для читателя копий. Ниже — короткие инварианты с идентификаторами; детали и обоснования в `LANGUAGE.md` (форма записи) и `GUIDE.md` (процесс, префикс META). ## Форма правила - Четыре обязательные части: `### <ПРЕФИКС>-. Заголовок`, абзац `**МОДАЛЬНОСТЬ.** норма`, абзац `**ПОЧЕМУ.** …`. Правило без обоснования не принимается. - `**ПРИМЕРЫ.**` — необязательный пятый блок после обоснования: код парой «плохо → хорошо». Иллюстрация нормы, а не спецификация — требований в блоке нет, дословным сниппетом он не является, при расхождении действует норма. - Норма — одна фраза; если в неё не влезает, это два правила. - Область правила — от его заголовка до следующего заголовка любого уровня; метка открывает блок, блок длится до следующей метки или до конца области. Абзацы после `**ПОЧЕМУ.**` — продолжение обоснования: требований в них не живёт, требование ставят в блок нормы. Таблица и список после модальной метки — часть нормы. - Шкала инвариантна, словарь — параметр языка набора. Канон русский, значит слова: **ДОЛЖЕН**, **НЕ ДОЛЖЕН**, **СЛЕДУЕТ**, **НЕ СЛЕДУЕТ**, **ДОПУСКАЕТСЯ**. Словарь один на канон, синонимов на ступень нет. - `SHALL` не используется ни в одном словаре — занято OpenSpec. - Нормативно только заглавное написание (правило RFC 8174): строчное «должен» в прозе нормой не является. - ДОЛЖЕН требует двух условий сразу: назван вред от нарушения (META-25) и вердикт о нарушении воспроизводим (META-6). Воспроизводимость сама по себе до ДОЛЖЕН не повышает — иначе шкала наполняется проверяемыми мелочами. - ДОПУСКАЕТСЯ адресовано рецензенту: помеченный им выбор на ревью не обсуждается. - **МЕХАНИЗИРОВАНО** — не модальность, а способ проверки, и свойство репозитория, а не канона: в тексте конвенции отметки нет, она стоит при записи о механизации в локальной части копии (META-7). - META-8: норма не удаляется из канона никогда, чем бы её ни проверяли. Механизация её не заменяет и не сокращает. - Метки правила — **ПОЧЕМУ**, **ПРИМЕРЫ**, **МЕХАНИЗИРОВАНО** и **СНЯТО** — тоже словарь набора и перечислены в строке о версии языка наравне с модальными словами. - META-30: правка словаря или состава частей правила доходит до `READING.md` — документа, который едет к потребителю. Словари двух описаний совпадают. - Заглавные модальные слова не употребляются вне правил: ни в «Область действия», ни в «Связано», ни в локальной части копии, ни во вводной прозе. Исключение — строка о версии языка, которая их перечисляет. - Обоснование отвечает на «что сломается, если сделать иначе», а не пересказывает норму. «Потому что так принято» — не обоснование. - Форма обоснования не ограничена: рамки смысловые. Длина, рассуждение, примеры, ссылки на внешние практики и чужие проекты — всё допустимо; запрещённых слов нет. Обязательность несёт норма, и путаницу исключает правило о заглавных. - Служебные слова сценарного блока — тоже словарь набора: **КОГДА**, **ТОГДА**, **И**, **ИЛИ** (по-английски `WHEN`/`THEN`/`AND`/`OR`). Одна форма на роль, заглавными. Модальностью не являются, в строку о версии языка не попадают. - Правило, классифицирующее ситуации, пишется таблицей «ситуация → вердикт»; строки нумеруются `KEYS-5.1`. Строки взаимоисключающи по умолчанию; иной порядок объявляется явно, а перечисленные случаи покрывают область действия. - Модальность принадлежит правилу, а не файлу: `status:` в шапке отменён. ## Идентификаторы: тема и префикс - Тема — набор правил об одном фокусе разработки и единица подписки. Имя — латиницей, рекомендуется нижний kebab-case, годится любой идентификатор, пригодный для имени файла. - META-28: тема объявлена в шапке (`topic: time`) и стоит в манифесте набора (`.conventions-suite.toml`, секция `[topics.live]`). Слои одной темы несут одно имя — по нему собираются в один файл, как бы ни назывались их файлы; имя файла повторяет тему из удобства. - META-29: имя темы не переиспользуется, снятое уходит в `[topics.retired]` с причиной и датой. Оно живёт в `origin:` копий и в подписках манифестов. - Формат `<ПРЕФИКС>-<номер>`, нумерация сквозная внутри файла. Порядок правил в файле — по читаемости: номер это идентификатор, а не позиция. - Идентификаторы не переиспользуются: новое правило берёт номер, следующий за наибольшим. - META-31: нумерация в файле сплошная. Снятое правило не исчезает, а остаётся заглушкой: заголовок с номером плюс блок `**СНЯТО <дата>.**` с причиной вместо нормы и ПОЧЕМУ. Реестра снятых номеров нет — файл сам себе реестр. - META-32: ссылок на несуществующие правила нет; неразрешённый идентификатор — всегда ошибка, а не «правило, наверное, сняли». - Новый файл конвенции — новый префикс: четыре заглавные латинские буквы, уникальные по всему канону, выбираются под файл, а не выводятся по формуле. Объявляется в шапке (`prefix: KEYS`) и регистрируется в манифесте набора, секция `[prefixes.live]`, путём от корня репозитория. - Удаление или разделение файла: префикс уходит в `[prefixes.retired]` с причиной и датой, а не освобождается. - Префиксы на букву `X` канон не занимает: они зарезервированы за локальными правилами репозиториев-потребителей. - Перенос правила в другой файл — смысловое изменение: новый префикс и новый номер. Переезд самого файла между осями идентификаторы не трогает. ## Ссылки - META-20: норму можно исполнить, имея один этот файл. Ссылка на правило чужой темы допустима в обосновании, в «Связано» и в разграничении области действия — но не в самой норме. Нужен концепт соседней темы — коротко повторить его здесь, соседа назвать в обосновании. - META-21: на соседнюю конвенцию ссылаются именем темы (конвенция `logging`), на правило — идентификатором (`SLOG-27`). Пути файлов канона в тексте конвенции нет (в обвязке — можно). - META-24: слой `lang/` или `stack/` называет идентификатор правила арх-слоя **своей** темы прямо в норме — базовый слой в собранной копии всегда рядом. На слои других языков и стеков это не распространяется: их состав зависит от манифеста. ## Что в каноне писать нельзя - META-4: в тексте конвенции нет утверждений о состоянии конкретного репозитория; норма — в настоящем предписывающем времени. - META-5: расхождение кода с правилом — отступление, а не повод переписать правило. Направление всегда конвенция → код; факт «в приложении уже иначе» не является аргументом. - META-6: ДОЛЖЕН требует воспроизводимого вердикта — двое проверяющих по тексту правила отвечают одинаково. Правило, вердикт которого зависит от суждения (вкус формулировки, уместность в конкретном месте), — СЛЕДУЕТ по построению. META-27: машинная проверка желательна, но ступени не задаёт; проверяющий по умолчанию — читатель правила, человек или агент. - META-10: блок ПОЧЕМУ не удаляется никогда, в том числе после того, как правило стало проверяться линтером. - META-1: один файл — ровно один повторяющийся выбор. META-2: конвенция заводится, когда решение принимается третий раз. - Репозиторного в каноне нет вовсе: механизация, отступления и ссылки на код живут в копии ниже маркера `` (META-22), который ставит сборщик. Заводить пустые местные разделы в каноне не нужно. ## Граница темы Пять вопросов, по которым тему проверяют на «не хапнули ли лишнего»; сначала разрез темы, ось — потом. - META-33: правило стоит в теме, чей вопрос оно решает. Тема — решение, а не вещество: «время» проходит через несколько решений сразу, и правило о колонках БД принадлежит схеме, а не времени. - META-37: имя темы называет решение и адресата, а не роль части проекта: `logging` и `client-logging`, но не `logging-backend`/`logging-frontend`. - META-34: тема нужна потребителю целиком — подписка берёт её без остатка. Если два правдоподобных потребителя хотят непересекающиеся части, между ними и проходит граница. - META-35: слой сужает базу, но не отменяет её. Приходится отменять — это не слой, а другая тема; общим осталось слово, а не решение. - META-36: вид приложения (веб-сервис, CLI, плейбуки, библиотека) называется в области действия, если норма от него зависит. Осью он не является. - META-20: норма исполнима без соседних тем. ## Выбор оси Умирает при смене языка → `lang/<язык>/`. Умирает при смене инструмента, хранилища или транспорта → `stack/<стек>/`. Не умирает ни от того, ни от другого → `arch/`. Ось определяется природой правила, а не числом сегодняшних потребителей. `extends: arch/<файл>.md` в шапке — документация связи, а не механизм; слой только реализует и сужает базу, но не отменяет её (META-35). META-38: ось объявлена в шапке ключами `lang:` и `stack:`, а не выведена из пути; без обоих ключей файл — базовый слой темы. Директория повторяет объявленное для человека. Осей может не быть вовсе: набор, где у темы один слой, — низкий конец той же модели, а не особый режим. ## Компоненты Компонент — область репозитория, где все выбранные слои действуют одновременно (`sqlite` и `postgres` — да, go и javascript — никогда). Уровней три: набор → проект → компонент. Сборка прогоняется по разу на компонент, у каждого своя директория копий, своя подписка и своя локальная часть; в `.conventions.toml` они записаны секциями `[components.<имя>]` с ключами `dir`, `lang`, `stack`, `topics`. Компонент пишется всегда, даже когда он один. Директории компонентов различны — этим копии и разводятся. ## Оформление файла Шапка `topic:` и `prefix:` (плюс `extends:`) → `# Тема` → вводная проза → отдельным абзацем строка о версии языка (её точный текст — в `LANGUAGE.md`, раздел «Ссылка на язык из конвенции») → `## Область действия` (обязателен для трудноизменяемых слоёв — META-11) → правила → `## Связано`, если канонические ссылки есть (META-17; пустого раздела не заводят). Имя файла повторяет имя темы. Проза переносится по ~76 колонок; таблицы и блоки кода не переносятся. ## Ревью формы Список того, что подлежит проверке, — в `LANGUAGE.md`, раздел «Что стоит проверять машиной». Ни одна из проверок не реализована, поэтому при ревью их выполняют чтением. Проверяется всё, что язык **употребляет**: конвенции и `GUIDE.md` (он несёт правила META и строку о версии языка). `LANGUAGE.md` и `README.md` язык цитируют — ключевые слова в них предмет описания, а не норма. Проверки распространения (тема в шапке, самодостаточность нормы, отсутствие путей канона) касаются только конвенций: обвязка к потребителю не едет. ## Коммиты Русский, строчная буква, без точки в конце, прошедшее время или страдательный залог: «заведён реестр префиксов, правила канона перенумерованы». Изредка область через двоеточие (`guide:`, `errors:`). Тело — маркированный список на 2–3 пункта с переносом по ~76 колонок; объясняет почему и цитирует идентификаторы правил. Conventional Commits не используются. ## Состояние репозитория - Тестов, линтеров и CI здесь нет: репозиторий — данные, а не код. Проверяет их `convy suite check`, живущий в своём репозитории и ставящийся бинарём. - Модель копий, описанная в `README.md`, реализована в `convy`. Прежний питоновский `conv` удалён вместе со своей моделью (зеркальное дерево, именованные регионы, `origin_hash`). При расхождении обвязки с инструментом истина — README, а не код. - Ни один репозиторий-потребитель ещё не подключён: копий с шапкой `origin:` в природе нет. - `TODO.md` — площадка для обсуждения на будущее, а не принятые решения; при работе над обвязкой его стоит прочесть, но истина о текущем устройстве — `README.md`.