docs initial
This commit is contained in:
Daniil
@@ -2,25 +2,60 @@
|
||||
|
||||
## The Rule
|
||||
|
||||
This project has a 20-agent team organized in a 4-tier hierarchy (`.claude/agents/`). For ANY non-trivial task — bug hunt, code review, feature, audit, optimization, research — you MUST consult with the developer team by dispatching the orchestrator.
|
||||
This project has a 19-agent specialist team (`.claude/agents/`). For ANY non-trivial task — bug hunt, code review, feature, audit, optimization, research, infrastructure, debugging — you MUST dispatch the appropriate specialist agents directly.
|
||||
|
||||
The orchestrator handles everything: it dispatches leads (Architecture Lead, Quality Lead, Product Lead), who in turn dispatch their specialists. Results bubble up with structured audit trails.
|
||||
**You ARE the tech lead / orchestrator.** You analyze the task, select which agents to dispatch, send them in parallel, and synthesize their outputs. There is no separate orchestrator agent.
|
||||
|
||||
## What You Must NOT Do
|
||||
|
||||
- **Do NOT solve non-trivial tasks yourself.** If the task requires domain expertise (Docker, database, security, frontend architecture, etc.), dispatch the specialist agents.
|
||||
- **Do NOT investigate deeply, then decide whether to dispatch.** Identify affected files/areas, select agents, dispatch. Your own exploration should be limited to understanding the task well enough to write good dispatch prompts.
|
||||
|
||||
## Team Roster
|
||||
|
||||
| Agent | Type | Dispatch for |
|
||||
|-------|------|-------------|
|
||||
| **Architecture Lead** | Lead | API design, schema, cross-service, component architecture |
|
||||
| **Quality Lead** | Lead | Testing strategy, quality synthesis, test gap analysis |
|
||||
| **Product Lead** | Lead | UX, docs, ML/AI, monetization, feature strategy |
|
||||
| **DevOps Engineer** | Staff | CI/CD, Docker, Kubernetes, infrastructure, deployment |
|
||||
| **Debug Specialist** | Staff | Root cause analysis, cross-service debugging |
|
||||
|
||||
Leads coordinate sub-teams internally:
|
||||
- Architecture Lead → Backend Architect, Frontend Architect, DB Architect, Remotion Engineer, Sr. Backend Engineer, Sr. Frontend Engineer
|
||||
- Quality Lead → Frontend QA, Backend QA, Security Auditor, Design Auditor, Performance Engineer
|
||||
- Product Lead → UI/UX Designer, Technical Writer, ML/AI Engineer
|
||||
|
||||
**You can also dispatch specialists directly** when the task is clearly scoped to one domain:
|
||||
- `devops-engineer` for Docker/infra tasks
|
||||
- `security-auditor` for security reviews
|
||||
- `backend-architect` for API design
|
||||
- `frontend-architect` for component architecture
|
||||
- etc.
|
||||
|
||||
Use leads when the task spans multiple specialists in their sub-team. Use specialists directly when the task is focused.
|
||||
|
||||
## Pipeline
|
||||
|
||||
1. **Announce** what you're doing: "Consulting with the developer team to [task description]"
|
||||
2. **Dispatch the orchestrator** agent with your analysis of the task
|
||||
3. **Receive results** — the orchestrator returns a synthesized recommendation with a full audit trail of all agent calls
|
||||
4. **Report results** — present the synthesis to the user, crediting which specialists contributed
|
||||
2. **Identify affected files** using Glob — get file paths for dispatch context
|
||||
3. **Select agents** — minimum viable team based on the task
|
||||
4. **Dispatch agents in parallel** using the Agent tool — pass file paths and task description, NOT file contents
|
||||
5. **Collect results** from all dispatched agents
|
||||
6. **Synthesize** — present the unified report to the user, crediting which specialists contributed
|
||||
|
||||
You do NOT need to: dispatch individual agents, process handoffs, manage chain depth, or sequence phases. The orchestrator → lead → specialist hierarchy handles all of this internally.
|
||||
## Dispatch Context
|
||||
|
||||
## Announcement Format
|
||||
Every agent dispatch should include:
|
||||
- The specific task or question
|
||||
- File paths to analyze (the agent reads them itself)
|
||||
- Constraints from the overall task
|
||||
- What deliverable you need back
|
||||
|
||||
Always start with a brief announcement before dispatching the orchestrator:
|
||||
## Skip Agents ONLY For
|
||||
|
||||
> Consulting with the developer team: dispatching orchestrator to [task summary].
|
||||
- Rename a variable, fix a typo, fix a single-line syntax error
|
||||
- Answer a quick factual question about the codebase
|
||||
- Run a command the user explicitly asked for
|
||||
|
||||
## Why
|
||||
|
||||
The hierarchical agent system provides: autonomous agent-to-agent collaboration, structured guardrails (depth limits, loop prevention, cost control), full audit trails, and domain-expert analysis at every level. The orchestrator selects the right leads, leads select the right specialists, and each agent can consult others directly when needed.
|
||||
Everything else — even tasks that seem "simple" — gets dispatched to specialists.
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
# Coding Style (Extended)
|
||||
|
||||
Extends the style guidelines in CLAUDE.md with patterns from ECC.
|
||||
|
||||
## Immutability
|
||||
|
||||
Create new objects — never mutate existing ones:
|
||||
|
||||
```typescript
|
||||
// WRONG: mutation
|
||||
user.name = newName;
|
||||
items.push(newItem);
|
||||
|
||||
// RIGHT: immutable update
|
||||
const updated = { ...user, name: newName };
|
||||
const updatedItems = [...items, newItem];
|
||||
```
|
||||
|
||||
```python
|
||||
# WRONG: mutation
|
||||
user["name"] = new_name
|
||||
items.append(new_item)
|
||||
|
||||
# RIGHT: immutable (when it matters)
|
||||
updated = {**user, "name": new_name}
|
||||
updated_items = [*items, new_item]
|
||||
```
|
||||
|
||||
Exception: Pydantic models and SQLAlchemy ORM objects are designed for mutation — use them as intended.
|
||||
|
||||
## File Organization
|
||||
|
||||
- 200-400 lines typical, 800 max per file
|
||||
- High cohesion, low coupling — one concept per file
|
||||
- Backend: module structure is fixed (models, schemas, repository, service, router) — don't add extra files
|
||||
- Frontend: FSD layers are fixed — don't add files outside the layer structure
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Frontend
|
||||
- API errors: handle in TanStack Query `onError` callbacks or error boundaries
|
||||
- Form validation: `react-hook-form` with inline `register()` validation rules and `Controller` for controlled components. Error messages in Russian.
|
||||
- Never show raw error strings to users — map to user-friendly Russian messages
|
||||
|
||||
### Backend
|
||||
- Raise `HTTPException` with appropriate status codes in routers
|
||||
- Service layer returns data or raises domain exceptions
|
||||
- Repository layer lets SQLAlchemy exceptions propagate (service handles them)
|
||||
- Store error messages as named constants with `ERROR_` prefix
|
||||
|
||||
## Input Validation
|
||||
|
||||
- Frontend: TypeScript interfaces + `react-hook-form` inline rules for form data, OpenAPI-generated types for API responses
|
||||
- Backend: Pydantic schemas validate all request bodies — never trust raw input
|
||||
- File uploads: validate extension + MIME type in files module
|
||||
- Never construct SQL from user input — SQLAlchemy handles parameterization
|
||||
|
||||
## Named Constants
|
||||
|
||||
```python
|
||||
# WRONG
|
||||
if status == "completed":
|
||||
...
|
||||
|
||||
# RIGHT
|
||||
JOB_STATUS_COMPLETED = "completed"
|
||||
if status == JOB_STATUS_COMPLETED:
|
||||
...
|
||||
```
|
||||
|
||||
```typescript
|
||||
// WRONG
|
||||
if (job.status === "completed") { ... }
|
||||
|
||||
// RIGHT
|
||||
const JOB_STATUS_COMPLETED = "completed" as const;
|
||||
if (job.status === JOB_STATUS_COMPLETED) { ... }
|
||||
```
|
||||
@@ -0,0 +1,41 @@
|
||||
# Git Workflow
|
||||
|
||||
## Commit Message Format
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
<optional body>
|
||||
```
|
||||
|
||||
**Types:** feat, fix, refactor, docs, test, chore, perf, ci
|
||||
**Scopes:** frontend, backend, remotion, infra, shared (or omit for cross-cutting)
|
||||
|
||||
Examples:
|
||||
- `feat(frontend): add transcription progress bar to ActionPanel`
|
||||
- `fix(backend): prevent duplicate job creation in tasks service`
|
||||
- `refactor(remotion): extract caption animation into reusable spring`
|
||||
- `chore(infra): update Docker Compose PostgreSQL to 16`
|
||||
|
||||
## Branch Naming
|
||||
|
||||
```
|
||||
<type>/<short-description>
|
||||
```
|
||||
|
||||
Examples: `feat/caption-styles`, `fix/upload-mime-validation`, `refactor/fsd-media-module`
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. Run verification before creating PR (see `verification.md` rule)
|
||||
2. Use `git diff main...HEAD` to see all changes from branch point
|
||||
3. Summarize ALL commits (not just the latest) in PR description
|
||||
4. Include test plan with specific scenarios
|
||||
5. Push with `-u` flag for new branches
|
||||
|
||||
## Monorepo Considerations
|
||||
|
||||
- Commits should touch ONE subproject when possible
|
||||
- Cross-service changes (e.g., new API endpoint + frontend consumer) go in separate commits within the same PR
|
||||
- Migration commits go BEFORE the code that uses them
|
||||
- Never commit `.env`, credentials, or lock files across subprojects
|
||||
@@ -0,0 +1,52 @@
|
||||
# Performance Awareness
|
||||
|
||||
## Frontend Performance
|
||||
|
||||
### Bundle Size
|
||||
- Avoid importing entire libraries — use tree-shakable imports
|
||||
- Dynamic `import()` for heavy components (modals, editors, charts)
|
||||
- Check: `@next/bundle-analyzer` if bundle grows unexpectedly
|
||||
- Never import server-only code in client components
|
||||
|
||||
### Rendering
|
||||
- Memoize expensive computations with `useMemo`/`useCallback` only when profiling shows a bottleneck — not preemptively
|
||||
- Avoid prop drilling through many layers — use stores or context at the right level
|
||||
- Keep `useEffect` dependency arrays tight — stale closures are better caught by the TypeScript hook than by runtime bugs
|
||||
|
||||
### Images & Media
|
||||
- Always use `next/image` with explicit width/height or `fill` + `sizes`
|
||||
- Lazy-load below-the-fold images (default in next/image)
|
||||
- Video thumbnails: use S3 presigned URLs with appropriate cache headers
|
||||
|
||||
## Backend Performance
|
||||
|
||||
### Database Queries
|
||||
- Always use `.options(selectinload(...))` or `.options(joinedload(...))` for related data — N+1 queries are the #1 backend perf killer
|
||||
- Add `.limit()` to any query that could return unbounded results
|
||||
- Use `EXPLAIN ANALYZE` (via DB Architect agent or MCP postgres) before optimizing — measure, don't guess
|
||||
- Index foreign keys and columns used in WHERE/ORDER BY
|
||||
|
||||
### Async Patterns
|
||||
- Never use `time.sleep()` — use `asyncio.sleep()` in async code
|
||||
- Never call sync I/O (file reads, HTTP requests) in async endpoints — use `run_in_executor` or async libraries
|
||||
- Dramatiq tasks are sync — that's fine, they run in worker processes
|
||||
|
||||
### Caching
|
||||
- Use Redis for frequently-accessed, rarely-changed data (user settings, project metadata)
|
||||
- Cache at service layer, not repository layer
|
||||
- Always set TTL — no unbounded caches
|
||||
|
||||
## Remotion Performance
|
||||
|
||||
- Keep composition prop data minimal — don't pass full transcription objects, pass pre-processed caption arrays
|
||||
- Use `delayRender`/`continueRender` for async data loading in compositions
|
||||
- Prefer `interpolate()` over `spring()` for simple animations — springs are heavier
|
||||
|
||||
## Agent Model Selection
|
||||
|
||||
When dispatching subagents, consider token cost:
|
||||
- **Sonnet** (default): Standard development work, code generation, reviews
|
||||
- **Haiku**: Lightweight lookups, simple code transformations, data extraction
|
||||
- **Opus**: Complex architectural decisions, deep analysis, ambiguous requirements
|
||||
|
||||
Use `model: "haiku"` parameter on Agent tool for cheap, focused tasks.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Post-Implementation Verification
|
||||
|
||||
After completing any feature, bug fix, or refactor — run verification before claiming the work is done.
|
||||
|
||||
## Base Verification (after every code change)
|
||||
|
||||
### Frontend (`cofee_frontend/`)
|
||||
```bash
|
||||
cd cofee_frontend && bunx tsc --noEmit 2>&1 | head -30
|
||||
```
|
||||
Must pass. Pre-existing errors in `app/template.tsx:15` and `CreateProjectModal.tsx:57` are known — no new errors allowed.
|
||||
|
||||
### Backend (`cofee_backend/`)
|
||||
```bash
|
||||
cd cofee_backend && uv run ruff check cpv3/ 2>&1 | head -20
|
||||
cd cofee_backend && uv run pytest 2>&1 | tail -30
|
||||
```
|
||||
Lint and tests must pass.
|
||||
|
||||
### Remotion (`remotion_service/`)
|
||||
```bash
|
||||
cd remotion_service && bunx tsc --noEmit 2>&1 | head -30
|
||||
```
|
||||
Must pass.
|
||||
|
||||
## Final Verification (before PR/merge)
|
||||
|
||||
Run base verification PLUS:
|
||||
|
||||
### Frontend
|
||||
```bash
|
||||
cd cofee_frontend && bun run build 2>&1 | tail -20 # Production build
|
||||
cd cofee_frontend && bun run test:e2e 2>&1 | tail -30 # Playwright E2E
|
||||
```
|
||||
|
||||
### Backend
|
||||
```bash
|
||||
cd cofee_backend && uv run ruff format --check cpv3/ # Format check
|
||||
```
|
||||
|
||||
If you changed models: `uv run alembic check` to verify migrations are up-to-date.
|
||||
|
||||
## Verification Report
|
||||
|
||||
```
|
||||
VERIFICATION REPORT
|
||||
===================
|
||||
Subproject: [frontend/backend/remotion]
|
||||
Level: [base/final]
|
||||
Type check: [PASS/FAIL]
|
||||
Lint: [PASS/FAIL]
|
||||
Tests: [PASS/FAIL] (X passed, Y failed)
|
||||
Build: [PASS/FAIL or SKIPPED]
|
||||
E2E: [PASS/FAIL or SKIPPED]
|
||||
|
||||
Files changed: [count]
|
||||
Status: [READY/NOT READY]
|
||||
|
||||
Issues to fix:
|
||||
1. ...
|
||||
```
|
||||
|
||||
## When to Skip
|
||||
|
||||
- Typo fixes in comments
|
||||
- Documentation-only changes
|
||||
- Changes to CLAUDE.md / agent definitions
|
||||
|
||||
## When to Always Run Final
|
||||
|
||||
- Cross-service changes (frontend + backend)
|
||||
- Schema/model changes
|
||||
- Auth or security-related changes
|
||||
Reference in New Issue
Block a user