Quatro fluxos de trabalho diários comuns: Exploração, correção de bugs, refatoração e escrita de testes

📚 Navegação da Série: Anterior 13 · Como escrever Prompts ensina você a 'como falar' — dividindo necessidades vagas in instruções precisas que o Codex compreende. Esta parte foca na aplicação prática: 80% do trabalho diário consiste nessas quatro categorias, e eu te darei um fluxo que você pode copiar diretamente para cada uma, bastando preencher as lacunas para usar. Próxima parte 15 · Permissões, sandbox e aprovações.

Ouça uma conversa rápida. Na semana passada, um colega que acabou de migrar para o Codex me perguntou no grupo:

「Pedi para ele corrigir um bug, ele sumiu com o erro rapidinho e eu enviei. Mas no dia seguinte o mesmo problema voltou a aparecer, o que aconteceu?」

Eu perguntei: 「Você pediu para ele encontrar a causa raiz primeiro? E adicionou testes de regressão?」

Ele: 「...ah? Corrigir um bug não é só sumir com a mensagem de erro?」

O problema está exatamente aí. Ele considerou que 'o erro sumiu' significava que 'o problema foi resolvido', sem travar aquele bug. Na verdade, exploração, correção de bugs, refatoração e escrita de testes possuem abordagens fixas — se o roteiro estiver correto, o Codex trabalha rápido e de forma estável; se estiver errado, ele resolve na superfície, mas deixa uma armadilha por baixo.

A seção anterior ensinou a técnica geral de comunicação, e esta parte aplicará isso aos quatro cenários mais frequentes. Após usar o Codex por mais de meio ano, o que consolidei foram estes quatro fluxos de trabalho, e cada um deles respeita a própria natureza do Codex — ele consegue ver os arquivos abertos na IDE, mas no CLI você precisa mencioná-los com @; ele é excelente em tarefas que 'consegue validar sozinho', então você precisa criar caminhos para essa validação.

Ao ler esta parte, você obterá:

• Um fluxo de trabalho diretamente copiável para cada uma das quatro tarefas comuns (exploração / correção de bugs / refatoração / escrita de testes), detalhando as diferenças entre a execução na IDE e na CLI
• Os conceitos fundamentais de 'por que fazer assim' para cada categoria, em vez de apenas memorizar templates
• Uma tabela comparativa resumindo as quatro tarefas no final do documento
• Um caso prático completo com saída esperada para você seguir (passando por todo o fluxo de correção de um bug real)

⚠️ As menções abaixo a comandos específicos, comandos de barra e comportamentos padrão são baseadas na documentação oficial do Codex; nomes de modelos e textos de interface que mudam com as versões devem seguir o que for exibido localmente, pois esta parte não os fixa.

---

01 Identifique primeiro: Quatro tarefas, quatro ferramentas

Antes de começar, entenda a 'personalidade' de cada uma dessas quatro tarefas. Elas exigem abordagens totalmente diferentes do Codex; usar o fluxo errado reduz drasticamente a eficiência.

Analogia: Quatro facas na cozinha, cada uma com seu uso específico. A faca para filetar peixe é diferente da faca de açougueiro para cortar costelas. Se você usar a de peixe para cortar ossos, com certeza vai estragar a lâmina. Exploração, correção de bugs, refatoração e escrita de testes são como facas diferentes — a questão não é 'saber usar o Codex', mas 'saber qual ferramenta usar para este trabalho'.

A diferença fundamental entre elas está em uma dimensão: esta tarefa altera o seu código?

Tarefa	Altera o código?	O que o Codex faz principalmente	O que você mais deve monitorar
Explorar código	Não (apenas leitura)	Lê os arquivos e te explica	Se a explicação dele está correta
Corrigir bug	Sim	Reproduz + identifica causa raiz + corrige	Se encontrou a causa raiz e se há testes de regressão
Refatorar	Sim (comportamento inalterado)	Reescreve mantendo equivalência	Se o comportamento externo mudou após a alteração
Escrever testes	Adiciona arquivos	Gera testes + cobre casos limite	Se os casos limite foram totalmente cobertos

