chore: simplify root tooling and repository boundaries
Conventional commits / commits (pull_request) Successful in 10s

This commit was merged in pull request #10.
This commit is contained in:
2026-09-15 20:45:36 +03:00
parent 4a78dd640d
commit 95e4361599
15 changed files with 89 additions and 358 deletions
+7 -10
View File
@@ -9,9 +9,8 @@
3. Расширь подходящий owner/helper/pattern; выбирай минимальное решение,
полностью закрывающее текущую задачу. Новый файл сам по себе не улучшение.
Уменьшай количество способов решать одну техническую задачу. Во frontend
сравни query keys, formatters, class composition; в backend — pagination,
error mapping, repositories и обращения к одному provider. Сходный синтаксис
Уменьшай количество способов решать одну техническую задачу: конфигурацию
release-it и commitlint поддерживай средствами этих инструментов. Сходный синтаксис
без общей ответственности не требует DRY. Критерий dependency — в
[dependencies](dependencies.md).
@@ -23,10 +22,8 @@ Consistency с подходящим project pattern предпочтительн
Сначала используй native API/установленный stack; не строй на гипотетических
consumers и будущих requirements.
Backend: CQRS, Event Sourcing, Domain Events, Unit of Work, Command Bus,
generic repositories, abstract factories, custom DI и elaborate domain layers
не вводятся только ради «best practice». Frontend: wrapper над Mantine, global
store и дополнительная OpenAPI hash/schema система не создаются автоматически.
Не вводи shared tooling для других репозиториев как обязательную зависимость
их сборки, CI или маршрута инструкций. Каждый repo владеет своими checks.
Trust-boundary validation, authorization, atomicity, accessibility и необходимая
regression proof остаются частью полного решения.
@@ -44,8 +41,8 @@ low-risk, behavior-preserving проблемы, которые легко про
Устойчивый pattern должен находиться через код и manifest. Добавляй convention,
только если следующей сессии всё ещё нужно явное project decision rule.
У каждого правила один owner; AGENTS содержит trigger и ссылку.
Mental model живёт в `.ai/architecture.md`, intent — в specs, системные знания —
в docs. Audit/backlog не помещай в conventions.
Устройство root tooling находится в README и конфигурации; их чтение не
требует соседних checkout. Audit/backlog не помещай в conventions.
Legacy фиксируется отдельно; новый diff не добавляет нарушений. При migration
закрывай подтверждённые baseline findings с evidence, сохраняя область проверки.
@@ -65,4 +62,4 @@ Numeric policy называй по смыслу и единицам (`TIMEOUT_MS
Индексы, `index + 1`, `Math.max(value, 0)` и обычные labels/log messages
не выноси в constants без semantic benefit. Локальный lint/i18n profile всё равно
применим. Не создавай tests существования констант или custom magic-string analyzer.
Различия TS/генератора принадлежат local conventions frontend/backend.
Правила приложений принадлежат их локальным conventions.
+2 -6
View File
@@ -14,9 +14,6 @@ native API и зрелую небольшую dependency: parsing, serialization
debounce, class composition. Три `Array.map` не требуют utility library.
Не продолжай копировать boilerplate, если один принятый способ дешевле сопровождать.
`clsx` сейчас не принят как direct dependency. Разные способы соединить классы
сначала требуют подтверждённого повторения; устанавливать его заранее не нужно.
## При выборе пакета
- Укажи конкретную потребность, альтернативу из текущего stack и существенную
@@ -26,8 +23,7 @@ debounce, class composition. Три `Array.map` не требуют utility libr
- Сохраняй exact versions и lockfile. Перед Node-командами активируй `.nvmrc`
через `nvm use --silent`; воспроизводимая установка — `npm ci` в нужном repo.
- Peer-конфликты решай совместимыми версиями, без `--force`/`--legacy-peer-deps`.
Известная frontend граница TypeScript/openapi-typescript — в
[README](../../frontend/README.md#проверка); версии принадлежат manifest/lockfile.
Версии и compatibility принадлежат местному manifest/lockfile.
- После изменения запускай relevant install/type/build/behavior checks и
existing security workflow. Не добавляй второй analyzer, когда задача решается
`npm audit` при изменении зависимостей. Не добавляй второй analyzer, когда задача решается
настройкой существующего; [карта проверок](guardrails.md).
+3 -5
View File
@@ -7,16 +7,14 @@
- Commit содержит одну связанную задачу и её необходимые проверки/документацию.
Межрепозиторное изменение оформляй отдельными commits/PR с взаимными ссылками.
- Commits и заголовки PR — Conventional Commits; допустим `spec:`.
Во frontend номер связанной issue добавляй в конец заголовка (`fix: … #12`);
без связанной issue номер не нужен. Формат проверяет local commitlint.
Формат проверяет local commitlint; правила других repo принадлежат их AGENTS.
- Перед commit проверь `git diff --cached --name-status` и сам staged diff
в каждом affected repo. Root tracking ограничен [.gitignore](../../.gitignore):
новый общий файл получает точечный allowlist и проверку
[tracking](../../test-workspace-tracking.py). `git add -f` не используется.
новый общий файл получает точечный allowlist; проверь staged paths вручную. `git add -f` не используется.
- Не выполняй `git clean -fdx`, reset чужих изменений, force-push, удаление или
перенос опубликованных тегов как обычную очистку. Для опасной операции нужны
явная необходимость, сохранение данных и соответствующая авторизация.
- Обычный PR допускает squash. Release/hotfix, синхронизация main/develop,
release-конфигурация и CI refs требуют чтения
release-конфигурация требуют чтения
[процесса релиза](../../README.md#релизы-и-ветки): он владеет merge policy,
версиями и тегами. Прямой push в `main` запрещён; версии вручную не повышай.
+12 -45
View File
@@ -1,48 +1,15 @@
# Conventions → deterministic guardrails
# Root проверки
Читай при выборе проверки или изменении tooling. Команды выполняются из repo
владельца после `nvm use --silent`. Config/manifest задаёт фактический scope;
таблица не заменяет semantic review и не утверждает, что все checks уже запущены.
Root CI содержит только `commits`: штатный commitlint проверяет заголовок PR
и коммиты между BASE и HEAD. Установка — `npm ci --ignore-scripts`, Node — из
местной `.nvmrc`. Самописные проверки и дополнительные CI workflow не добавляются.
| Convention | Существующий check | Достаточность / следующий шаг |
| --- | --- | --- |
| Git multi-repo tracking | root `python3 test-workspace-tracking.py`, `.gitignore` | Проверяет exact allowlist и сохранность fictional data/nested Git; обновлять вместе с allowlist |
| Conventional Commits | local commitlint + commits workflow | Syntax покрыт; атомарность и scope — review |
| Dependencies | exact manifest/lockfile, `npm ci`, security workflows (audit/Gitleaks) | Reuse, peer compatibility, ценность dependency — review; новый analyzer не нужен |
| Frontend types/style/literals | TypeScript strict, `erasableSyntaxOnly`; Biome `npm run lint` | Props profile, i18n и symbolic strings требуют review; literals exclusions — в Biome |
| Frontend FSD | dependency-cruiser `npm run deps` | Upward imports, cycles, public entry points покрыты; same-layer запрет неполный, semantic ownership не проверяется |
| Unused frontend code/deps | `npm run knip`, TS unused locals/params | Existing tool достаточно; не добавлять второй unused analyzer |
| API generation | frontend `openapi:check`; backend `test:openapi-contract` | Первый сравнивает generated types со snapshot; второй — Nest schema со snapshot. Ни один не доказывает runtime validation errors |
| Query/auth/error/finance behavior | Vitest + RTL/MSW; backend Jest/SQLite/HTTP | Test Intent выбирает риск и уровень, без автоматического теста для каждого файла |
| Storybook | `typecheck`, `deps:storybook`, `build:catalog` | Imports/types/build покрыты; `play`, visual/keyboard/browser behavior проверять отдельно |
| Backend types/style | ESLint/Prettier, app/test TypeScript | Zero-warning gate; `no-explicit-any` отключён, часть unsafe rules включена. Не обещать полного запрета `any` |
| Backend modules/domain | TypeScript и semantic review | Отдельного architecture analyzer нет. При повторных нарушениях сначала рассмотреть existing ESLint `no-restricted-imports`, без нового custom analyzer |
| DB ownership/atomicity | Prisma schema/constraints, `test:sqlite`, `test:e2e`, `test:durability` | Mock Prisma недостаточно. Relevant suites на disposable DB, без reset пользовательской базы |
| Logging/security | Logging/auth/access tests, configured HTTP tests, Gitleaks | Allowlist/redaction имеют границы. Встроенный ESLint `no-console` можно включить отдельно; semantic security review обязателен |
| Markdown/routing | docs markdownlint-cli2 + relative-links, `git diff --check` | Existing docs gate охватывает docs, а не соседние `.ai`; для них запустить тот же установленный CLI с явным списком путей и docs config |
Локально перед Node-командами выполни `nvm use --silent`. Для изменений проверь
JSON/config syntax, тексты, ссылки и `git diff --check`; новые файлы просмотри
отдельно. Перед commit проверь staged paths относительно allowlist `.gitignore`.
Зависимости устанавливай через `npm ci`; при их изменении выполни `npm audit`.
## Ratchet без новой инфраструктуры
- Existing error gates остаются обязательными; не ослабляй их ради legacy.
- До расширения FSD rule получи candidate violations существующим depcruise.
Его `--ignore-known` допускает native baseline; сначала проверь формат через
`--help`. Не игнорируй целые directories. Обновление baseline принимается
только с evidence закрытия/явным обоснованием нового исключения.
- Semantic findings учитываются stable IDs в
[inventory](../migrations/conventions-v1/audit.md) и закрываются vertical slices
по [plan](../migrations/conventions-v1/plan.md). Это reviewed inventory,
не автоматический полный счётчик нарушений.
- Новый analyzer/custom baseline CI не создаётся. Если существующей проверки
недостаточно, сначала сформулируй повторяющийся regression и стоимость
поддержки предлагаемого rule.
## Выбор финального gate
Markdown/routing-only: проверить все новые/изменённые Markdown, ссылки/якоря,
достижимость тем, смысл и `git diff --check`. Root allowlist change дополнительно
требует tracking-тест. Не запускать application builds/coverage только ради текста.
Code/dependency changes: full `npm run verify` affected repo после lockfile install;
targeted tests ускоряют итерацию, но не подменяют required gate. Wire changes
дополнительно требуют backend contract check, HTTP/DB changes — relevant isolated
suites по local Testing. Форматирующие `lint:fix`/`format` — mutations, не proof.
Release-it использует встроенные проверки ветки, чистого дерева и наличия
коммитов. Перед подготовкой релиза вручную проверь теги и соответствие версии
последнему принятому тегу; повторно не повышай уже подготовленную версию.
Процесс — в [README](../../README.md#релизы-и-ветки).