standards

Standards — escala, performance, segurança, UX premium

Regras transversais aos 4 projetos. O AGENTS.md/CLAUDE.md de cada repo tem precedência em conflitos — estes são os mínimos globais.

Escala (worktodo e singolo: pensar em milhares de usuários)

• Toda query nova: tem índice que a suporta? Roda em O(linhas retornadas), não O(tabela)? Em Supabase, explain em queries de caminho quente.
• N+1 é bloqueante: loops com query/fetch dentro nunca passam de review. Batch, join ou view.
• RLS: política nova ou alterada deve ser testada como usuário autenticado real (SET request.jwt.claims), e avaliada por custo (políticas com subquery por linha matam performance em escala).
• Paginação por padrão em qualquer listagem que cresce com uso. Sem select * ilimitado.
• Custo por usuário: feature que chama IA/storage/push por usuário ativo → estimar custo mensal em 1k/10k usuários antes de aprovar o plano.

Performance (especialmente mobile)

• Caminho crítico de abertura do app/página: nada de trabalho síncrono pesado, fetch em cascata ou bundle desnecessário.
• React/RN: estado no nível mais baixo possível; listas longas viram virtualizadas; memo só onde medido.
• Next.js: Server Components first; 'use client' apenas quando necessário; imagens otimizadas.
• Animações: 60fps ou nada — transform/opacity, nunca layout em animação contínua.

Segurança (mínimos inegociáveis)

• Toda mudança de superfície (rota, RPC, webhook, storage) lista quem pode acessar e por quê. Default: negar.
• Segredos nunca em código/cliente. Validação de input com Zod (ou equivalente do repo) em toda fronteira.
• Writes owner-only passam user_id explícito quando o schema não tem DEFAULT auth.uid().
• Mudança em auth/RLS/billing/migrations = área sensível: exige plano aprovado + verificação empírica, sem exceção.

UX premium (simplicidade é o produto)

• Todo estado existe: loading (skeleton, não spinner genérico quando possível), empty (com ação), erro (com recuperação). Nunca tela branca.
• Dark mode via tokens semânticos, nunca cor hardcoded.
• Feedback imediato a toda ação do usuário (otimista quando seguro); nada de botão que "não responde".
• Menos é mais: cada elemento na tela precisa justificar existência. Na dúvida, corte.

Tickets Jira (worktodo, singolo) — o reporter NÃO é fonte confiável

Os tickets são escritos pelos sócios/testers do Matheus: pessoas sem conhecimento técnico, muitas vezes descrevendo o problema com ajuda de uma AI que não tem acesso ao código. Consequências práticas:

• Diagnósticos e "soluções" propostas no ticket são hipóteses, nunca veredito (ex: "está hardcoded", "erro de roteamento") — podem induzir a erro. Verifique no código antes de aceitar qualquer afirmação técnica.
• Foque no problema real (o sintoma observado pelo usuário), não na solução sugerida. Reproduza primeiro; o fix certo pode estar em outro lugar.
• Separe: regressão real × mismatch de expectativa (feature funcionando como projetada) × scope creep disfarçado de bug.
• Leia os comentários em ordem cronológica: o problema realmente aberto costuma ser um trailing issue, não o título do ticket.
• Títulos hiperbólicos ("CRÍTICO", "Inoperância Total") não definem prioridade técnica — a investigação define.

Ao comentar/mover cards no Jira: linguagem simples para leigos, e só marque como resolvido com prova empírica (não "compilou").

Loop de validação (rodar após cada mudança significativa)

Repo	Gate
worktodo	yarn validate
clinicas	npm run validate (rápido: npm run ai:audit)
monitor-imobiliario	pnpm check (raiz); SaaS: tooling em monitor-imobiliario-saas/
singolo / default	npx tsc --noEmit && npx eslint <alterados> && npx vitest run

O type system é o validador mais barato — rode tsc --noEmit cedo e sempre. Teste passando é a ground truth. Compilar não é funcionar: "done" exige prova runtime (ver /flow:ship).