Percebeu? A exploração tem risco zero (ele lê, mas não escreve), então você pode perguntar à vontade; correção de bugs e refatoração exigem alterações, por isso deixe-o explicar antes de alterar; a escrita de testes fica no meio do caminho, pois cria arquivos novos sem tocar no código existente, mas você deve garantir que ele não seja preguiçoso e teste apenas o 'caminho feliz'.

Há também uma regra geral que serve para as quatro categorias, tirada da documentação oficial:

O Codex entrega melhor qualidade quando consegue validar seu próprio trabalho. Dê a ele as etapas de reprodução, as formas de validação, os comandos de lint e de testes — com isso ele tem parâmetros para trabalhar, em vez de dar a tarefa por encerrada ao 'parecer correto'.

Esta frase é a fundação desses quatro fluxos. As próximas quatro seções basicamente respondem a uma única pergunta — como criar um caminho de validação próprio para cada uma dessas tarefas com o Codex.

💡 Resumo em uma frase: Divida as quatro tarefas pela característica de 'alterar ou não o código' — a exploração tem risco zero e pode ser feita livremente, enquanto as tarefas que alteram o código exigem que ele explique antes de agir; além disso, sempre crie um caminho para ele validar o próprio trabalho.

Esta imagem coloca as quatro tarefas lado a lado para comparação: cada célula mostra a característica de 'alteração de código', a abordagem principal e o ponto que você deve monitorar — as próximas seções detalharão cada um desses fluxos.

---

02 Explorar código desconhecido: Do geral ao específico, perguntando em três níveis

Primeiro, o cenário mais comum: você assume um projeto totalmente novo e precisa entendê-lo.

Como você fazia isso antes? Abria pastas, olhava para dezenas de diretórios sem rumo, entrava em um por um e, depois de duas horas, continuava confuso. Agora não precisa mais disso — o Codex trata o seu projeto como área de trabalho, consegue ler todo o código e você só precisa perguntar.

Analogia: Entrar em um shopping novo. Primeiro olhe o mapa geral, depois localize a loja específica e, finalmente, siga a rota até lá. Você não entra correndo e vasculhando qualquer prateleira; primeiro olha no saguão para entender 'quantos andares tem o shopping e o que vende em cada um' (arquitetura geral), depois localiza 'em qual andar e seção fica a loja de departamentos' (localizar módulo) e, por fim, segue a rota do ponto de entrada até lá (rastrear o fluxo). Do macro para o micro, da visão geral para o detalhe, esse é o fluxo padrão de exploração.

Aqui, há um ponto crítico sobre como fazer essas perguntas em três níveis — a extensão de IDE e a CLI do Codex obtêm contexto de formas diferentes, e o Claude Code também tem suas particularidades: enquanto o CLI do Claude Code detecta o contexto de todo o projeto automaticamente (com base no CLAUDE.md e na área de trabalho), o CLI do Codex não faz isso — ele exige que você mencione os arquivos com @ para que consiga 'enxergar' o que você quer que ele veja.

A extensão da IDE inclui automaticamente os arquivos abertos e o código selecionado no contexto; mas na CLI do Codex, você geralmente precisa usar @ para indicar o caminho do arquivo (ou usar /mention para anexar um arquivo específico).

Ou seja — ao explorar na IDE, abra os arquivos relevantes e selecione o código de interesse antes de perguntar; na CLI, indique o arquivo usando @nome_do_arquivo. Essa é a diferença fundamental apontada oficialmente, caso contrário ele não 'verá' o que você precisa que ele avalie.

Como perguntar na IDE (exploração local mais rápida)

Abra os arquivos mais relevantes, selecione a seção de código desejada (opcional, mas altamente recomendado) e pergunte. O prompt oficial de exploração é assim:

Explique como a requisição flui pelo trecho de código que selecionei.

Por favor, inclua:
- Uma breve explicação do que cada módulo envolvido faz
- Quais dados são validados e onde ocorre essa validação
- Um ou dois pontos de atenção ao alterar esta seção

Após a resposta, para confirmar rapidamente o que ele explicou, peça uma lista de verificação de apoio:

Resuma este fluxo de requisição em uma lista numerada de etapas e liste os arquivos envolvidos.

