av
d79189be18
- беклог и план переехали в docs/tasks (38 задач, 11 целей), слаги переименованы с транслита на английские, 85 ссылок поправлены - conventions.md разобран в docs/conventions/, local-research.md — в docs/research/, review-journal.md — в docs/review.md с разделом настройки конвейера; заведены security.md, adr/ и .pm.json - шаг docs.py check добавлен в task gate; поведение в architecture.md помечено девятью маркерами долга, database.md получил настройки с числовым значением
3.1 KiB
Конвенции кода
Как мы пишем код — в отличие от openspec/specs/, который описывает, что
система делает, и architecture.md, который описывает, как
она сложена.
Прозой остаётся только то, что не выражается правилом. Свойство, ставшее правилом линтера, отсюда удаляется и переезжает в перечень «Механизировано».
Язык документации и кода — в CLAUDE.md: это правило шире кода, оно касается и коммитов, и документов.
Записи
- errors.md — ошибки: обёртка, sentinel против типа, трансляция на границе, что глушим.
- logging.md — логи: уровень по адресату, единственный логирующий чекпоинт, что не попадает в лог никогда.
- config.md — конфигурация: TOML, валидация на старте, самодокументируемый образец.
- storage.md — база и идентификаторы: ULID и естественные ключи, время в UTC, правило выбора между версиями, отпечаток витрины, миграции.
- testing.md — тесты: реальные пакеты в
testdata, идемпотентность, перебор версий, замер на живом архиве.
Механизировано
Проверяет task lint по .golangci.yml. Пересказывать эти
правила прозой не нужно — линтер скажет точнее и всегда актуальнее.
| Правило | Где механизировано |
|---|---|
msg лога — константная категория, данные атрибутами |
sloglint |
Без fmt.Print* — логируем через slog |
forbidigo |
Конфигурация только из TOML, без os.Getenv |
forbidigo |
Время генерирует store.Now(), не time.Now() |
forbidigo |
Сравнение ошибок через errors.Is/As, не == |
errorlint |
Ошибки только stdlib errors + fmt.Errorf |
depguard |
Стек-трейсы избыточны — контекст несёт slog |
depguard |
Плюс шаги task gate: сборка, go vet, gofmt, тесты,
гонки, покрытие изменённых строк, миграции, образцы конфига, секреты в индексе,
данные о здоровье в индексе.
Непойманное место механизации означает, что проход по конвенциям будет добросовестно проверять уже проверенное.