av
6c7f006e75
- перечень «Механизировано» и то, что осталось прозой, снято из конвенций: они про то, как писать код, а не про инструменты, которые его читают - новый документ — дом темы ревью autotests, с границами: семантика гейта остаётся в CLAUDE.md, журнал дефектов и вопросы по темам — в review.md - вопрос ревью о суждении по готовому ответу сужен до того, что машина не проверяет: до ответа мимо recorder
60 lines
4.8 KiB
Markdown
60 lines
4.8 KiB
Markdown
# Конвенции кода
|
||
|
||
Как мы пишем код — в отличие от `openspec/specs/`, который описывает, что
|
||
система делает, и от [../architecture.md](../architecture.md), который описывает,
|
||
как она сложена.
|
||
|
||
**Прозой остаётся только то, что не выражается правилом.** Свойство, ставшее
|
||
правилом линтера или тестом-сканером, отсюда **удаляется** и переезжает в
|
||
перечень «Механизировано» документа [../autotests.md](../autotests.md) — дома
|
||
инструментов, которые читают код. Причина: файл на несколько сотен строк
|
||
размазывает внимание по тривиальному — и модель, и человек добросовестно
|
||
проверят именование и не дойдут до формы решения.
|
||
|
||
Обоснование «почему именно так» живёт в [../adr/](../adr/README.md); инварианты с
|
||
severity — в [CLAUDE.md](../../CLAUDE.md).
|
||
|
||
## Откуда взяты и что с расхождениями
|
||
|
||
Четыре записи перенесены из проекта jellybit — тот же Go, тот же автор, те же
|
||
задачи. Код transcriber написан раньше и **части правил не следует**: ключи —
|
||
UUID вместо ULID, время берётся `time.Now()` по месту, лог пишется на каждом
|
||
шаге и дублируется воркером.
|
||
|
||
Из этого перечня одно уже закрыто: доменные ошибки проверялись приведением типа
|
||
до 2026-08-11, задача `errors-as-instead-of-typecast`. Приведение типа на этом
|
||
месте больше не долг, а регрессия.
|
||
|
||
Пятая, `web-ui.md`, тоже пришла оттуда, но не прижилась: jellybit работает на
|
||
htmx, а здесь решено делать SPA — и перенесённый текст снят целиком.
|
||
|
||
Каждое такое место названо в своей записи строкой «*Расхождение:*». Читается оно
|
||
как **долг, а не как нарушение**: правила действуют на новый код, переписывание
|
||
существующего — отдельная работа. Проходу ревью строка «Расхождение» говорит, что
|
||
находка на этом месте уже известна и новой не считается.
|
||
|
||
## Записи
|
||
|
||
- [logging.md](logging.md) — логирование: уровень по адресату, единая логирующая
|
||
точка на доменной границе, словарь полей, `ext.*`, что не логируем.
|
||
- [errors.md](errors.md) — ошибки: stdlib, обёртка `%w`, `errors.Is` и
|
||
`errors.As`, трансляция доменной ошибки на внешней границе, sentinel против
|
||
типизированной.
|
||
- [config.md](config.md) — конфигурация: TOML, секреты рендерит выкладка в файл
|
||
`0600`, самодокументируемый `config.dist.toml`, проверка на старте.
|
||
- [database.md](database.md) — БД и идентификаторы: время в UTC RFC 3339, TEXT
|
||
ULID, разбор на входной границе, естественные ключи у деталей.
|
||
- [web-ui.md](web-ui.md) — веб-UI: Vue 3 с Vite и статикой в бинарнике,
|
||
однофайловые компоненты, таблица маршрутов, состояние в экране, одна обёртка
|
||
над `fetch`, показ ошибок и состояний списка.
|
||
|
||
## Что из этого проверяет машина
|
||
|
||
Перечень правил, доведённых до проверки, и место настройки каждого — в
|
||
[../autotests.md](../autotests.md). Там же сказано, что из перечисленного в
|
||
записях осталось прозой и потому проверяется человеком на каждом ревью заново:
|
||
сегодня правилом выражено ровно одно свойство из всех записей.
|
||
|
||
Здесь этот перечень не повторяется. Дом у него один, и он не тут: конвенции
|
||
говорят, как писать код, а не какими инструментами его читают.
|