Como perguntar na CLI (quando precisar de logs em texto e comandos de shell)

Inicie a sessão interativa:

codex

E pergunte indicando os arquivos com @ (esta é a maior diferença entre a CLI e a IDE — você precisa apontar os arquivos, ele não os lê sozinho):

Quero entender o protocolo usado por este serviço. Leia @foo.ts @schema.ts,
explique sua estrutura de dados e o fluxo de "requisição / resposta", focando em quais campos são obrigatórios,
quais são opcionais e as regras de compatibilidade com versões anteriores.

Aqui vai um hábito seguro que uso sempre que assumo um novo projeto: durante a fase de exploração, mude a permissão para apenas leitura. Na seção 12 · Comandos de barra e atalhos, falamos sobre /permissions; ao explorar, mude para Read Only (Apenas Leitura) — garantindo que ele apenas leia e explique, sem fazer nenhuma alteração de código por impulso. A exploração deve ter risco zero, e fechar essa torneira traz total tranquilidade.

No ano passado, assumi um projeto legado em Go com 30 mil linhas de código e fiz exatamente isso: primeiro, usei a CLI e @ nos arquivos de entrada para perguntar sobre 'a arquitetura geral e os principais módulos' para entender a divisão de serviços; depois, localizei onde ficava cada parte usando perguntas como 'onde está o código responsável pela função X'; por fim, selecionei caminhos críticos e pedi para ele 'resumir o fluxo da requisição em passos numerados'. Entendi o projeto em meio período, algo que antes levaria dois ou três dias.

Aqui está a tabela de fluxo de exploração para usar de guia na IDE e na CLI:

Etapa	Extensão da IDE	CLI
1. Fornecer contexto	Abra os arquivos relevantes e selecione o trecho de código	Mencione com @nome_do_arquivo ou anexe com /mention
2. Perguntar sobre a arquitetura	「Visão geral da arquitetura, qual a responsabilidade de cada módulo principal」	Igual à esquerda, com os arquivos indicados por @
3. Localizar módulos	「Em quais arquivos fica o código responsável por [recurso]」	Igual à esquerda
4. Rastrear fluxo	「Rastreie a rota completa para [determinado fluxo]」	Igual à esquerda
5. Solicitar entregável de validação	「Resuma em passos numerados + lista de arquivos envolvidos」	Igual à esquerda
Durante todo o tempo	Evite alterações de código	Mude para Read Only para travar como apenas leitura

💡 Resumo em uma frase: O ritmo da exploração é único — da arquitetura geral para arquivos específicos e, finalmente, para a rota de execução, perguntando em três níveis de cima para baixo; lembre-se: a IDE lê os arquivos abertos, enquanto a CLI precisa que você os indique com @, e manter o modo apenas leitura é o caminho mais seguro.

---

03 Corrigir bug: Reproduzir → Identificar causa raiz → Alterar → Validar

Corrigir bugs é outra atividade frequente e também a que mais causa problemas — o colega do início do texto caiu justamente nessa armadilha.

Por que é fácil errar? Porque o erro mais comum dos iniciantes é: enviar um erro com a frase 'me ajude a consertar', e o Codex responder com uma alteração que apenas 'faz o erro sumir'. Note que 'fazer o erro sumir' não significa 'resolver o problema' — muitas vezes, isso apenas esconde o sintoma enquanto a causa raiz continua lá, pronta para quebrar de outra forma depois.

Analogia: Vazamento de cano, você não pode apenas colocar um balde embaixo. Diante de uma poça de água, ficar secando o chão com pano ou balde (fazer o erro sumir) resolve temporariamente, mas não resolve o problema — é preciso seguir o caminho da água para descobrir qual parte do cano rachou (identificar a causa raiz), substituir essa parte e abrir a água novamente para confirmar que não vaza mais (validação). Corrigir bugs é a mesma coisa — encontre a rachadura primeiro, não corra para colocar o balde.

A abordagem oficial do Codex para corrigir bugs foca em dar a ele uma 'receita' de reprodução clara, em vez de apenas uma descrição genérica. A documentação oficial explica bem:

