dev-conventions/CLAUDE.md

# 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`, `prefixes.toml`, `conv`) живёт в корне и в
репозитории-потребители не едет.

Ниже — короткие инварианты с идентификаторами; детали и обоснования в
`LANGUAGE.md` (форма записи) и `GUIDE.md` (процесс, префикс META).

## Форма правила

- Четыре обязательные части: `### <ПРЕФИКС>-<N>. Заголовок`, абзац
  `**МОДАЛЬНОСТЬ.** норма`, абзац `**Почему.** …`. Правило без «Почему» не
  принимается.
- Норма — одна фраза; если в неё не влезает, это два правила.
- Модальные слова: **ДОЛЖЕН**, **НЕ ДОЛЖЕН**, **СЛЕДУЕТ**, **НЕ СЛЕДУЕТ**,
  **ДОПУСКАЕТСЯ**, плюс не-модальная отметка **МЕХАНИЗИРОВАНО**. Английские
  ключевые слова (SHALL, MUST) не используются — они заняты OpenSpec.
- Модальные слова не употребляются вне правил: ни в «Область действия», ни в
  «Связано», ни в локальных регионах, ни во вводной прозе.
- «Почему» отвечает на «что сломается, если сделать иначе», а не
  пересказывает норму. «Потому что так принято» — не обоснование.
- Правило, классифицирующее ситуации, пишется таблицей «ситуация → вердикт»;
  строки нумеруются `KEYS-5.1`.
- Модальность принадлежит правилу, а не файлу: `status:` в шапке отменён.

## Идентификаторы и префиксы

- Формат `<ПРЕФИКС>-<номер>`, нумерация сквозная внутри файла. Порядок правил
  в файле — по читаемости: номер это идентификатор, а не позиция.
- Идентификаторы не переиспользуются. Удалённое правило оставляет дыру, новое
  берёт следующий свободный номер, а не первый освободившийся.
- Новый файл конвенции — новый префикс: четыре заглавные латинские буквы,
  уникальные по всему канону, выбираются под файл, а не выводятся по формуле.
  Объявляется в шапке (`prefix: KEYS`) и регистрируется в `prefixes.toml`,
  секция `[live]`, путём от корня репозитория.
- Удаление или разделение файла: префикс уходит в `[retired]` с причиной и
  датой, а не освобождается.
- Перенос правила в другой файл — смысловое изменение: новый префикс и новый
  номер. Переезд самого файла между осями идентификаторы не трогает.

## Ссылки

- META-20: норму можно исполнить, имея один этот файл. Ссылка на правило
  чужой темы допустима в «Почему», в «Связано» и в разграничении области
  действия — но не в самой норме. Нужен концепт соседней темы — коротко
  повторить его здесь, соседа назвать в «Почему».
- META-21: на соседнюю конвенцию ссылаются именем темы (конвенция
  `logging`), на правило — идентификатором (`SLOG-27`), на другой слой своей
  темы — словами «базовый слой». Пути файлов канона в тексте конвенции нет
  (в обвязке — можно).

## Что в каноне писать нельзя

- META-4: в тексте конвенции нет утверждений о состоянии конкретного
  репозитория; норма — в настоящем предписывающем времени.
- META-5: расхождение кода с правилом — отступление, а не повод переписать
  правило. Направление всегда конвенция → код; факт «в приложении уже иначе»
  не является аргументом.
- META-6: ДОЛЖЕН без механической проверки либо механизируется, либо
  понижается в СЛЕДУЕТ. Правило, непроверяемое машиной в принципе (вкус
  формулировки, суждение о ситуации), — СЛЕДУЕТ по построению.
- META-10: блок «Почему» не удаляется никогда, в том числе после того, как
  норма уехала в линтер.
- META-1: один файл — ровно один повторяющийся выбор. META-2: конвенция
  заводится, когда решение принимается третий раз.
- Локальные регионы `<!-- local:имя --> … <!-- /local -->` в каноне остаются
  пустыми: их содержимое принадлежит репозиторию-потребителю. Имя региона и
  путь файла — API, переименование осиротит все копии.

## Выбор оси

Умирает при смене языка → `lang/<язык>/`. Умирает при смене инструмента,
хранилища или транспорта → `stack/<стек>/`. Не умирает ни от того, ни от
другого → `arch/`. Ось определяется природой правила, а не числом сегодняшних
потребителей. `extends: arch/<файл>.md` в шапке — документация связи, а не
механизм; слой только реализует и сужает базу, но не отменяет её.

## Оформление файла

Шапка `prefix:` (плюс `extends:`) → `# Тема` → вводная проза со строкой
«Форма записи — `LANGUAGE.md`» → `## Область действия` (обязателен для
трудноизменяемых слоёв — META-11) → правила → `## Связано` с пустым
`<!-- local:связано -->`. Имя файла — kebab-case по теме. Проза переносится
по ~76 колонок; таблицы и блоки кода не переносятся.

## Ревью формы

Список того, что подлежит проверке, — в `LANGUAGE.md`, раздел «Что стоит
проверять машиной». Ни одна из проверок не реализована, поэтому при ревью их
выполняют чтением.

## Коммиты

Русский, строчная буква, без точки в конце, прошедшее время или страдательный
залог: «заведён реестр префиксов, правила канона перенумерованы». Изредка
область через двоеточие (`guide:`, `errors:`). Тело — маркированный список на
2–3 пункта с переносом по ~76 колонок; объясняет почему и цитирует
идентификаторы правил. Conventional Commits не используются.

## Состояние репозитория

- Тестов, линтеров и CI нет. `conv` — python3 CLI на одной stdlib; запускают
  его из корня репозитория-потребителя (`~/projects/private/dev-conventions/`
  плюс `conv status`). `status` и `diff` всегда возвращают 0 — это отчёт, а не
  проверка.
- Ни один репозиторий-потребитель ещё не подключён: копий с шапкой `origin:`
  в природе нет, все локальные регионы канона пусты.
- `TODO.md` — площадка для обсуждения на будущее, а не принятые решения; при
  работе над обвязкой его стоит прочесть, но истина о текущем устройстве —
  `README.md`.