opencode-config/.opencode/skills/code-standards/SKILL.md

name	description
code-standards	Universal code standards for any language. Use when writing, refactoring, or reviewing code. Also when user says "стандарты кода", "code review", "правила разработки".

Code Standards

1. Код как рассказ

• KISS: Пиши лаконично, без переусложнений. Код читается как последовательный рассказ
• Функциональный стиль: Классы — только когда нужно состояние или интерфейс библиотеки. В остальном — функции
• Приватность: Внутреннюю логику модуля скрывай. Префикс _ в Python/JS, private в TS/Rust, internal методы по умолчанию
• Разделение ответственности: Бизнес-логика ≠ транспорт ≠ представление. Максимум 200-300 строк на файл. Одна ответственность на файл

2. Прагматизм

• YAGNI: Только то что нужно сейчас. Никаких заделов «на будущее», оверинжиниринга и самодеятельности
• Правило 80/20: Если задача ведёт к неоправданному усложнению — предупреди и предложи альтернативу до написания кода

3. Принципы модульности

• Функция/метод — не длиннее 30-50 строк. Если больше — разбивай на мелкие тестируемые функции
• Файл — до 200-300 строк. Больше → декомпозиция
• Конфиги/константы — в отдельный файл, не в логику
• Приватные функции/методы для внутренних деталей (с префиксом _ или аналогом языка)

4. Документирование

• AGENTS.md правило «No comments unless requested» — это default: код без комментариев
• Этот skill описывает исключение: Google-style docstrings на английском для публичных API — когда контракт warrants (библиотечный API, public surface)
• Описывай зачем, а не что — код и так говорит что делает

5. Architecture: good vs bad

Слои для backend: routes → schemas → services → db/models (4-tier, однонаправленный). Роуты тонкие (импортируют только services + schemas), сервисы работают с db/models, бизнес-логика здесь. project-status.py enforces subset (thin routes, centralized models); этот раздел объясняет «почему».

Backend (подробно)

GOOD tree (синтетический):

src/<package>/
├── api/
│   ├── v1/
│   │   ├── routes/users.py        ← тонкие роуты, импортируют только services + schemas
│   │   ├── dependencies.py        ← Depends(), get_current_user
│   │   └── router.py
│   └── router.py
├── config/
│   ├── settings.py               ← pydantic-settings
│   └── logger.py                 ← loguru setup
├── db/
│   ├── connection.py             ← Tortoise.init
│   └── models/                   ← ВСЕ ORM-модели здесь (centralized)
│       ├── user.py
│       ├── post.py
│       └── comment.py
├── schemas/                      ← Pydantic DTO (НЕ Tortoise models)
│   ├── base.py
│   ├── user.py
│   └── post.py
├── services/                     ← бизнес-логика (работает с db/models)
│   ├── user_service.py
│   └── post_service.py
└── utils/
    └── metadata.py

Правила GOOD:

1. Все ORM-модели в db/models/ (centralized)
2. Schemas (Pydantic) отдельно от models (Tortoise) — НЕ смешивать
3. Роуты тонкие — импортируют только services и schemas
4. Сервисы работают с db/models — бизнес-логика здесь
5. Слои: routes → schemas → services → db/models (4-tier, однонаправленный)

BAD tree 1 — feature-scatter:

src/<package>/
├── channels/
│   ├── models.py              ← ❌ модель здесь (scatter)
│   ├── routes.py
│   └── service.py
├── monitor/
│   ├── models.py              ← ❌ ещё модель здесь
│   └── routes.py
├── logs/
│   └── models.py              ← ❌ и здесь
├── models.py                  ← ❌ root-level модель
├── db.py                      ← ❌ connection flat (не db/connection.py)
└── main.py

Проблемы BAD 1: модели раскиданы по feature-папкам; models.py в root; db.py flat; не publishable; Tortoise modules должен перечислять 4+ файла вручную.

BAD tree 2 — mixed-layers:

src/<package>/
├── api/
│   ├── v1/
│   │   └── users.py           ← ❌ роут содержит бизнес-логику + Tortoise queries
│   └── models.py              ← ❌ модели в api/ (не в db/models/)
├── services/
│   └── user_service.py
│       └── schemas.py         ← ❌ schemas в services/ (не в schemas/)
└── main.py

Проблемы BAD 2: роут делает Tortoise queries напрямую (не тонкий); модели в api/models.py (не db/models/); schemas внутри services (не отдельный слой).

Fullstack (кратко)

Backend as above (in backend/ + frontend/ separation). Frontend: SvelteKit co-located *.test.ts в src/lib/, e2e/*.spec.ts для Playwright. НЕ смешивать backend код в frontend/ и наоборот. + mobile-first (PWA + Playwright mobile + axe a11y) — silent enforcement через STACK_REQUIRED["fullstack"].

CLI (кратко)

cli.py (Typer commands) + core.py (business logic). Нет api/db/schemas layers. tests/test_cli.py + tests/test_core.py.

6. Tests

Что писать (как запускать — в run-tests skill). project-status.py enforces subset (conftest required, anti-stub, mirror structure); этот раздел объясняет «почему».

Типы тестов

• Regression — воспроизводит конкретный баг, который был исправлен. Ссылается на issue/PR (test_parser_handles_crlf_regression_#227).
• Integration — пересекает слои (DB+API, scheduler+DB). Имеет pytest.mark.integration + skipif opt-in. В tests/integration/.
• Unit — чистая функция/сервис, без DB/сети. В tests/unit/.

Антипаттерны

• Stub files — test_*.py без def test_*/async def test_* (digital_factory 50/62 файлов). project-status WARNs.
• Тесты без assertions — только print/logger.info. Каждый тест должен иметь минимум 1 assert.
• Тесты ради тестов — coverage ради coverage, без реальной проверки поведения.

Mirror structure (backend)

• tests/unit/ ↔ src/<pkg>/services/ (unit-тесты сервисов)
• tests/api/ ↔ src/<pkg>/api/v1/routes/ (route-тесты через TestClient)
• tests/integration/ ↔ cross-cutting flows (opt-in)

conftest.py

Обязателен (backend). Shared fixtures: mock_settings, client, auth_client, create_<entity> factories.