Fluxo de Desenvolvimento¶

Do início de uma tarefa até o deploy em produção — passo a passo.

Visão Geral¶

Linear issue
    │
    ▼
branch de feature (a partir de develop)
    │
    ▼
desenvolvimento local
    │  git commit → pre-commit hooks (ruff, ty, yaml, json...)
    ▼
Pull Request → develop
    │  CI: docs-build, pre-commit, unit tests, integration tests
    │  Aprovação: 1 CODEOWNER
    ▼
develop
    │  deploy automático → ambiente de staging (Railway)
    ▼
Pull Request → main
    │  CI: tudo acima + e2e tests
    │  Aprovação: 1 CODEOWNER
    ▼
main
    │  deploy automático → produção (Railway)

1. Criar a branch¶

Sempre crie a branch a partir de develop, nunca de main:

git checkout develop
git pull origin develop
git checkout -b tipo/descricao-curta

Convenção de nomenclatura¶

{tipo}/{descricao-em-kebab-case}

Exemplos:

feat/agent-approval-workflow
fix/webhook-signature-validation
chore/update-logfire-integrations
refactor/billing-subscription-guard

Se a tarefa tem issue no Linear, inclua o identificador no branch ou no título do PR para linkar automaticamente:

feat/SPR-142-agent-approval-workflow

2. Desenvolvimento local¶

Antes de começar, garanta que o ambiente está rodando:

make db-start          # PostgreSQL local via Supabase CLI
docker run -d --name spryx-redis -p 6379:6379 redis:7-alpine  # Redis
make dev-api           # App API com hot reload

Ver Desenvolvimento Local para o setup completo.

3. Commits¶

Formato — Conventional Commits¶

tipo(escopo): descrição curta no imperativo

corpo opcional com mais contexto

Co-Authored-By: ...

Exemplos:

feat(agent): add approval request workflow

fix(billing): prevent duplicate webhook processing

chore(ci): add docs-build job to validate zensical on PRs

refactor(identity): extract tenant validation to repository

Escopo: nome do módulo afetado (agent, billing, identity, connections, etc.) ou da camada (ci, docker, deps).

Pre-commit hooks¶

Ao fazer git commit, os hooks rodam automaticamente antes de aceitar o commit:

Se um hook falhar:

# Corrigir formato automaticamente
make fix

# Verificar o que ainda tem problema
make lint

# Rodar typecheck separadamente
make typecheck

# Tentar commitar de novo
git add -p
git commit

4. Abrir Pull Request¶

Para qual branch abrir¶

Título do PR¶

Siga o mesmo formato de Conventional Commits:

feat(agent): add approval request workflow
fix(billing): prevent duplicate webhook processing

Descrição¶

Inclua no mínimo:

• O que muda — contexto da mudança, decisões não óbvias
• Como testar — como o revisor pode verificar o comportamento
• Link do Linear — se houver issue associada

Quem aprova¶

O CODEOWNERS define que todos os arquivos requerem aprovação de @ppcantidio ou @LuizHenriquerg. Na prática: 1 aprovação de CODEOWNER desbloqueia o merge.

PRs de um CODEOWNER ainda precisam de aprovação do outro.

5. CI — O que roda e o que bloqueia¶

Todos os checks abaixo rodam automaticamente ao abrir ou atualizar um PR. Nenhum merge é possível sem que todos passem.

PRs para develop¶

Os testes de integração aguardam o job Supabase Preview criar o banco isolado para a branch do PR antes de rodar.

PRs para main (adicionalmente)¶

Se um check falhar¶

1. Clique no job que falhou no GitHub para ver os logs
2. Corrija localmente, commite e faça push — o CI roda de novo automaticamente
3. Não force o merge sem todos os checks passando

6. Deploy e ambientes¶

Ambientes¶

Acompanhar o deploy¶

O deploy acontece automaticamente no Railway após o merge. Para acompanhar:

1. Abra o Railway dashboard
2. Selecione o serviço (App API, Backoffice API ou Worker)
3. A aba Deployments mostra o status em tempo real: Building, Deploying, Active
4. Logs de build e runtime disponíveis no próprio dashboard

Verificar que subiu¶

Após o deploy ficar Active:

• App API staging: GET /health ou abrir o Swagger em /docs
• Logfire: verifique se novos spans estão chegando do ambiente correto

7. Hotfix — Correção urgente em produção¶

Use apenas quando main tem um bug crítico que não pode esperar o ciclo normal de develop → main.

# 1. Crie a branch a partir de main (não develop)
git checkout main
git pull origin main
git checkout -b fix/nome-do-bug-critico

# 2. Faça a correção mínima necessária
# 3. Abra PR direto para main
# 4. Após merge em main, backporte para develop também
git checkout develop
git pull origin develop
git merge main
git push origin develop

Checklist antes de abrir o PR¶

[ ] Branch criada a partir de develop (ou main, se hotfix)
[ ] make lint passou sem erros
[ ] make typecheck passou sem erros
[ ] make test-unit passou
[ ] make test-integration passou (opcional local, mas roda no CI)
[ ] Commits seguem Conventional Commits
[ ] Título do PR segue o formato convencional
[ ] Descrição explica o que muda e como testar
[ ] Issue do Linear linkada (se aplicável)