O que você fornece: etapas de reprodução e restrições — isso é muito mais valioso do que uma descrição genérica. O que o Codex fornece: saídas de comando, pontos de chamada encontrados e informações de pilha rastreadas.

Portanto, o fluxo correto de correção de bugs tem quatro etapas indispensáveis:

1. Fornecer receita de reprodução + arquivos suspeitos: o erro completo acompanhado de 'onde cliquei, quais passos segui para disparar o erro', além de indicar os arquivos que você suspeita
2. Pedir para reproduzir antes de diagnosticar a causa: a documentação recomenda explicitamente escrever 'reproduza este bug localmente primeiro' — com a reprodução ativa, o diagnóstico da causa raiz será confiável, em vez de adivinhações baseadas no nada
3. Aplicar a correção: com a causa raiz definida, peça para ele aplicar a alteração, instruindo para 'manter a alteração mínima'
4. Validar: o Codex deve executar as etapas de reprodução novamente após a alteração; se houver um processo de verificação padrão, peça para 'executar o lint + testes mínimos relacionados, relatando os comandos e resultados para mim'

O quarto passo é o que os iniciantes mais esquecem, mas é justamente o mais valioso. O prompt recomendado oficialmente para validação após a correção é simples:

Após corrigir, execute o lint e a suíte de testes mínima relacionada. Relate os comandos usados e os resultados.

Isso coloca uma trava no bug — com os testes passando após a correção, qualquer alteração acidental futura disparará o alarme. O bug do colega do início voltou justamente porque ele não colocou essa trava, e ninguém sabia que aquela linha não podia ser mexida.

Corrigir bug na IDE

Abra o arquivo que você suspeita ter problemas, junto com o arquivo que faz a chamada a ele (a IDE trará os arquivos abertos como contexto) e diga:

Identifique o bug que faz com que mostre "Salvo" mas não realize a persistência de fato.
Após propor a correção, me diga como validar na interface que foi corrigido.

Corrigir bug na CLI

Inicie o Codex no diretório raiz do repositório e envie a receita de reprodução completa. Siga este esqueleto oficial preenchendo com os dados do seu bug:

codex

Bug: Ao clicar em "Salvar" na página de configurações, às vezes mostra "Salvo", mas as alterações não se aplicam de verdade.

Reprodução:
1) Inicie a aplicação: npm run dev
2) Acesse /settings
3) Altere o botão "Ativar notificações"
4) Clique em salvar
5) Atualize a página: o botão volta ao estado anterior

Restrições:
- Não altere o formato da API.
- A alteração deve ser a menor possível; se viável, adicione um teste de regressão.

Reproduza o bug localmente primeiro, depois proponha a correção e execute as checagens.

Note a riqueza de detalhes deste prompt — ele descreve o passo a passo de como disparar o erro, impõe limites (não alterar a API) e exige explicitamente 'reproduzir primeiro'. Isso é o que a documentação chama de 'a receita de reprodução é mais valiosa que uma descrição genérica'.

Aqui está o esqueleto de correção de bugs rápido:

Bug: [Descreva o sintoma em uma frase]
Reprodução: [Liste as etapas de reprodução numeradas, do início ao erro]
Restrições: [O que não alterar, limite da alteração]
Arquivos suspeitos: [Se souber onde está o problema, indique com @]
Por favor: reproduza primeiro → localize a causa raiz (não altere ainda) → aplique a alteração mínima → execute o lint e os testes relacionados para me passar os resultados.

💡 Resumo em uma frase: Correção de bugs em quatro etapas — forneça a receita de reprodução, peça para reproduzir antes de diagnosticar, aplique a alteração mínima e execute o lint/testes para validar; receitas de reprodução são muito mais valiosas do que descrições genéricas, e sem testes de validação, o mesmo bug voltará mais cedo ou mais tarde.

---

04 Refatoração: Planejar primeiro → Alterações incrementais → Comportamento estável → Testar antes e depois

A refatoração é a tarefa com maior risco, pois altera código que está funcionando.

