Dia a dia de desenvolvimento¶

Rodar¶

Cada app roda no host com hot reload, em terminais separados:

make local-up         # PostgreSQL + Redis + Mailpit + Caddy em container (uma vez por sessão)
make api-dev          # uvicorn  :8000
make worker-dev       # worker da fila (arq) — consulta ao bureau e jobs agendados
make web-dev          # vite     :5173
make api-wiki         # sphinx   :8001  (opcional — documentação técnica gerada de docstrings)

make test-web         # suíte unitária do web (ARQ=<caminho> roda um arquivo só)
make test             # vitest do web, depois pytest da API (spec 0047)
make lint             # ruff na API + tsc no web + invariantes de estado
make preflight        # verificações determinísticas antes de chamar um revisor
make local-down       # encerra a stack (dados preservados)

make help lista todos os alvos. make preflight verifica, só nas linhas que a branch acrescentou, o que não exige julgamento (Swagger completo, downgrade real, CommitRoute, data-testid, meta-testes do repositório e a suíte do web quando a branch tocou o apps/web) — segundos nas branches que não mexem no web, ~1m30 nas que mexem. Rode-o antes de pedir qualquer revisão.

Como o trabalho entra no repositório¶

Desde 2026-10-15 o trabalho é conduzido pelo plugin Superpowers — os skills próprios /spec, /fix e /tweak foram removidos. O repositório acrescenta ao plugin duas coisas: onde o trabalho fica registrado e a régua da revisão (as rubricas de .claude/rubrics/). Não se mexe direto na main.

O ajuste direto não gera documento: ../tweaks/ é histórico do tempo do /tweak. Mexeu em permissão, isolamento, migration ou contrato de API, não é ajuste direto, qualquer que seja o tamanho do diff.

A fonte de tudo isso — como escolher na fronteira, onde o Superpowers grava (e onde não grava), a numeração, as rubricas e quando a revisão aprova — é a seção Fluxo de desenvolvimento do CLAUDE.md da raiz; o deploy está em ../operations/deployment.md.

A ordem dentro de qualquer trabalho que atravesse os apps é sempre a mesma — o contrato desce da API: apps/api → apps/web → apps/e2e. Nada é commitado, mesclado ou empurrado sem pedido explícito; a única exceção é a tag de versão que o /ship empurra depois de um deploy verificado.

Testes¶

• A suíte a rodar segue o que a branch tocou: só apps/api → o pytest; só apps/web → make test-web; os dois → make test (o web primeiro; falhando, o pytest não roda).
• make test-web ARQ=<caminho> — um arquivo da suíte do web, ~10s. É o que se roda no meio de uma correção, inclusive para o red-green: reverta, veja vermelho, restaure.
• Teste a escrever acompanha o código — apps/api/tests/ na API, *.test.tsx ao lado do arquivo no web, e e2e quando o comportamento pede prova de fluxo.
• e2e — só os specs das telas que a branch alterou, e sempre contra o dev-remote: /devremote-rebuild primeiro (as imagens embutem o código), depois cd apps/e2e && npx playwright test tests/e2e/<spec>.spec.ts --project=chromium. make e2e inteiro nunca roda por iniciativa própria — quando o diff parece atravessar telas além das tocadas, a suíte completa é recomendação ao usuário. Nunca contra um ambiente isolado montado à mão. Ver ../operations/troubleshooting.md para as armadilhas conhecidas.

Nesta máquina, especificamente¶

Não há uv nem apps/api/.venv no host desta máquina — a parte do pytest de make test (cd apps/api && uv run pytest) falha aqui. O pytest da API roda pelo container do dev-remote: docker exec garantora-devremote-api-1 uv run pytest, e como a imagem embute o código, copie antes o arquivo alterado com docker cp (procedimento no apps/api/CLAUDE.md). make test-count já escolhe sozinho entre host e container — use-o como referência de como decidir. A suíte do web (make test-web) roda aqui normalmente.