Time de Agentes Claude

O fast_deliv é desenvolvido com assistência de um time especializado de 13 agentes Claude, cada um com responsabilidades bem definidas. Eles operam via Claude Code SDK e possuem acesso apenas ao que precisam para realizar suas tarefas.

Visão Geral do Time

                        ┌─────────────────┐
                        │  Orchestrator   │
                        │  (Coordenador)  │
                        └────────┬────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        │                        │                        │
┌───────┴──────┐        ┌────────┴───────┐      ┌────────┴───────┐
│   Backend    │        │   Frontend     │      │ Infrastructure  │
│    Team      │        │    Team        │      │     Team        │
│              │        │                │      │                 │
│ api-agent    │        │ ui-agent       │      │ db-agent        │
│ auth-agent   │        │ map-agent      │      │ deploy-agent    │
│ payment-agent│        │ realtime-agent │      │ docs-agent      │
│ routing-agent│        │ pwa-agent      │      │                 │
└──────────────┘        └────────────────┘      └─────────────────┘
                                 │
                        ┌────────┴───────┐
                        │  Quality Team   │
                        │                 │
                        │ test-agent      │
                        │ security-agent  │
                        └─────────────────┘

Agentes Backend

1. `api-agent` — Especialista em FastAPI

Responsabilidade: Criação e manutenção dos endpoints FastAPI, schemas Pydantic v2, validação de dados e lógica de negócio das rotas.

Escopo: - backend/app/api/v1/ - backend/app/schemas/ - backend/app/core/

Regras: - Todos os endpoints com response_model explícito - Valores financeiros sempre em Decimal, nunca float - HTTP status codes semanticamente corretos (201 para POST criação, 204 para PUT sem corpo) - Erros sempre com HTTPException e mensagem em português

Exemplo de trabalho:

@router.post("", response_model=DeliveryOut, status_code=status.HTTP_201_CREATED)
async def create_delivery(body: DeliveryCreate, admin: RequireAdmin) -> DeliveryOut:
    ...

2. `auth-agent` — Especialista em Autenticação

Responsabilidade: Implementação do fluxo de autenticação JWT (Supabase HS256), middleware de roles, validação de tokens e segurança de acesso.

Escopo: - backend/app/core/security.py - backend/app/dependencies/ - frontend/lib/supabase/ - frontend/middleware.ts

Regras: - JWT validado via SUPABASE_JWT_SECRET (HS256), nunca confiado sem verificação - RequireAdmin e RequireDriver como Annotated dependencies - Role extraída de user_metadata.role no payload JWT - Session refresh via updateSession() no middleware Next.js

3. `payment-agent` — Especialista em ASAAS e Pagamentos

Responsabilidade: Integração com ASAAS (subcontas, transferências Pix), processamento de webhooks, gestão de carteiras e saques.

Escopo: - backend/app/services/asaas.py - backend/app/api/v1/wallets.py - backend/app/api/v1/webhooks.py

Regras: - Webhook sempre validado via HMAC-SHA256 antes de processar - Idempotency key obrigatória em transferências (usa withdrawal.id) - Saldo verificado antes de criar saque - Status do saque atualizado via webhook, nunca diretamente após chamada ASAAS

Fluxo de responsabilidade:

POST /withdraw → valida saldo → INSERT withdrawal → POST ASAAS → UPDATE asaas_id
POST /webhooks/asaas → valida HMAC → UPDATE withdrawal.status

4. `routing-agent` — Especialista em Roteamento e Mapas

Responsabilidade: Integração com OpenRouteService para cálculo de rotas, distâncias e polylines. Configuração do MapLibre GL JS no frontend.

Escopo: - backend/app/services/routing.py - frontend/components/maps/

Regras: - Coordenadas enviadas no formato [longitude, latitude] (ORS inverte o padrão lat/lng) - Distance arredondada para 2 casas decimais - Polyline em formato GeoJSON (geometry encodada) - Tiles via Stadia Maps com chave pública (NEXT_PUBLIC_STADIA_API_KEY)

Agentes Frontend

5. `ui-agent` — Especialista em Interface e Componentes

Responsabilidade: Criação de componentes React com TypeScript strict, estilização com Tailwind v4, formulários com validação Zod, e UX responsiva.

Escopo: - frontend/app/ - frontend/components/ - frontend/types/index.ts

Regras: - TypeScript strict: sem any, sem as unknown - Zod para validação de dados de API - Tailwind v4 (nova sintaxe CSS, sem tailwind.config.js) - Componentes Server quando possível, Client apenas quando necessário (use client)

6. `map-agent` — Especialista em Mapa Interativo

Responsabilidade: Implementação do mapa do admin com MapLibre GL JS, markers de motoristas, polylines de rotas e atualização em tempo real via Supabase Realtime.

Escopo: - frontend/components/maps/ - frontend/app/(admin)/map/

Regras: - MapLibre inicializado apenas no cliente (não SSR) - Markers atualizados via diff, sem re-render completo do mapa - Polyline decodificada do formato OSRM/ORS antes de renderizar - Cleanup de listeners de Realtime no useEffect cleanup

7. `realtime-agent` — Especialista em Supabase Realtime

Responsabilidade: Implementação dos canais Realtime (Broadcast e Presence), hooks de subscription, gestão de conexões e reconexão automática.

Escopo: - frontend/hooks/ - Integração com driver_locations, deliveries, wallets

Regras: - Sempre usar channel.subscribe() com status callback - Cleanup obrigatório: supabase.removeChannel(channel) no cleanup do useEffect - Presence para status online/offline dos drivers no mapa - Rate limit de GPS: máximo 1 update/10s por driver

8. `pwa-agent` — Especialista em PWA e Service Worker

