Refatoração com o Codex: plano, meta e uma revisão a cada passo

O que o Codex faz em refatoração

• Avança por um backlog de refatoração em passos pequenos, cada um no seu próprio pull request.
• Roda os testes antes e depois de cada passo e para quando eles falham.
• Faz a parte mecânica das migrações: renomeações em todo o código, upgrades de API, a troca para uma biblioteca nova.
• Remove código morto e lógica duplicada e explica cada remoção.

Recursos do Codex para refatoração

Como configurar o Codex para refatoração

1. Conecte as ferramentas

   Não há nada para conectar. O que torna uma refatoração segura é um comando de teste que o Codex possa rodar e um limite para o tamanho de cada passo, então coloque os dois no AGENTS.md.

   # Na CLI: combine o plano e depois defina a linha de chegada
   /plan Propose a migration plan for the billing module
   /goal Finish the migration and keep tests green

2. Escreva as regras no AGENTS.md

   O Codex lê o AGENTS.md antes de qualquer trabalho: ~/.codex/AGENTS.md e depois os arquivos da raiz do repositório até a pasta em que está trabalhando. Coloque ali as regras do trabalho, ou em uma skill em .agents/skills/ se forem longas. Veja o guia do AGENTS.md.

   ## Regras de refatoração
   - Nenhuma mudança de comportamento. Se um teste precisar mudar,
     pare e pergunte.
   - Rode `npm test` antes de começar e depois de cada passo.
   - Um passo por pull request, com menos de 400 linhas alteradas.
   - Mantenha o REFACTOR.md em dia: marque o que foi feito e
     acrescente o que você encontrou.
   - Não mexa em migrations/, arquivos gerados ou APIs públicas
     sem perguntar.

3. Rode sem a interface interativa

   codex exec roda uma tarefa e encerra. O progresso vai para o stderr e a mensagem final para o stdout; -o também a grava em um arquivo e --json transmite os eventos. O sandbox é somente leitura, a menos que você passe --sandbox workspace-write.

   # No primeiro dia, e depois a mesma sessão de novo no dia seguinte
   codex exec --sandbox workspace-write "Faça o primeiro passo do REFACTOR.md"
   codex exec resume --last "Continue com o próximo passo não marcado do REFACTOR.md"

4. Coloque em um agendamento

   Crie uma tarefa agendada no app desktop do ChatGPT ou na web (a CLI não as gerencia), ou rode codex exec pelo cron. Veja como deixar o Codex proativo.

Fonte: documentação do Codex

Limites e segurança

• Sem testes, ele não consegue distinguir uma refatoração de uma mudança de comportamento. Adicione testes para a área primeiro.
• Uma reescrita grande de uma vez só é difícil de revisar. Passos pequenos que entram um a um são mais seguros e, no fim, mais rápidos.
• Ele não sabe qual código estranho é proposital. Marque esses trechos com um comentário ou nas regras.
• O Codex roda os comandos em sandbox por padrão: as escritas ficam no workspace e a rede fica desligada. Deixe danger-full-access para um runner ou contêiner isolado.

Claude Code ou Codex para refatoração?

As regras valem para os dois. Escreva-as uma vez no AGENTS.md e coloque @AGENTS.md no CLAUDE.md, e os dois agentes leem o mesmo arquivo.

Passo a passo para o outro agente: refatoração com o Claude Code.

Coloque alguém responsável por refatoração

Comandos rodam quando alguém lembra de rodá-los. O Crewmark transforma o seu próprio Codex em um funcionário de IA com um cargo, uma meta em números, horário de trabalho e um heartbeat, então o trabalho acontece no horário e aparece em um quadro.

1. Comece pelo cargo

   O engenheiro de software com IA, com estas regras no brief.

2. Leve o trabalho para o quadro dele

   Adicione o trabalho como issue recorrente. O funcionário acorda com o heartbeat, faz o trabalho e relata em um comentário.

3. Veja também

   Revisão de código confere cada passo antes do merge.

Perguntas frequentes