язык записи опёрт на стандарты, словарь стал параметром

- шкала обязательности объявлена инвариантом, а набор ключевых слов —
  параметром естественного языка набора: для английского готовый словарь
  даёт BCP 14, для прочих берут перевод стандарта или делают свой; отклонены
  синонимы ступеней и `SHALL`, занятый OpenSpec
- применены шесть дельт: нормативно только заглавное написание (RFC 8174),
  ДОЛЖЕН требует названного вреда и машинной проверки сразу, ДОПУСКАЕТСЯ
  адресовано рецензенту, МЕХАНИЗИРОВАНО выведено из шкалы в отметку рядом с
  модальностью (ISO/IEC/IEEE 29148), у таблиц объявлены политика совпадения
  и полнота (DMN)
- «Форма записи — LANGUAGE.md» в двенадцати конвенциях заменена строкой о
  версии языка по образцу boilerplate BCP 14: пути канона в копии не
  существует, а словарь и правило заглавных строка несёт сама
This commit is contained in:
av
2026-07-26 13:42:10 +03:00
parent fea0285619
commit 9318087248
16 changed files with 395 additions and 205 deletions
+5 -1
View File
@@ -8,7 +8,11 @@ prefix: DIRS
создания и ценности содержимого: конфигурация, данные, кеш. Категория сразу
отвечает на два вопроса, которые иначе выясняются чтением кода приложения:
**кто создаёт** содержимое и **что будет, если его потерять**. Из категорий
механически выводится состав бэкапа. Форма записи — `LANGUAGE.md`.
механически выводится состав бэкапа.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
## Область действия
+5 -1
View File
@@ -5,7 +5,11 @@ prefix: CONF
# Конфигурация приложения
Как устроена конфигурация: где лежит, как попадает в процесс, что с
секретами и когда падает. Форма записи — `LANGUAGE.md`.
секретами и когда падает.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
## Область действия
+5 -2
View File
@@ -4,8 +4,11 @@ prefix: KEYS
# Идентификаторы сущностей
Как выбираются и как выглядят первичные ключи сущностей. Форма записи —
`LANGUAGE.md`.
Как выбираются и как выглядят первичные ключи сущностей.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
## Область действия
+5 -2
View File
@@ -5,8 +5,11 @@ prefix: TIME
# Время
Как приложение записывает моменты и длительности: в каком формате, откуда
берётся значение и где появляется не-UTC. Форма записи —
`LANGUAGE.md`.
берётся значение и где появляется не-UTC.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
## Область действия
+5 -1
View File
@@ -6,7 +6,11 @@ extends: arch/config.md
# Конфигурация: реализация на Go
Как базовый слой выглядит в Go-приложении: формат, загрузчик, границы
запрета на окружение. Форма записи — `LANGUAGE.md`.
запрета на окружение.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
Секретов Go-специфика не касается: они приходят из деплоя уже в файле, а
проверка их непустоты идёт вместе с остальной валидацией — как описано в
+5 -2
View File
@@ -5,8 +5,11 @@ extends: arch/db-identifiers.md
# Идентификаторы: реализация на Go
Как базовый слой выглядит в Go-приложении. Форма записи —
`LANGUAGE.md`.
Как базовый слой выглядит в Go-приложении.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
Единая точка из `KEYS-3` — пакет `internal/ident`: он
порождает идентификаторы (`NewID`, `NewIDAt`) и он же их разбирает
+5 -1
View File
@@ -5,7 +5,11 @@ prefix: MIGR
# Схема и миграции (SQLite, Go)
Как пишутся миграции и какие типы колонок выбираются для схемы SQLite в
Go-приложении. Форма записи — `LANGUAGE.md`.
Go-приложении.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
## Область действия
+7 -3
View File
@@ -4,9 +4,13 @@ prefix: GERR
# Ошибки
Как ошибки строятся, оборачиваются и проверяются. Форма записи —
`LANGUAGE.md`. Где и когда ошибку **логировать** — в конвенции `logging`
(коротко: лог один раз на доменной границе).
Как ошибки строятся, оборачиваются и проверяются. Где и когда ошибку
**логировать** — в конвенции `logging` (коротко: лог один раз на доменной
границе).
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
Две границы, о которых говорят правила ниже:
+5 -1
View File
@@ -7,7 +7,11 @@ extends: arch/time.md
Как и когда писать логи. Это правила оформления кода (How), а не
спецификация поведения: наблюдаемые требования к логам, входящие в контракт
функциональности, живут в спеках. Форма записи — `LANGUAGE.md`.
функциональности, живут в спеках.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
Лог читают инструментами, а не глазами: повседневно — `jq`
(`jq 'select(.download_id=="a1b2")' app.jsonl`), тяжёлое (агрегации, JOIN) —
+6 -3
View File
@@ -5,9 +5,12 @@ extends: arch/time.md
# Время: реализация на Go
Как требования базового слоя выполняются в Go-коде: откуда берётся
«сейчас», в каком виде время попадает в базу и в логи, что делать с зонами.
Форма записи — `LANGUAGE.md`.
Как требования базового слоя выполняются в Go-коде: откуда берётся «сейчас»,
в каком виде время попадает в базу и в логи, что делать с зонами.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
## Правила
+5 -2
View File
@@ -5,8 +5,11 @@ extends: arch/app-directories.md
# Категории директорий: реализация в Ansible
Как категории из базового слоя раскладываются на сервере
плейбуком. Форма записи — `LANGUAGE.md`.
Как категории из базового слоя раскладываются на сервере плейбуком.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
## Область действия
+7 -4
View File
@@ -4,10 +4,13 @@ prefix: HTMX
# Веб-UI на htmx
Как пишется код веб-UI: частичный своп фрагментов, поллинг живых
обновлений, обработчики действий, деградация без JS, ошибки. Что именно UI
показывает и какие действия поддерживает — в спеках, не здесь. Форма записи
`LANGUAGE.md`.
Как пишется код веб-UI: частичный своп фрагментов, поллинг живых обновлений,
обработчики действий, деградация без JS, ошибки. Что именно UI показывает и
какие действия поддерживает — в спеках, не здесь.
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
только тогда, когда написаны заглавными.
Логирование запросов — конвенция `logging` (HTTP-поля, рутинно-частое на
`DEBUG`). Трансляция доменных ошибок наружу — конвенция `errors`