Corrigir bugs tem um critério claro de sucesso: o erro sumiu e os testes passaram. A refatoração não tem isso; seu objetivo é 'tornar o código mais limpo, mas mantendo o comportamento externo exatamente idêntico'. Se o comportamento mudar, você estará introduzindo bugs silenciosamente sob o pretexto de refatorar — esses são os piores bugs, pois ninguém costuma testar com rigor um trecho de código que 'apenas foi organizado'.

Analogia: Trocar peças de um trem de alta velocidade em movimento, sem parar o trem e sem incomodar os passageiros. Você deve garantir que o trem continue correndo e que os passageiros não percebam nada, enquanto substitui uma peça por outra mais fácil de manter. Refatorar é essa 'troca em movimento' — o serviço externo (experiência do passageiro) deve permanecer idêntico o tempo todo.

A refatoração costuma falhar por dois motivos: reescrever tudo de uma vez (impedindo a validação gradual) e não ter testes de cobertura (dependendo da validação visual se o comportamento mudou ou não). A abordagem recomendada do Codex ataca justamente essas falhas — planejar primeiro e entregar em etapas.

Passo 1: Solicitar um plano de refatoração primeiro

A documentação recomenda: antes de alterar o código, peça ao Codex para propor um plano. Se você tiver a habilidade (skill) $plan instalada, invoque-a explicitamente (habilidades usam o prefixo $, diferente do comando /plan para mudar de modo). Essa costuma ser uma habilidade nativa (nível SYSTEM), pronta para usar; caso não esteja na lista, basta pedir em linguagem natural para ele 'criar o plano primeiro sem alterar nada'.

O prompt de planejamento recomendado oficial é assim (veja como ele define objetivos e restrições com precisão):

$plan

Queremos refatorar o subsistema de autenticação (auth), objetivos:
- Separar responsabilidades (dividir em decodificação de token / carregamento de sessão / validação de permissões)
- Reduzir dependências cíclicas
- Aumentar a testabilidade

Restrições:
- O comportamento visível ao usuário não deve mudar
- As APIs públicas devem permanecer estáveis
- Forneça um plano de migração passo a passo

Após receber o plano, não aceite de cara — ajuste os detalhes com ele (esta etapa define o sucesso da refatoração):

Ajuste o plano:
- Especifique quais arquivos serão alterados em cada etapa
- Adicione uma estratégia de rollback para cada passo

Por que planejar primeiro? Porque a regra geral se aplica aqui — 'dividir tarefas complexas em passos menores e focados ajuda o Codex a entregar melhor e facilita a sua revisão'. Um plano detalhando quais arquivos mudam e como reverter transforma uma grande refatoração em várias micro-refatorações fáceis de validar.

Passo 2: Entregar em pequenas etapas, testando a cada passo

Com o plano definido, execute etapa por etapa, rodando os testes a cada passo para garantir que nada quebrou. Há uma regra de ouro a ser seguida:

Nunca peça para o Codex refatorar código que não tem testes. Imagine que, para ir mais rápido, você peça para refatorar uma função utilitária sem testes, e ele 'otimize' um bloco condicional — que parecia código morto, mas tratava uma entrada rara. O problema só será descoberto em produção.

Se o código a ser refatorado não possui testes, a primeira etapa não é alterar, mas sim escrever testes — capture o comportamento atual escrevendo testes de cobertura e use-os para garantir que o comportamento se mantém após a refatoração. Isso segue a mesma lógica de correção de bugs: crie um caminho de validação próprio para o Codex, caso contrário a impressão de 'parecer correto' será o único sinal de entrega, o que costuma esconder problemas.

Eu mesmo já cometi esse erro: no início, pedi para o Codex refatorar uma função de formatação de valores que não tinha testes; ele 'otimizou' e acabou removendo a lógica que tratava números negativos. Tudo parecia bem localmente, mas os erros apareceram na conciliação em ambiente de homologação. Desde então, minha regra é — sem testes, primeiro escrevemos testes e depois refatoramos, sem exceções. Demora um pouco mais, mas nunca mais tivemos problemas.

Aqui está o fluxo de refatoração:

