remotion_service/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This workspace has three services: cofee_frontend/ for the Next.js UI, cofee_backend/ for the FastAPI API, and remotion_service/ for video rendering. Frontend routes live in cofee_frontend/app/; app code lives in cofee_frontend/src/{pages,widgets,features,entities,shared}; E2E specs live in cofee_frontend/tests/e2e/specs/. Backend code lives in cofee_backend/cpv3/, with modules under cpv3/modules/ and tests in tests/unit/ and tests/integration/. Remotion API code lives in remotion_service/server/, compositions in remotion_service/src/, and assets in remotion_service/public/.

Build, Test, and Development Commands

• cd cofee_frontend && bun dev starts the frontend.
• cd cofee_frontend && bunx tsc --noEmit is the current reliable frontend check; bun run test:e2e runs Playwright.
• cd cofee_backend && uv sync && uv run uvicorn cpv3.main:app --reload starts the backend.
• cd cofee_backend && uv run pytest runs backend tests; uv run ruff check cpv3/ and uv run ruff format cpv3/ lint and format Python code.
• cd cofee_backend && docker-compose up starts Postgres, Redis, MinIO, API, and worker.
• cd remotion_service && bun run server starts the render API; bun run dev opens Remotion Studio; bun run lint runs ESLint and TypeScript checks.

Coding Style & Naming Conventions

Prefer early returns, descriptive names, and named constants over magic values. Frontend formatting uses tabs, no semicolons, double quotes, and sorted imports; use aliases such as @shared/* and keep FSD imports one-way: pages -> widgets -> features -> entities -> shared. Backend code targets Python 3.11+, uses absolute imports, async functions, and the standard module file set: models.py, schemas.py, repository.py, service.py, router.py. Keep user-facing UI text in Russian.

Testing Guidelines

Frontend Playwright files use *.spec.ts and *.integration.spec.ts; prefer getByRole locators and cover error paths, not just happy paths. Backend tests follow test_*.py naming and should land in tests/unit/ or tests/integration/ based on scope. No repository-wide coverage gate is configured, so add regression tests for behavior changes. remotion_service currently relies on linting plus manual render verification.

Commit & Pull Request Guidelines

Recent history favors short, lowercase subjects, sometimes with prefixes such as feature:, chore:, or init:. Keep commits scoped to one service when possible, for example feature: add silence settings validation. PRs should name the service, link the task, list commands run, include screenshots or video for UI and captioning changes, and mention backend schema updates plus regenerated frontend API types when relevant.

Codex Subagents

Project-scoped Codex subagents live in .codex/agents/. Shared team guidance lives in .codex/agent-team.md. Use built-in explorer for read-heavy codebase mapping and built-in worker for bounded implementation when a custom specialist is unnecessary.

Default operating mode is team-first:

• Before any non-trivial repo task, consult the team instead of working solo.
• Use orchestrator for cross-service, ambiguous, or high-risk tasks.
• Use the narrowest relevant lead for single-domain work: architecture_lead, quality_lead, or product_lead.
• Use a direct specialist only when the question is narrow enough that routing through a lead would add latency without changing the answer.
• After choosing the agent, follow .codex/agent-skills.md and load only the role-matched skills that materially fit the task.
• Purely mechanical actions that cannot materially change behavior, architecture, or risk may stay local.

For non-trivial work, explicitly delegate instead of handling everything in one thread:

• Use orchestrator when the task spans multiple domains or needs routing.
• Use a lead agent for multi-specialist work inside one domain: architecture_lead, quality_lead, or product_lead.
• Use a specialist directly for focused asks such as devops_engineer, security_auditor, backend_architect, or frontend_qa.
• Keep delegation shallow. .codex/config.toml sets max_depth = 2, which supports root -> lead -> specialist and avoids uncontrolled fan-out.

Migration Notes

Do not read from or rely on the .claude/ directory. If agent memory is needed, store it under .codex/memories/. Service-level CLAUDE.md files outside .claude/ still contain the best local architecture and workflow notes until matching service-level AGENTS.md files exist.