Индекс документации Agents

Паспорт документа

• Статус документа: working reference
• Актуально на: 28 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении инженерного backlog, локального workflow или платформенного статуса
• Область применения: внутренний инженерный knowledge/rules/backlog слой проекта
• Связанные документы:
  • Индекс документации
  • Текущее состояние
  • Roadmap

Этот раздел нужен как детализированный инженерный backlog и база правил для команды. Он не заменяет канонические документы верхнего уровня, а дополняет их.

Сначала читать это

• ../README.md — общий индекс канонической документации
• ../project/current-state.md — фактическое состояние платформы, production и инфраструктуры
• ../project/roadmap.md — текущий стратегический roadmap и ближайшие спринты
• ../architecture/api-routes.md — обзорная карта живых API-маршрутов
• ../governance/engineering-principles.md — обязательные правила передачи проекта, тестирования и документации

Что находится в docs/Agents

• commands.md — актуальные команды для qadam-core и qadam-web
• knowledge-base.md — продуктовая и техническая база знаний
• product-roadmap.md — детализированный backlog по задачам и спринтам

Важно про source of truth

• Живые API-контракты определяются через qadam-core/docs/architecture/api-routes.md и OpenAPI artifact, а не через старые route examples в отдельных спеках.
• Production уже работает из qadam-core и qadam-web. Старый /data/uzbek не является рабочим репозиторием.
• docs/Agents/specs/* остаются полезными детальными сценарными спеками, но перед реализацией их нужно сверять с current-state.md, roadmap.md, api-routes.md и apps/api/openapi/openapi.json.

Индекс правил

Архитектура

• architecture-vertical-slices — вертикальные срезы по фичам
• architecture-feature-boundaries — границы модулей и инкапсуляция
• architecture-server-components — Server Components против Client Components
• architecture-api-separation — backend как единый источник серверных данных

Качество

• quality-avoid-barrel-imports — избегать barrel-imports
• quality-simplicity — держать код простым
• quality-error-handling — паттерны обработки ошибок
• quality-imports — правила импортов
• quality-pr-creation — правила подготовки PR/change package
• quality-code-comments — комментарии в коде
• quality-code-review — фокус code review

Data Layer

• data-prefer-select-over-include — prefer select в Prisma
• data-repository-pattern — repository pattern для NestJS
• data-read-write-replicas — read/write separation
• data-dto-boundaries — DTO-границы между слоями
• data-prisma-migrations — миграции и эволюция схемы
• data-redis-caching — стратегия Redis
• data-locations-and-maps — геоданные, карты и координаты

API Design

• api-thin-controllers — thin controllers
• api-validation — Zod-validation и boundary validation
• api-versioning — версия API и обратная совместимость

Performance

• performance-avoid-quadratic — избегать O(n^2)
• performance-server-rendering — SSR/SSG стратегия
• performance-database-queries — оптимизация запросов и индексов
• performance-caching-strategy — кэширование

Testing

• testing-coverage-requirements — требования к покрытию
• testing-nestjs — backend testing patterns
• testing-playwright — web smoke/e2e на Playwright
• testing-timezone — единая работа с TZ=UTC

CI/CD

• ci-type-check-first — type-check до остальных шагов
• ci-git-workflow — git/change workflow
• ci-deployment — текущий deploy-контур и целевой docker/image-based контур

Patterns

• patterns-dependency-injection — DI patterns
• patterns-shared-schemas — Zod schemas внутри qadam-core и граница с qadam-web
• patterns-i18n — i18n patterns

Reference

• reference-file-locations — ключевые пути по двум репозиториям
• reference-local-dev — актуальный локальный запуск