Etapa	O que fazer	Instrução chave
1. Criar plano	Peça para ele (ou $plan) criar um plano de refatoração estruturado	Defina objetivos + restrições: comportamento idêntico e APIs estáveis
2. Ajustar plano	Ajuste os arquivos a serem alterados em cada passo e a reversão	Divida em marcos pequenos e validáveis
3. Escrever testes	Se não houver testes, escreva testes para cobrir o comportamento atual	Tire uma foto (snapshot) do comportamento atual
4. Aplicar em passos	Execute um marco de cada vez	Não permita reescrever tudo de uma vez
5. Testar antes e depois	Rode os testes a cada etapa, e o resultado deve ser idêntico ao anterior	Se o comportamento mudar, pare e reverta imediatamente

ℹ️ Para grandes refatorações, há uma técnica avançada: planeje e ajuste localmente, e terceirize a execução longa e pesada para a nuvem em paralelo. Esse é o cenário discutido na seção 10 · Cloud Codex Cloud — o local cuida do planejamento e validação finos, e a nuvem executa as tarefas demoradas. Vamos dominar o fluxo local aqui e ver os detalhes de nuvem lá.

💡 Resumo em uma frase: O segredo da refatoração é 'o comportamento externo não pode mudar' — crie um plano em passos, defina quais arquivos mudam, aplique em etapas e teste a cada passo; se não houver testes, escreva-os antes de começar. Reescrever tudo de uma vez e não ter testes de cobertura são os maiores perigos da refatoração.

---

05 Escrever testes: O foco é exigir a cobertura de casos limite

A última categoria: adicionar testes para o código.

O Codex é muito eficiente para escrever testes — a recomendação oficial orienta a 「seguir as convenções já existentes nos testes do projeto」, o que significa que ele inspecionará os arquivos de teste existentes para adotar o mesmo framework e estilo de asserção, alinhando-se automaticamente ao seu estilo sem você precisar explicar. Mas há uma armadilha que você precisa conhecer: se você não especificar, ele dependerá apenas do 'caminho feliz' (happy path).

O caminho feliz consiste em testar o fluxo básico. Para uma função que inverte uma lista, por exemplo, ele testará se [1, 2, 3] se transforma em [3, 2, 1] — está correto, mas e se a lista estiver vazia? E se tiver apenas um elemento? E se receber null? Esses 'casos limite' (edge cases) são onde os bugs costumam aparecer e são os que mais precisam de cobertura de testes.

Analogia: Fazer teste de colisão em carros novos não pode ser apenas dirigir devagar em linha reta. O teste real e valioso exige bater na parede, frear bruscamente, capotar — testar situações extremas. Os problemas acontecem nos limites, não no asfalto liso. O foco ao escrever testes é exigir que o Codex cubra esses limites.

A orientação oficial para ambas as abordagens (IDE e CLI) destaca o mesmo ponto — cobrir tanto o happy path quanto os edge cases.

Escrever testes na IDE (baseado em seleção)

Abra o arquivo com a função alvo, selecione as linhas que definem a função, escolha a opção 'Add to Codex Thread' (Adicionar à conversa do Codex) no painel para incluir as linhas no contexto e diga:

Escreva testes unitários para esta função. Siga as convenções existentes nos outros testes.

A opção 'Add to Codex Thread' é um recurso específico da IDE — ela fornece as linhas exatas selecionadas para o Codex, o que é muito mais preciso do que descrever 'aquela função'.

Escrever testes na CLI (especificando a função + arquivo no prompt)

Inicie o Codex, indique o arquivo com @ e especifique a função, exigindo explicitamente a cobertura de casos limite:

codex

Escreva testes para a função invert_list em @transform.ts.
Cubra o caminho feliz e inclua casos limite.

O ponto chave deste prompt oficial é a parte final — 「inclua casos limite」 — se remover essa instrução, ele provavelmente gerará testes apenas para o caminho feliz. Compare os dois prompts abaixo e veja a diferença:

❌ Prompt Vago	✅ Prompt Preciso
「Escreva testes para esta função」	「Escreva testes para a função invert_list em @transform.ts, cobrindo o caminho feliz e focando em casos limite como lista vazia, único elemento, null e listas gigantes」
Ele testa apenas o fluxo comum, dando uma falsa sensação de cobertura alta	Ele cobrirá os pontos reais onde o código costuma quebrar

