☁️ Codex Cloud: Agente Roda no Servidor da OpenAI
Cloud é um ambiente isolado no servidor da OpenAI que executa o agente sem depender do seu laptop. Você descreve a tarefa, fecha o notebook, e horas depois encontra a PR pronta esperando revisão.
🔄 Local vs Cloud — Fluxo Operacional
📊 Por que isso importa pra fábrica
Quando você opera 1 SaaS por semana com 10 clientes ativos, o gargalo não é digitação — é tempo da sua máquina ligada. Cloud paraleliza N tarefas sem ocupar seu local. Enquanto Cloud builda um vertical novo, você atende cliente. À noite, desliga o laptop e a obra continua. Throughput dobra sem cobrar mais horas suas.
🔗 Conectando ao GitHub
Setup é OAuth + GitHub App + escolha fina de repos autorizados. Calibrar agora evita acidente (agente com acesso a repo errado) e libera todos os recursos pra frente (Cloud, @codex review).
📋 Checklist do Setup
⚠️ Erro caro de setup
Autorizar "All repositories" em organização com clientes pagantes deixa o agente acessível a todo repo — incluindo os privados de outros projetos. Use sempre fine-grained access com lista explícita. Quando criar um repo novo, volte e adicione manualmente. O minuto extra economiza acidentes que custam clientes.
📤 Delegando uma Tarefa ao Cloud
No App, você dirige em tempo real e corrige no caminho. No Cloud, o agente está sozinho — então a descrição precisa ser blindada: contexto, escopo, critério de pronto e ramo de destino, tudo explícito.
📝 Template de Brief para Cloud
## Tarefa
Implementar lembrete automático de consulta no InboxAI-Clinica.
## Contexto
- Repo: inema/inboxai-clinica (branch base: main)
- Stack: Next.js 15 + Convex + Tailwind
- Convenção: AGENTS.md tem padrões; siga-os.
## Escopo
1. Adicionar tabela `appointments` no schema Convex.
2. Criar cron job `notifyAppointmentTomorrow` que dispara WhatsApp.
3. UI: nova página /agenda com lista de próximos 7 dias.
## Fora de escopo
- Não alterar layout do dashboard existente.
- Não tocar em integrações de pagamento.
## Definition of Done
- [ ] Schema migrado e tipado.
- [ ] Cron rodando às 18h America/Sao_Paulo.
- [ ] UI renderiza sem erros.
- [ ] Testes passando (npm test).
- [ ] PR aberta para `develop` com Summary + Test Plan.
## Branch
feat/clinica-lembretes💡 Regra do contexto async
Cada ambiguidade não resolvida no brief vira 1h de retrabalho. Vale 5 minutos a mais escrevendo "fora de escopo" e "definition of done" do que descobrir que o agente reescreveu o que não devia. Templates são patrimônio: salve em .codex/briefs/ no repo.
📋 PR Automático com Summary e Test Plan
Cloud não devolve só um diff — devolve PR completa: branch nova, commits semânticos, descrição estruturada. Esse é o padrão profissional que destrava revisão de cliente, equipe e do próprio @codex review.
📄 Estrutura padrão da PR
feat(clinica): lembretes automáticos de consulta via WhatsApp
## Summary
- Nova tabela `appointments` (paciente, médico, datetime, status).
- Cron diário às 18h envia WhatsApp para consultas do dia seguinte.
- Página /agenda lista próximos 7 dias com filtros.
## Test Plan
- [ ] Rodar `npm test` (cobre schema e lógica do cron).
- [ ] Criar consulta para amanhã via UI; aguardar 18h e validar envio.
- [ ] Cancelar consulta; confirmar que cron pula a entrada.
- [ ] Testar em Convex dev antes de merge para develop.
## Out of scope
- Não cobre lembrete por e-mail (issue #142 acompanha).✅ PR boa
- • Título conventional commits
- • Summary objetivo (3–5 bullets)
- • Test Plan acionável
- • Links de issues relacionadas
- • Out of scope explícito
❌ PR ruim
- • Título "atualização"
- • 30 commits desorganizados
- • Sem descrição
- • Mistura refactor + feature
- • Quebra testes existentes
🤖 @codex review: A IA Revisando a IA
Comente @codex review em qualquer PR. Um agente independente lê o diff completo, identifica bugs, riscos de segurança e sugere refactors — direto nos comentários do GitHub. Segundo par de olhos automatizado.
🔍 O que o @codex review olha
🐛 Bugs lógicos
Off-by-one, null deref, race conditions, validação ausente.
🔐 Segurança
Secrets em código, SQL injection, permissões expostas, CORS.
📐 Padrões do projeto
Aderência ao AGENTS.md, naming, estrutura de pastas.
⚡ Performance
Loops aninhados, N+1 queries, render desnecessário.
📌 Workflow real
Cloud abre PR → você comenta @codex review → 2 minutos depois aparece review estruturado → você lê só os pontos sinalizados como "high severity" → decide aceitar ou pedir ajuste. De 30 minutos de revisão humana, sobram 5. O resto é decisão, não leitura.
👨💻 Workflow Profissional: Solo + Cloud + Review
A combinação que multiplica throughput sem virar caos: você dispara N tarefas no Cloud, cada uma vira PR, cada PR passa pelo @codex review. Você só atua nos pontos sinalizados — o resto roda sozinho.
🏭 Pipeline do Solo Dev Moderno
🚀 O que isso destrava
Sem essa orquestração, você executa 1 tarefa por vez sequencialmente. Com ela, opera 4–8 em paralelo com revisão automatizada de qualidade — o que era trabalho de equipe vira routine de 2h diárias. É a diferença entre cobrar R$ 5k de freela e operar R$ 15k/mês recorrente com 10 clientes.
🇧🇷 Estudos de Caso: Codex Cloud + GitHub PRs em Equipe Solo
Três devs solo brasileiros que escalaram operação combinando Codex Cloud com revisão automatizada via @codex review nas PRs.
DataSenge Consulting
São Paulo · Consultoria de dadosDetalhe técnico: automation configurada para revisar 100% das PRs com @codex review antes do humano abrir o diff — humano só vê PR já triada.
Aldeia Digital
Porto Alegre · AgênciaDetalhe técnico: branches isoladas por feature + PRs auto-revisadas pelo @codex review eliminam o risco de cross-contamination entre projetos paralelos.
Cardápio Smart
Salvador · SaaS para restaurantesDetalhe técnico: @codex review identificou 12 bugs antes de chegar na revisão humana — economia direta de horas e proteção contra regressões silenciosas.
✅ O que Aprendemos
Próximo Módulo:
6.2 — Automations: agentes recorrentes que rodam por cron, geram relatório semanal, triagem de issues e dependabot review — sem você precisar lembrar.