Daniil
42 lines
4.5 KiB
Markdown
42 lines
4.5 KiB
Markdown
# 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.
|