Há também uma dica de ouro — peça para ele sugerir novos casos. Muitas vezes esquecemos alguns limites, então deixe-o propor:

Além disso, sugira outros casos limite que eu possa ter esquecido e adicione testes para eles também.

Uso essa frase sempre que peço testes, e ela frequentemente identifica combinações de entradas que eu não havia considerado — uma vez, em uma função que calculava intervalos de datas, eu cobri valores vazios e datas invertidas, e ele adicionou testes para 'horário de verão' e 'mesmo dia com horários diferentes', que eu teria deixado passar.

Aqui está o fluxo de escrita de testes na IDE e na CLI:

Etapa	Extensão da IDE	CLI
1. Identificar alvo	Selecione as linhas da função → 「Add to Codex Thread」	Mencione o arquivo com @ e especifique o nome da função
2. Alinhar estilo	「Siga as convenções dos testes existentes」	Igual à esquerda
3. Exigir casos limite	「Caminho feliz + casos limite: [liste-os]」	Igual à esquerda
4. Deixar propor novos casos	「Adicione outros casos limite que eu possa ter esquecido」	Igual à esquerda
5. Executar validação	Rode os testes e corrija falhas até passar	Igual à esquerda

💡 Resumo em uma frase: Ao pedir testes, não diga apenas 'escreva testes' — exija explicitamente a cobertura de casos limite (nulos, vazios, extremos); a instrução 'inclua casos limite' é essencial, e deixar o Codex sugerir novos casos ajuda a encontrar falhas invisíveis.

---

06 Mão na massa: Corrigindo um bug real passo a passo

Teoria sem prática não consolida o aprendizado. Vamos fazer um laboratório prático de correção de bug — este fluxo é o mais completo e, dominando-o, os outros três serão naturais. Preparamos um bug real para você corrigir.

Diferenças de plataforma: Os comandos mkdir / cd funcionam diretamente no Mac / Linux; no Windows, execute-os no PowerShell e crie o arquivo calc.py manualmente com o Bloco de Notas.

Passo 1: Criar um projeto de teste com um bug

mkdir bug-demo
cd bug-demo

No Mac / Linux, use echo para escrever o arquivo:

echo 'def average(numbers):
    return sum(numbers) / len(numbers)' > calc.py

No Windows, crie calc.py com o Bloco de Notas e cole estas duas linhas:

def average(numbers):
    return sum(numbers) / len(numbers)

Esta função average calcula médias e parece correta — mas ao passar uma lista vazia, ela quebrará por divisão por zero. Este é o bug que vamos corrigir.

Resultado esperado: Uma pasta bug-demo contendo o arquivo calc.py com as duas linhas da função.

Passo 2: Iniciar o Codex no diretório raiz

codex

Resultado esperado: A interface interativa (TUI) será aberta, mostrando a área de conversa e a barra de entrada na parte inferior.

Passo 3: Aplicar o fluxo de correção de bug, fornecendo a receita

Cole o seguinte texto na barra de entrada (este é o esqueleto da seção 03 preenchido, contendo passos de reprodução, restrições e a instrução de reproduzir primeiro):

Bug: Chamar average([]) em calc.py gera uma falha.

Reprodução:
1) Passe uma lista vazia [] para a função average
2) Ela dispara ZeroDivisionError: division by zero de forma consistente

Restrições:
- Mantenha a alteração mínima e não altere a assinatura da função.

Por favor: reproduza este bug localmente primeiro, identifique a causa raiz (não altere ainda), depois aplique a alteração mínima,
e por fim crie um teste de regressão que reproduza o problema e execute-o para confirmar que passa.

Resultado esperado: O Codex reproduzirá o erro e explicará a causa — ao receber uma lista vazia, len(numbers) é 0, causando divisão por zero; em seguida, ele proporá um diff de alteração (como retornar 0 para listas vazias ou lançar uma exceção clara) e esperará sua aprovação; após aprovado, ele criará um arquivo de testes (como test_calc.py) com um caso de teste para a lista vazia.

ℹ️ A necessidade de aprovação antes de alterar depende das configurações de permissão locais (o modo Auto pode liberar alterações automaticamente dentro da área de trabalho). Detalharemos essa lógica de sandbox e aprovações na seção 15 · Permissões, sandbox e aprovações.

