Como Construir Sua Fábrica de Software com Codex, CI e Testes de API Apidog

O diagrama de Gergely Orosz da fábrica de software interna da OpenAI tem circulado esta semana: um desenvolvedor registra um resultado, o Codex escreve o código, uma frota de agentes de revisão especialistas discute sobre o risco, e um agente supervisiona a implantação enquanto monitora painéis que ele próprio construiu. É também, para as partes que mais importam para os próprios engenheiros da OpenAI, uma descrição de ferramentas internas que você não pode instalar.

O Perf Factory, Sevbot e a implantação agêntica com painéis auto-construídos rodam na própria pilha de observabilidade da OpenAI e não fazem parte do produto Codex que você pode comprar. O que você pode construir esta semana é um ciclo menor que ainda realiza um trabalho real: um desenvolvedor define o resultado como uma issue, o Codex trabalha na branch, o CI verifica se a mudança realmente se comporta como esperado, um ou dois agentes revisores a examinam, e um humano aprova qualquer coisa arriscada antes de ser lançada por trás de uma feature flag. Tudo isso depende de um detalhe que o diagrama original omite: "CI passa" só significa algo se o CI verificar as coisas certas. Para uma API, isso significa testar a API, não apenas o código que a chama.

O que o diagrama acerta (e o que você não pode copiar)

A parte pública do artigo do Pragmatic Engineer descreve um ciclo central onde o Codex “realiza uma série de mudanças no código até atingir seu objetivo e então verifica se o software funciona como deveria”. Áreas de baixo risco podem ser aprovadas automaticamente; mudanças de alto risco recebem mais revisão de IA ou uma aprovação humana obrigatória. Essa estrutura — propor, verificar, revisar por nível de risco — é portátil. Equipes a têm aproximado com bots de pull request e portões de CI por anos; agentes apenas tornam o ciclo mais rápido e menos supervisionado.

O que não é portátil é a maquinaria interna que o envolve. O Perf Factory filtra alertas e painéis para encontrar regressões de latência e propor correções. O Sevbot investiga incidentes e responde a perguntas no Slack, embora não execute mitigações por si mesmo. A implantação agêntica monitora uma mudança na produção e constrói seu próprio monitoramento usando a pilha de telemetria interna da OpenAI. Nenhuma dessas três funcionalidades é enviada no produto externo Codex. O que foi lançado é o aplicativo de desktop, o comando /goal para tarefas de longa duração e os plugins e habilidades de função que você configura. A página do produto Codex da OpenAI cobre o que está realmente disponível.

O ciclo de cinco etapas que você pode executar esta semana

Uma versão reduzida se parece com isto:

1. Um desenvolvedor registra o resultado como uma issue. Não uma lista de tarefas, mas uma descrição do estado final: “pedidos podem conter um código de desconto opcional que reduz o total.” Entregar essa mesma issue do GitHub a um Agente no Sharkly é a integração lançada: a issue se torna uma Tarefa, e a execução retorna como um PR em vez de um ticket separado para conciliar. Atualmente, é gratuito para organizações de até 10 pessoas.
2. O Codex trabalha na branch com /goal. Conforme abordado em como o comando /goal impulsiona execuções autônomas do Codex e Claude Code, você dá ao agente um objetivo e o deixa iterar por conta própria até que o objetivo seja atingido.
3. O CI executa build, testes unitários e cenários de teste de API. Esta é a etapa que a maioria das equipes pula ou constrói pela metade.
4. Um ou dois agentes revisores verificam o diff, e um humano revisa qualquer coisa acima de baixo risco. Ferramentas de revisão de código de IA podem detectar muitos problemas antes que um humano sequer abra o PR. No Sharkly, é aqui que o "Pronto para Lançamento" faz o trabalho: um humano precisa mover a tarefa desse status antes que algo chegue a "Concluído", e um Agente revisor separado pode estar na mesma Equipe que aquele que escreveu o código.
5. Implante por trás de uma feature flag, para que uma fusão problemática seja um switch, não um incidente.