Responsabilidade: Configuração do Service Worker, Web Push notifications, manifesto PWA e experiência offline básica.

Escopo: - frontend/public/sw.js - frontend/public/manifest.json - backend/app/api/v1/ (endpoint de subscription)

Regras: - VAPID public key exposta via NEXT_PUBLIC_VAPID_PUBLIC_KEY - VAPID private key exclusivamente no backend - Service Worker registrado condicionalmente ('serviceWorker' in navigator) - Notificações apenas para role = 'driver' (nova entrega disponível)

Agentes de Infraestrutura

9. `db-agent` — Especialista em Banco de Dados

Responsabilidade: Design e manutenção do schema PostgreSQL, RLS policies, índices, funções e triggers no Supabase.

Escopo: - backend/supabase/migrations/

Regras: - RLS habilitado em todas as tabelas, sem exceção - SECURITY DEFINER em funções que precisam bypassar RLS - Índices parciais para queries frequentes com WHERE clause - Migrations idempotentes (CREATE IF NOT EXISTS, ON CONFLICT DO NOTHING) - Valores financeiros como numeric(12,2), nunca float

10. `deploy-agent` — Especialista em Deploy e Vercel

Responsabilidade: Configuração dos projetos na Vercel, variáveis de ambiente por ambiente (sandbox/produção), otimização de builds e monitoramento.

Escopo: - backend/vercel.json - frontend/vercel.json - Configuração de env vars no dashboard Vercel

Regras: - Backend: @vercel/python runtime, maxLambdaSize: 15mb - Frontend: framework: nextjs, sem configuração extra necessária - Env vars de produção nunca commitadas no repositório - Preview deployments com variáveis apontando para sandbox ASAAS

11. `docs-agent` — Especialista em Documentação

Responsabilidade: Manter a documentação MkDocs atualizada, precisa e consistente com o código. Atualizar páginas quando funcionalidades mudam.

Escopo: - docs/ - mkdocs.yml

Regras: - Toda mudança de API ou schema deve refletir na documentação - Exemplos de código sempre testados e funcionando - Fórmulas matemáticas verificadas contra a implementação real - Linguagem técnica e objetiva, sem floreios

Agentes de Qualidade

12. `test-agent` — Especialista em Testes

Responsabilidade: Criação e manutenção de testes unitários (pytest), testes de integração, e coleção Bruno para testes manuais de API.

Escopo: - backend/tests/ - backend/tests/unit/ - backend/tests/integration/

Regras: - asyncio_mode = "auto" (configurado em pyproject.toml) - Mocks de Supabase e ASAAS para testes unitários - Testes de pricing cobrem edge cases (exatamente no min_km, abaixo, acima) - Fixtures reutilizáveis em conftest.py

Exemplo de teste:

# tests/unit/test_pricing.py
from decimal import Decimal
import pytest
from app.schemas.pricing import PricingConfigOut, calculate_driver_earning

@pytest.fixture
def config() -> PricingConfigOut:
    return PricingConfigOut(
        id="test-id",
        base_fare=Decimal("15.00"),
        price_per_km=Decimal("2.00"),
        min_km=Decimal("5.00"),
        updated_at="2026-01-01T00:00:00Z",
    )

def test_earning_below_min_km(config: PricingConfigOut) -> None:
    assert calculate_driver_earning(Decimal("3.00"), config) == Decimal("15.00")

def test_earning_at_min_km(config: PricingConfigOut) -> None:
    assert calculate_driver_earning(Decimal("5.00"), config) == Decimal("15.00")

def test_earning_above_min_km(config: PricingConfigOut) -> None:
    # 5 + (12 - 5) * 2 = 15 + 14 = 29
    assert calculate_driver_earning(Decimal("12.00"), config) == Decimal("29.00")

13. `security-agent` — Especialista em Segurança

Responsabilidade: Auditoria de segurança, revisão de RLS policies, validação de inputs, HMAC de webhooks, e garantia de que chaves sensíveis nunca vazam.

Escopo: - Revisão transversal de todos os arquivos - backend/app/api/v1/webhooks.py - backend/app/core/security.py

Regras: - Toda PR passa por revisão do security-agent antes de merge - Chave Pix nunca logada (apenas pix_key_type em logs) - service_role_key nunca em código frontend - Rate limiting verificado nos endpoints de localização - HMAC de webhook com compare_digest (timing-safe)

Checklist de segurança:

[ ] Nenhuma chave sensível em logs ou respostas de API
[ ] Todos os endpoints autenticados têm RequireAdmin ou RequireDriver
[ ] Webhook ASAAS valida assinatura HMAC antes de processar
[ ] RLS habilitado em todas as tabelas
[ ] Valores financeiros em Decimal (sem float)
[ ] JWT validado com algoritmo e audience corretos

Protocolo de Coordenação

O Orchestrator distribui tarefas seguindo o princípio do menor privilégio:

Recebe a tarefa do usuário
Identifica quais agentes são necessários
Distribui sub-tarefas com contexto mínimo necessário
Integra os resultados
Garante que os agentes de qualidade (test, security) revisam antes de finalizar

Agentes nunca modificam arquivos fora do seu escopo sem aprovação explícita do Orchestrator.

Time de Agentes Claude

Visão Geral do Time

Agentes Backend

1. api-agent — Especialista em FastAPI

2. auth-agent — Especialista em Autenticação

3. payment-agent — Especialista em ASAAS e Pagamentos

4. routing-agent — Especialista em Roteamento e Mapas

Agentes Frontend

5. ui-agent — Especialista em Interface e Componentes

6. map-agent — Especialista em Mapa Interativo

7. realtime-agent — Especialista em Supabase Realtime

8. pwa-agent — Especialista em PWA e Service Worker