docs: документы подняты на канон 7

- review.md переведён на словарь меток: вопросы адресованы темам, триггеры
  профиля стали триггерами метки в три списка, quick/standard/wide → small/
  medium/large, профиль deep упразднён
- openspec/config.yaml переписан по канонической форме: адреса passport и
  CLAUDE.md вместо пересказа правил ревью и конвенций
- разобраны находки doc-consistency и doc-code-drift: исключение инварианта
  сверено со спеками, единая точка времени и таблица classifyErr дополнены,
  MaxTorrentSize получил дом в database.md
This commit is contained in:
av
2026-08-07 13:01:23 +03:00
parent b450ab1fd5
commit b879c049ea
11 changed files with 174 additions and 143 deletions
+30 -34
View File
@@ -9,50 +9,46 @@ context: |
- Технические термины (API, REST, JWT), пути и код — на английском
Имена capabilities:
- Capability — это ПОВЕДЕНИЕ/домен системы, а не пакет кода (совпадение с
- Capability — это ПОВЕДЕНИЕ или домен системы, а не пакет кода (совпадение с
именем пакета допустимо, но не критерий).
- Существительное, понятное без знания кода: ingest, recognition,
file-layout, review, notifications. НЕ qbt/worker (это реализация).
- Существительное, понятное без знания кода: ingest, recognition, file-layout,
review, notifications. НЕ qbt/worker это реализация.
- Гранулярность по принципу «требования меняются вместе». Дробить, когда в
одной спеке смешиваются разные заботы. Переименовать дёшево (RENAMED
Requirements) — не дроби преждевременно в маленьком проекте.
RFC 2119 — это требование валидатора, не стиль:
RFC 2119 — требование валидатора, не стиль:
- Каждое ### Requirement ОБЯЗАНО содержать литерал SHALL или MUST, иначе
`openspec validate` падает (проверено). Поэтому эти слова и WHEN/THEN не
русифицируем — они несут точную нормативную/структурную семантику.
`openspec validate` падает. Поэтому эти слова и WHEN/THEN не русифицируем.
Ревью (процесс, не артефакт):
- Нетривиальная/архитектурная задача — два чекпоинта: ревью дизайна (после
design/specs, ДО кода — дешевле чинить направление) и ревью кода (после
apply, до archive).
- Тривиальная задача — достаточно одного прохода (код).
Что это за проект — читай перед предложением, а не отсюда:
- docs/passport.md — цель, её граница (чем jellybit НЕ является),
потребители, типовые сценарии, референсы;
- CLAUDE.md — инварианты с severity, семантика гейта, запреты с путями и то,
что считается необратимым;
- docs/architecture.md — устройство и единые точки; docs/security.md —
периметр; docs/database.md — схема и настройки с числами;
docs/adr/ — почему решено так; docs/research/ — что уже измерено.
Пересказа этих документов здесь нет намеренно: второй дом факта расходится с
первым молча, и заметно это становится в предложении, которое уже написано.
Конвенции кода (соблюдать при apply):
- Механизируемое проверяет конвейер сборки (.golangci.yml + internal/archrules),
пересказывать его здесь не нужно: `task lint` и `task test` скажут точнее.
- Прозой остаётся то, что правилом не выражается, и это читаем в источнике:
docs/conventions/{logging,errors,config,database,web-ui}.md — уровень лога
по адресату, единственный логирующий чокпоинт на доменной границе,
трансляция доменной ошибки на внешней границе, самодокументируемый
config.example.toml, htmx-партиалы.
- Безопасность: никаких секретов в полях логов и в диагностике состояния
(пароли qBittorrent, API-ключи LLM/метабаз, auth-заголовки).
Ревью: правило выбора метки и состав проходов здесь не пересказываем — их дом
скилл av-dev-pipeline:review-pipeline, проектная настройка — docs/review.md.
# Project context (optional)
# This is shown to AI when creating artifacts.
# Add your tech stack, conventions, style guides, domain knowledge, etc.
# Example:
# context: |
# Tech stack: TypeScript, React, Node.js
# We use conventional commits
# Domain: e-commerce platform
Конвенции кода: механизированное проверяет `task gate`, прозой остаётся
docs/conventions/. Ни состав шагов гейта, ни перечень конвенций здесь не
пересказываем: и то и другое растёт по ходу задач.
Развилка или блокер — сперва prior art. Готовые решения смотрим в референсах
паспорта, отвергаем — с названной причиной, и причина идёт в design.md этого
же изменения.
# Per-artifact rules (optional)
# Add custom rules for specific artifacts.
rules:
proposal:
- Capabilities называй по поведению/домену системы, не по пакету кода
- Capabilities называй по поведению или домену системы, не по пакету кода
specs:
- Каждое ### Requirement обязано содержать SHALL или MUST (иначе валидация падает)
- Заголовки и WHEN/THEN/GIVEN — на английском, остальной текст на русском
# Кавычки обязательны: без них YAML обрежет строку на первом '#'.
- "Каждое ### Requirement обязано содержать SHALL или MUST (иначе валидация падает)"
- "Сценарий — ровно #### (четыре решётки); три или список молча теряются"
- "SHALL/MUST должно стоять в ПЕРВОМ абзаце требования: валидатор смотрит только его"
- "Заголовки и WHEN/THEN/GIVEN — на английском, остальной текст на русском"