Passo 4: Aprovar a alteração e validar

Revise o diff e escolha 'Sim / Yes'. O Codex executará os testes criados — cumprindo o passo de validação pós-correção.

Resultado esperado: O resultado do teste será exibido no terminal, semelhante a:

test_calc.py::test_average_empty_list PASSED
test_calc.py::test_average_normal PASSED

Testes verdes = bug corrigido e travado — se alguém reverter a alteração futuramente, os testes acusarão o erro.

Passo 5: Sair e verificar se o arquivo foi alterado

Saia do Codex (com /exit) e verifique o arquivo no terminal:

cat calc.py

(No Windows PowerShell, use type calc.py)

Resultado esperado: O arquivo calc.py conterá o tratamento para listas vazias, e a pasta terá um arquivo de testes criado. O diff aplicado corresponde ao aprovado = fluxo de correção de bug concluído com sucesso!

⚠️ Se o Codex não gerou testes no Passo 3, você provavelmente removeu a instrução 'crie um teste de regressão'. Não pule essa instrução — a trava de validação separa desenvolvedores iniciantes de experientes.

💡 Resumo em uma frase: Execute o fluxo de correção de bug na prática — crie o bug de exemplo, envie a receita para reproduzir e corrigir, e veja-o passar nos testes após aplicar; dominar este fluxo torna os outros três intuitivos.

---

07 Resumo

Esta seção organizou 80% do seu trabalho diário em quatro categorias, fornecendo um fluxo específico para cada uma:

Tarefa	Fluxo Principal	Ponto de Atenção Crucial
Explorar código	「Arquitetura geral → Onde fica o código de X → Rastrear fluxo de execução」	IDE lê arquivos abertos, CLI precisa de @ para indicar; use apenas leitura
Corrigir bug	「Receita de reprodução → Reproduzir antes de consertar → Correção mínima → Validar」	Receitas de reprodução são essenciais; nunca pule os testes de validação
Refatorar	「Criar plano → Ajustar passos → Alteração incremental → Testar antes e depois」	O comportamento não pode mudar; escreva testes antes de começar se não houver cobertura
Escrever testes	「Happy path + Casos limite, depois peça para sugerir novos casos」	Exigir casos limite é essencial; o caminho feliz é a parte mais fácil

A regra comum a todos eles é: crie um caminho de validação próprio para o Codex — na exploração peça listas de passos, na correção exija testes de reprodução, na refatoração use testes de cobertura como garantia e ao escrever testes force a cobertura dos limites. Com parâmetros de validação claros, o Codex entrega qualidade de fato em vez de apenas parecer correto.

Agora você é capaz de: enfrentar qualquer uma dessas quatro tarefas sem hesitação — aplicando o fluxo correto, sabendo o que exigir do Codex em cada passo, o que monitorar na entrega e entendendo as diferenças de contexto entre a IDE e a CLI. Esses quatro fluxos servem de estrutura para a maior parte do seu trabalho; tarefas mais complexas costumam ser apenas a combinação e sequência desses fluxos.

Essas abordagens foram validadas no dia a dia e trarão robustez para suas entregas com o Codex.

---

A próxima seção 15 · Permissões, sandbox e aprovações — embora tenhamos falado sobre aprovações e o modo de apenas leitura nesta parte, ainda não detalhamos o mecanismo por trás disso. Como o Codex sabe quando pedir permissão e quando agir de forma autônoma? Qual o limite do sandbox dele? A próxima seção explicará a mecânica de permissões, sandbox e aprovações, para que você tenha controle total sobre os limites de atuação do Codex. Uma reflexão: no laboratório de correção de bug ele 'esperou sua aprovação antes de alterar'; se você quisesse permitir alterações livres na área de trabalho e aprovação apenas fora dela, qual configuração ajustaria?

---

Leituras Recomendadas

• Agent Skills 技能: Empacotando e ensinando fluxos ao Codex
• Automação e CI/CD: Deixando o Codex trabalhar na sua ausência
• Cloud Codex Cloud: Terceirizando execuções longas para a nuvem