A Etapa 3 é onde o ciclo funciona ou mente para você.

Por que o CI precisa testar a API, não apenas o código

O recurso de revisão do próprio Codex, abordado em como funciona a revisão de código do Codex, lê o diff e sinaliza problemas óbvios. Ele não executa seu serviço e verifica o que ele retorna. Testes unitários, se o agente os escreveu ou manteve, principalmente verificam se o código faz o que ele pretende, o que não é o mesmo que verificar se a API faz o que o contrato promete. Um agente editando um handler pode passar em todos os testes unitários enquanto silenciosamente quebra a resposta da qual todo cliente depende.

Digamos que você execute uma API de pedidos. POST /api/orders cria um pedido e retorna seu registro; GET /api/orders/{id} busca um pelo ID. Você mantém uma especificação OpenAPI para ambos, e construiu cenários de teste do Apidog contra ela: crie um pedido, recupere-o e verifique quatro coisas que um teste unitário tipicamente não fará:

• Códigos de status. POST /api/orders retorna 201, não 200 ou um 500 silencioso em um caso de borda de validação.
• Esquema de resposta contra a especificação OpenAPI. O campo total_amount permanece um número, status permanece um dos valores de enumeração que você definiu, e nenhum campo do qual os clientes dependem desaparece ou é renomeado silenciosamente.
• Falhas de autenticação. Uma requisição sem um token válido retorna 401, não um 200 com um corpo vazio, o que é uma regressão surpreendentemente comum.
• Um limite de latência. O cenário afirma que a resposta retorna abaixo de um limite definido, de modo que uma mudança que adiciona uma chamada de banco de dados não agrupada dentro do handler é detectada antes que um cliente perceba.

Essas são exatamente as verificações que uma refatoração em nível de handler pode quebrar silenciosamente enquanto todos os testes unitários ainda passam, porque os testes unitários geralmente simulam o limite que o cenário da API realmente exercita.

Integrando-o no pipeline

Você já executa a versão CLI desses cenários localmente se seguiu como usar o CLI do Apidog no Codex. O mesmo comando é executado no CI. Um job do GitHub Actions que constrói, executa testes unitários e depois executa o cenário do Apidog se parece com isto:

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  build-test-verify:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build and run unit tests
        run: npm run build && npm test

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run orders API test scenario
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run \
            --access-token $APIDOG_ACCESS_TOKEN \
            -t 88214 \
            -e 3301 \
            -r cli,junit

      - name: Upload Apidog reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-reports
          path: apidog-reports/

Os valores -t e -e são seus IDs reais de cenário e ambiente do Apidog, não placeholders que você inventa. A referência do comando apidog run cobre todas as flags, e os relatórios de teste do Apidog CLI explicam a saída JUnit que o job carrega. apidog run sai com código diferente de zero em qualquer asserção falha, então o GitHub Actions marca o job como falho da mesma forma que faria para um teste unitário falho.

Como se parece o prompt do agente

O objetivo do /goal é que você descreva o resultado e a condição de saída, e o Codex itere sem que você aprove cada etapa. Para o exemplo do código de desconto, um prompt razoável é:

/goal Add an optional `discount_code` field to POST /api/orders. Validate it
against the promotions service and apply the discount to `total_amount` in
the response. Do not rename or remove any existing response field. Run
`npm test` and `apidog run --access-token $APIDOG_ACCESS_TOKEN -t 88214 -e 3301
-r cli` before you finish. Both must exit 0. If the Apidog run fails, read the
failing assertion and fix the handler, not the test.

Essa última linha importa. Um agente sob pressão para deixar uma verificação verde às vezes editará a asserção em vez do bug. Dizer explicitamente qual lado do loop deve ser corrigido mantém o cenário de teste como a fonte da verdade, e não um obstáculo a ser contornado.

