feat: upgrade agent team with browser, MCP, CLI tools, rules, and hooks
- Add Chrome browser access to 6 visual agents (18 tools each) - Add Playwright access to 2 testing agents (22 tools each) - Add 4 MCP servers: Postgres Pro, Redis, Lighthouse, Docker (.mcp.json) - Add 3 new rules: testing.md, security.md, remotion-service.md - Add Context7 library references to all domain agents - Add CLI tool instructions per agent (curl, ffprobe, k6, semgrep, etc.) - Update team protocol with new capabilities column - Add orchestrator dispatch guidance for new agent capabilities - Init git repo tracking docs + Claude config only Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Daniil
@@ -0,0 +1,190 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Monorepo Structure
|
||||
|
||||
Three independent projects:
|
||||
- **`cofee_frontend/`** — Next.js 16 + TypeScript frontend (FSD architecture)
|
||||
- **`cofee_backend/`** — FastAPI + Python backend (layered module pattern)
|
||||
- **`remotion_service/`** — ElysiaJS + Remotion video captioning microservice
|
||||
|
||||
Each subproject has its own `CLAUDE.md` and `AGENTS.md` — read the relevant one before starting work.
|
||||
|
||||
## Cross-Service Data Flow
|
||||
|
||||
```
|
||||
Frontend (Next.js :3000) → Backend API (FastAPI :8000) → Remotion Service (Elysia :3001)
|
||||
↕ ↕
|
||||
PostgreSQL :5332 S3/MinIO :9000
|
||||
Redis :6379 (pub/sub + task queue)
|
||||
```
|
||||
|
||||
1. Frontend calls Backend API via typed `openapi-fetch` client with JWT auth
|
||||
2. Backend submits background jobs via Dramatiq (Redis broker) — e.g. transcription, silence detection
|
||||
3. Backend sends video + transcription to Remotion Service for caption rendering
|
||||
4. Remotion renders captions onto video, uploads result to S3, returns S3 path
|
||||
5. Backend notifies Frontend of job completion via WebSocket (Redis pub/sub)
|
||||
|
||||
## Frontend Commands
|
||||
|
||||
```bash
|
||||
bun dev # Dev server (localhost:3000)
|
||||
bun run build # Production build
|
||||
bunx tsc --noEmit # Type-check (lint scripts are broken)
|
||||
bun run gc <layer> <Name> # Generate FSD component
|
||||
bun run gicons # Convert raw SVGs to React icon components
|
||||
bun run gen:api-types # Regenerate API types from OpenAPI schema (needs backend running)
|
||||
bun run test:e2e # Playwright E2E tests
|
||||
```
|
||||
|
||||
## Backend Commands
|
||||
|
||||
```bash
|
||||
uv sync # Install dependencies
|
||||
uv run uvicorn cpv3.main:app --reload # Dev server (localhost:8000)
|
||||
uv run pytest # Run all tests
|
||||
uv run pytest tests/integration/<file>.py # Single test file
|
||||
uv run pytest -k "test_name" # Single test by name
|
||||
uv run dramatiq cpv3.modules.tasks.service # Start background worker
|
||||
uv run alembic revision --autogenerate -m "msg" # Create migration
|
||||
uv run alembic upgrade head # Apply migrations
|
||||
uv run ruff check cpv3/ # Lint
|
||||
uv run ruff format cpv3/ # Auto-format
|
||||
```
|
||||
|
||||
## Remotion Service Commands
|
||||
|
||||
```bash
|
||||
cd remotion_service
|
||||
bun install # Install dependencies
|
||||
bun run server # Start API server (localhost:3001)
|
||||
bun run dev # Remotion Studio for visual debugging
|
||||
bunx tsc --noEmit # Type-check
|
||||
```
|
||||
|
||||
## Frontend Architecture (FSD)
|
||||
|
||||
Strict unidirectional imports: `pages -> widgets -> features -> entities -> shared`. No cross-slice imports within the same layer. Enforced by `eslint-plugin-boundaries`.
|
||||
|
||||
Features are **module-aware** — grouped by domain (`features/profile/`, `features/project/`), not flat.
|
||||
|
||||
Path aliases: `@app/*`, `@pages/*`, `@widgets/*`, `@features/*`, `@entities/*`, `@shared/*` map to `src/<layer>/*`.
|
||||
|
||||
See `cofee_frontend/CLAUDE.md` for full details on components, API client, styling, and gotchas.
|
||||
|
||||
## Backend Architecture
|
||||
|
||||
Layered module pattern. Each module has exactly: `__init__.py`, `models.py`, `schemas.py`, `repository.py`, `service.py`, `router.py`. No extra files, no subdirectories within modules. When in doubt, put logic in `service.py`.
|
||||
|
||||
11 modules: `users`, `projects`, `media`, `files`, `transcription`, `captions`, `jobs`, `notifications`, `tasks`, `webhooks`, `system`.
|
||||
|
||||
Flow: Router → Service → Repository → Database (async SQLAlchemy + PostgreSQL).
|
||||
|
||||
See `cofee_backend/CLAUDE.md` for full details on patterns, commands, and gotchas.
|
||||
|
||||
## Remotion Service Architecture
|
||||
|
||||
Standalone video captioning microservice. Two layers sharing types:
|
||||
- **Server** (`server/`): ElysiaJS API, single `POST /api/render` endpoint — receives S3 video path + transcription, spawns Remotion CLI render, uploads captioned video to S3.
|
||||
- **Composition** (`src/`): Remotion React components for deterministic frame rendering. All animations **must** use Remotion's `interpolate()`/`spring()`, never CSS transitions or Framer Motion.
|
||||
|
||||
See `remotion_service/CLAUDE.md` for full details.
|
||||
|
||||
## Docker Services
|
||||
|
||||
```
|
||||
postgres → localhost:5332 minio → localhost:9000 (console: 9001)
|
||||
redis → localhost:6379 api → localhost:8000 (OpenAPI at /api/schema/)
|
||||
worker → Dramatiq bg jobs remotion → localhost:3001
|
||||
```
|
||||
|
||||
```bash
|
||||
cd cofee_backend && docker-compose up # DB, Redis, MinIO, API, Worker
|
||||
cd remotion_service && docker-compose up # Remotion service (dev)
|
||||
```
|
||||
|
||||
## Localization
|
||||
|
||||
All user-facing UI text **must be in Russian**. The only exception is the brand name "Coffee Project" / "Cofee Project" — it stays in English.
|
||||
|
||||
## Code Style (Both Projects)
|
||||
|
||||
- Simple over clever, early returns over deep nesting
|
||||
- Max ~30 lines per function — extract helpers if longer
|
||||
- Named constants instead of magic values
|
||||
- Descriptive names: `getUserById` not `getData`
|
||||
- Store user-facing error messages in named constants (`ERROR_` prefix), not inline strings
|
||||
|
||||
## Agent Team
|
||||
|
||||
This project has a team of 16 specialist agents (15 specialists + 1 Orchestrator).
|
||||
Agent files: `.claude/agents/`. Shared protocol: `.claude/agents-shared/team-protocol.md`.
|
||||
|
||||
### When to Use the Orchestrator
|
||||
|
||||
For ANY non-trivial task (feature, bug fix, audit, optimization, research, infrastructure,
|
||||
review, documentation), you MUST:
|
||||
|
||||
1. Think about the task yourself first — understand scope, affected areas, risks
|
||||
2. Dispatch the `orchestrator` agent with your analysis as context
|
||||
3. Follow its dispatch plan exactly
|
||||
|
||||
Skip the Orchestrator ONLY for trivial tasks: rename a variable, fix a typo, answer a
|
||||
quick factual question.
|
||||
|
||||
### Dispatch Loop
|
||||
|
||||
After receiving the Orchestrator's plan:
|
||||
|
||||
1. Dispatch all Phase 1 agents (in parallel when the plan says parallel). When dispatching,
|
||||
include any specialist memory context the Orchestrator specified in "SPECIALIST MEMORY TO INCLUDE"
|
||||
and any relevant past decisions from "RELEVANT PAST DECISIONS".
|
||||
2. Collect results from all Phase 1 agents
|
||||
3. For each agent result, check for "## Handoff Requests" sections
|
||||
4. If handoffs exist:
|
||||
a. Dispatch the requested agents with the context provided in the handoff
|
||||
b. Collect handoff results
|
||||
c. Re-invoke the original agent with continuation context (see Continuation Format)
|
||||
d. Check the continuation result for NEW handoff requests
|
||||
5. Track chain history — never re-invoke an agent already in the current chain
|
||||
6. Max chain depth: 3. If exceeded, stop and present partial results to the user.
|
||||
7. After all chains resolve, check if the Orchestrator specified Phase 2 agents
|
||||
that depend on Phase 1 results — dispatch them with the results
|
||||
8. Repeat until all phases complete
|
||||
9. Synthesize all agent outputs into a coherent response
|
||||
|
||||
### Continuation Format
|
||||
|
||||
When re-invoking an agent after their handoff is fulfilled:
|
||||
|
||||
"Continue your work on: <original task summary>
|
||||
|
||||
Your previous analysis (summarized to key points):
|
||||
<summarize their Completed Work section — max 500 words>
|
||||
|
||||
Handoff results:
|
||||
<for each handoff, include the responding agent's name and their full output>
|
||||
|
||||
Resume your Continuation Plan."
|
||||
|
||||
### Context Triggers
|
||||
|
||||
After each agent returns, check their output against the Orchestrator's
|
||||
"CONTEXT TRIGGERS TO WATCH" list. If a trigger fires, dispatch the
|
||||
specified agent with the relevant finding as context.
|
||||
|
||||
### Conflict Handling
|
||||
|
||||
If two agents' outputs contradict each other:
|
||||
- If one has clear domain authority → use their recommendation
|
||||
- If ambiguous → present both to the user with your analysis
|
||||
|
||||
## Compact Instructions
|
||||
|
||||
When compacting, always preserve:
|
||||
- List of all modified files and their purposes
|
||||
- Test command results (pass/fail)
|
||||
- Architecture decisions made in this session
|
||||
- Error messages and their resolutions
|
||||
- Which subproject (frontend/backend/remotion) is being worked on
|
||||
Reference in New Issue
Block a user