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

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

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

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

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

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

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

- [commands.md](./commands.md) — актуальные команды для `qadam-core` и `qadam-web`
- [knowledge-base.md](./knowledge-base.md) — продуктовая и техническая база знаний
- [product-roadmap.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](rules/architecture-vertical-slices.md) — вертикальные срезы по фичам
- [architecture-feature-boundaries](rules/architecture-feature-boundaries.md) — границы модулей и инкапсуляция
- [architecture-server-components](rules/architecture-server-components.md) — Server Components против Client Components
- [architecture-api-separation](rules/architecture-api-separation.md) — backend как единый источник серверных данных

### Качество

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

### Data Layer

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

### API Design

- [api-thin-controllers](rules/api-thin-controllers.md) — thin controllers
- [api-validation](rules/api-validation.md) — Zod-validation и boundary validation
- [api-versioning](rules/api-versioning.md) — версия API и обратная совместимость

### Performance

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

### Testing

- [testing-coverage-requirements](rules/testing-coverage-requirements.md) — требования к покрытию
- [testing-nestjs](rules/testing-nestjs.md) — backend testing patterns
- [testing-playwright](rules/testing-playwright.md) — web smoke/e2e на Playwright
- [testing-timezone](rules/testing-timezone.md) — единая работа с `TZ=UTC`

### CI/CD

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

### Patterns

- [patterns-dependency-injection](rules/patterns-dependency-injection.md) — DI patterns
- [patterns-shared-schemas](rules/patterns-shared-schemas.md) — Zod schemas внутри `qadam-core` и граница с `qadam-web`
- [patterns-i18n](rules/patterns-i18n.md) — i18n patterns

### Reference

- [reference-file-locations](rules/reference-file-locations.md) — ключевые пути по двум репозиториям
- [reference-local-dev](rules/reference-local-dev.md) — актуальный локальный запуск