Quando o agente quebra o contrato

O Codex adiciona o campo de desconto e, no processo, renomeia total_amount para totalAmount porque essa é a convenção em um arquivo que ele leu por perto. Os testes unitários ainda passam; eles verificam a matemática do desconto, não o nome do campo. A build é bem-sucedida. Então o cenário do Apidog roda no CI, valida a resposta contra a especificação OpenAPI e falha: a especificação diz total_amount, a resposta agora tem totalAmount, e a asserção de esquema a detecta imediatamente.

O CI relata uma saída diferente de zero e aponta para a asserção de esquema falha na saída JUnit. O Codex lê a falha, vê que a renomeação é a causa e a reverte, mantendo a lógica de desconto. O cenário passa, a build fica verde, e o pull request avança para revisão com uma garantia real por trás da palavra "passando". Sem a verificação em nível de API, essa renomeação seria enviada, e todo cliente que analisa total_amount seria quebrado no próximo lançamento.

Classificação de risco que você pode basear na especificação

Em vez de uma vaga sensação do que conta como baixo risco, vincule sua classificação de risco ao diff OpenAPI. Uma mudança que adiciona um campo opcional com um valor padrão é candidata a auto-mesclagem uma vez que os testes passem. Uma mudança que remove um campo, renomeia um, ou altera um código de status nunca é de baixo risco, independentemente do restante do diff. Essa única regra captura a maioria do que um agente de revisão especialista sinalizaria de qualquer forma. Direcione tudo o que a regra sinaliza para um revisor humano ou para uma segunda passada de uma ferramenta de revisão de código de IA antes da mesclagem.

Envie por trás de uma flag, não para o vazio

Uma vez que uma mudança seja aprovada pelo CI e revisão, implante-a por trás de uma feature flag em vez de diretamente para todos os usuários. Este é o substituto barato para a etapa de implantação agêntica da OpenAI: nenhum agente supervisionando o lançamento ou construindo seus próprios painéis. Uma flag que começa com 5% do tráfego e uma pessoa que verifica as taxas de erro antes de passá-la para 100% oferece a maior parte da segurança sem nenhuma das ferramentas internas. Se algo estiver errado, você desativa a flag em vez de reverter uma mesclagem sob pressão.

Um andaime que já existe

Você não precisa conectar todas as cinco etapas do zero. orchflows é um projeto de código aberto que apareceu nas respostas ao thread de Orosz: um comando /software-factory licenciado pelo MIT para Claude Code e Codex, construído em torno de um pequeno número de habilidades reutilizáveis. É um andaime inicial, não um substituto para as etapas de CI e revisão mencionadas acima; você ainda o aponta para seus próprios cenários de teste e regras de risco.

O que evitar construir

Não tente reproduzir o Perf Factory, Sevbot ou a implantação agêntica com painéis auto-construídos. Eles são sistemas internos da OpenAI conectados a telemetrias que a maioria das equipes não executa. Humanos na OpenAI ainda definem resultados, aprovam mudanças de alto risco, autorizam mitigações de incidentes e estão de plantão; como a OpenAI colocou, “o plantão não é coisa do passado.” Copie as partes do ciclo que são apenas boa disciplina de engenharia: verifique antes de mesclar, classifique o risco pelo que realmente mudou e mantenha um humano em qualquer coisa que não seja obviamente segura.

Coloque o ciclo para rodar

Comece com a etapa de CI; ela torna todas as outras etapas confiáveis. Construa seu cenário de teste de API de pedidos no Apidog, cobrindo códigos de status, esquema, autenticação e um orçamento de latência. Conecte-o ao seu pipeline com o CLI, aponte /goal para uma issue real e deixe o Codex iterar contra uma verificação que realmente afirma o comportamento da API, em vez de confiar na palavra do agente. Baixe o Apidog para construir o primeiro cenário e, em seguida, adicione as etapas de revisão e flag quando o ciclo se provar.