Como dividir uma refatoração grande em etapas com o GPT-6 Astra e revisar cada uma

Soltar uma refatoração inteira de uma vez num agente é a forma mais rápida de perder o controle do que entrou no seu repositório

A OpenAI lançou o GPT-6 Astra em 3 de setembro de 2026, apresentado como o modelo mais capaz dela para trabalho longo de ponta a ponta: raciocínio complexo, código, uso de computador, pesquisa e criação de documentos

E é justamente por causa disso que o método importa MAIS, não menos

O Astra tem 1.050.000 tokens de janela de contexto e 128K de saída máxima

Só que janela grande não é permissão pra jogar o repositório inteiro dentro do prompt, cruzar os dedos e aceitar o diff que voltar

Janela grande é espaço pra plano, não desculpa pra falta dele, beleza? 🙂

O que você precisa antes de começar

Antes de sair rodando, se liga no que precisa estar na mesa:

• Acesso ao GPT-6 Astra: o rollout é faseado, começou limitado a organizações do Trusted Access Program e, nos dias seguintes, chega a ChatGPT Plus, Pro, Business e Enterprise, além da API da OpenAI e da AWS
• Codex CLI com sessão interativa, que é onde os comandos deste post rodam
• Repositório versionado com git, porque o fluxo inteiro depende de separar mudanças não commitadas, commit e branch base
• Suíte de testes que já roda e passa ANTES da refatoração começar
• Ciência do custo, que é o item que a galera esquece
• Ciência de que a tarefa pode parar no meio: a OpenAI documenta que as checagens de segurança extras do Astra podem interromper trabalho legítimo, e o comportamento muda por produto (no ChatGPT e no Codex a tarefa pode ser pausada pedindo sua revisão, na API ela é interrompida)

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Falando em custo:

Na API, o Astra custa US$ 10 por milhão de tokens de entrada e US$ 50 por milhão de tokens de saída

Isso é 2,5 vezes o preço do GPT-5.6 Sol, que sai por US$ 4 por milhão de entrada e US$ 20 por milhão de saída

E tem um detalhe que pesa numa refatoração grande: prompts acima de 272 mil tokens de entrada são cobrados com multiplicador na requisição INTEIRA, 2x nas taxas de input e cache e 1,5x no output

Ou seja: encher a janela até o talo não é só desleixo técnico, é conta subindo

Passo a passo: da definição do plano ao merge de cada bloco

A lógica aqui é uma só: fechar o plano antes do código e nunca aceitar um lote gigante de uma vez

1. Trave o agente em modo somente leitura antes de conversar sobre a refatoração

Antes de discutir arquitetura, tira do agente a permissão de mexer em arquivo

/permissions

O que dá pra afirmar com segurança é isso: o /permissions alterna a sessão para o modo somente leitura

A documentação também descreve que a segurança do Codex tem duas camadas, sandbox mode e approval policy, e que a approval_policy aceita untrusted, on-request, never e granular

Não vou chutar qual das duas camadas responde pelo modo somente leitura, porque pra este fluxo o que importa é o efeito: com o /permissions acionado, o agente conversa e não escreve

O erro comum deste passo: discutir a refatoração com o agente já liberado pra escrever, e aí ele "ajuda" implementando metade do plano enquanto vocês ainda estão combinando o plano

2. Entre no Plan mode e deixe ele reunir contexto

/plan

O Plan mode do Codex também é alternado com Shift + Tab

Ele existe pra isso: o agente reúne contexto, faz perguntas de esclarecimento e monta o plano ANTES de implementar

Pergunta de esclarecimento não é enrolação, é o agente dizendo onde ele ainda está chutando

O erro comum deste passo: responder as perguntas com "tanto faz, escolhe você"

Cada "tanto faz" seu vira uma decisão de arquitetura que você vai descobrir depois, no diff

3. Escolha o modelo e o nível de raciocínio

Dentro da sessão interativa:

/model

O /model troca o modelo ou ajusta o reasoning effort

Na inicialização, dá pra já subir com o modelo definido:

codex --model <modelo>

Ou no alias curto:

codex -m <modelo>

Na API, o reasoning.effort do Astra aceita low, medium, high, xhigh e max

E atenção: o Astra NÃO aceita o nível none

O erro comum deste passo: subir o esforço de raciocínio pro máximo em tudo, inclusive nas etapas mecânicas, e transformar cada bloco numa fatura

4. Fixe um esforço maior só para o planejamento

O planejamento é onde pensar caro compensa

No ~/.codex/config.toml:

plan_mode_reasoning_effort = "high"

Assim a fase de plano ganha fôlego sem você ficar trocando na mão a cada sessão

O erro comum deste passo: configurar e nunca reabrir o arquivo, mesmo quando o tipo de tarefa muda completamente

5. Materialize o plano num PLANS.md

A OpenAI documenta o uso de planos em markdown como memória durável para tarefas longas no Codex: um arquivo com spec, plano, restrições e status, que o agente revisita ao longo do trabalho

Segundo o cookbook da própria OpenAI, isso permitiu ao Codex trabalhar mais de sete horas a partir de um único prompt

# Spec
Objetivo da refatoracao e o que NAO muda

# Restricoes
- API publica nao pode quebrar
- Sem mudanca de comportamento observavel
- Testes existentes continuam passando

# Plano (blocos)
- [ ] Bloco 1: ...
- [ ] Bloco 2: ...
- [ ] Bloco 3: ...

# Status
Bloco atual: 1
Ultima revisao: pendente

O erro comum deste passo: escrever spec e plano e esquecer as restrições

Restrição é o que impede o agente de "melhorar" coisa que ninguém pediu

6. Recorte a refatoração em blocos pequenos e independentes

Um objetivo por bloco

Se você não consegue descrever o bloco numa frase, ele não é um bloco, é um projeto

O erro comum deste passo: criar blocos que dependem uns dos outros em cadeia, e aí o bloco 2 só pode ser revisado depois do 3 estar meio pronto

7. Implemente UM bloco por vez e pare

Parar é parte do método, não falta de produtividade

O erro comum deste passo: deixar o agente emendar no próximo bloco porque "já tá com o contexto quente"

Contexto quente é ótimo pro agente e péssimo pra sua revisão

8. Rode a revisão dedicada no bloco

/review

O /review revisa mudanças não commitadas, um commit ou uma branch base, e reporta achados priorizados SEM modificar a working tree

Essa parte é a que muda o jogo: é revisão de verdade, não é o agente mexendo enquanto revisa

O erro comum deste passo: mandar revisar cinco blocos acumulados de uma vez, e receber uma lista tão longa que você lê os três primeiros itens e aprova o resto no olhômetro

9. Rode os testes e commite só com o bloco verde

Suíte passando é o critério de aceite do bloco

Não é "parece certo", não é "o diff está bonito"

O erro comum deste passo: commitar com teste quebrado prometendo consertar no bloco seguinte

Já vi essa promessa virar três dias de arqueologia no git log

10. Atualize o status no PLANS.md e abra o próximo bloco

Marcar o bloco como feito não é burocracia: é o que mantém o agente alinhado quando a sessão reinicia e o contexto some

O erro comum deste passo: atualizar o status só no fim de tudo, quando ele já não serve pra nada

Como recortar os blocos: exemplos de divisão que funcionam

A regra do bloco revisável é simples: cabe numa leitura humana e tem teste próprio

Se falhar em qualquer um dos dois, corta de novo

Agora, como isso se traduz nos tipos mais comuns de mudança ampla:

Renomeação em massa:

Separe a renomeação mecânica da mudança de comportamento

Um bloco só renomeia e mantém tudo funcionando, outro bloco altera lógica

Diff de renomeação é longo e chato, mas é revisável em minutos

Diff misto de renomeação com lógica é onde bug se esconde à vista de todos

Extração de módulo:

Primeiro bloco: mover código pro novo lugar sem mudar assinatura

Segundo bloco: ajustar quem chama

Terceiro bloco: limpar o que ficou órfão

Cada um desses tem um teste natural pra chamar de seu

Troca de biblioteca:

Recorte por ponto de contato, não por arquivo

Um bloco por fronteira trocada, com a antiga ainda no lugar até a última etapa

A remoção da dependência velha é um bloco por si só, e é o mais fácil de revisar

Separação de camada:

Recorte por fluxo, não por diretório

Pega um fluxo de ponta a ponta, separa ele, testa, commita

Depois o próximo

Esse raciocínio de fatiamento é o mesmo que você usa quando precisa dividir uma spec em specs menores, e não é coincidência: plano grande demais falha pelo mesmo motivo em qualquer ferramenta

E se você for distribuir esses blocos entre mais de um agente ao mesmo tempo, aí entra outro cuidado, que é evitar que eles editem o mesmo arquivo

Como padronizar a revisão de cada etapa com regras no AGENTS.md

O Codex Code Review lê regras de revisão personalizadas do próprio repositório

As regras entram numa seção chamada Code Review Rules dentro do AGENTS.md mais próximo do código que elas governam

O Codex procura os AGENTS.md do repositório e segue as regras aplicáveis

## Code Review Rules

- Nenhuma mudanca de assinatura publica neste modulo sem teste novo
- Rejeitar renomeacao que venha junto com alteracao de logica no mesmo diff
- Toda funcao movida deve manter o mesmo tratamento de erro da origem
- Sinalizar qualquer import novo que nao esteja no plano

Por que isso importa numa refatoração longa:

A sessão muda

O contexto muda

Você mesmo muda de humor entre o bloco 1 e o bloco 9, vamos combinar 😀

Com as regras no arquivo, a régua de revisão fica IGUAL do primeiro ao último bloco, independente do que a conversa daquele dia tinha dentro

O erro comum deste passo: regra genérica demais

"Escrever código limpo" não pega nada

A regra tem que descrever o que ESSA refatoração especificamente pode quebrar, no arquivo mais perto do código que ela protege

Quando a etapa trava ou o lote volta gigante: o que fazer

Sintoma: o agente devolve um lote enorme de mudanças de uma vez

Causa provável: bloco mal recortado ou plano vago

Quando o objetivo é ambíguo, o agente preenche a lacuna do jeito dele, e o jeito dele costuma ser "faz tudo"

Solução: não aceite pra depois filtrar

Volta pro Plan mode, refaz o recorte, deixa explícito o que está FORA do bloco

Revisar um lote gigante é o mesmo que não revisar, só que com mais cansaço

Sintoma: a tarefa é pausada ou interrompida no meio

Causa provável: as checagens de segurança extras do Astra

Esse contexto vale conhecer: o Astra é o primeiro modelo que a OpenAI classificou como tendo atingido o limiar "critical" de capacidade cibernética no Preparedness Framework

Em 7 de agosto de 2026 a OpenAI disse não conseguir descartar capacidades cibernéticas críticas e pausou atividades internas com o Astra

O modelo foi lançado em 3 de setembro de 2026 já classificado como "critical" em cibersegurança, com salvaguardas reforçadas

E, segundo a própria OpenAI, o comportamento muda conforme o produto:

• No ChatGPT e no Codex, a tarefa pode ser pausada e pedir sua revisão antes de continuar
• Na API, a tarefa é interrompida

Solução: saber disso antes evita o susto

Se você automatizou algo na API, trate interrupção como estado possível do fluxo, não como bug do seu script

Sintoma: a conta subindo mais rápido do que você esperava

Causa provável: prompts acima de 272 mil tokens de entrada

Lembrando: acima desse limite, o multiplicador vale pra requisição INTEIRA, 2x em input e cache e 1,5x no output

Solução: bloco menor também é controle de custo, não só controle de qualidade

Um plano bem recortado te faz mandar menos contexto por vez, e essa é a economia que ninguém anuncia

O Astra vale o método? O que os números dizem sobre código

Aqui vale calibrar expectativa sem transformar o post em review

No Artificial Analysis Intelligence Index, o GPT-6 Astra (max) marca 61, empatado com o GPT-5.6 Sol e com o Grok 4.6 (high)

Quem lidera o índice é o Claude Fable 5.1, com 66

As outras variantes do Astra ficam em 60 (high), 59 (medium) e 55 (non-reasoning)

No Coding Agent Index, medido rodando dentro do Codex, o Astra marca 67

Isso é aproximadamente igual ao Claude Opus 5 e ao Fable 5 rodando no Claude Code, e ao Muse Spark 1.3 no Muse Code

O detalhe interessante: ele empata com o Fable 5 por menos da metade do custo, por ganho de eficiência de tokens

E no teste de código agêntico citado no lançamento, o Astra fez 74,1% (113 tarefas) contra 70,8% do GPT-5.6 Sol

A Meta reportou 75,4% para o Muse Spark 1.3 no ajuste máximo de raciocínio

A leitura honesta disso tudo:

A margem de vantagem é ESTREITA

Ninguém está tão à frente a ponto de você poder confiar num lote gigante sem olhar

O que separa uma refatoração com GPT-6 Astra que dá certo de uma que vira dívida técnica não é a nota do modelo no índice

É o método: bloco pequeno, revisão dedicada, teste verde, commit

Vídeo: um panorama de IA aplicada no dia a dia

Pra começar do zero com o assunto de dividir trabalho em partes com IA, este vídeo do canal mostra uma IA que separa uma imagem em camadas

Próximo passo: comece pelo bloco menos arriscado

O princípio central é um só, e cabe numa frase: você controla o que entra no repositório, não o agente

Janela de 1.050.000 tokens não muda isso

Nota alta em benchmark não muda isso

O que muda é o tamanho do pedaço que você aceita revisar de verdade

Então o próximo passo é bem concreto: escolhe aquela refatoração que tá pendente há semanas, abre o Plan mode, escreve o PLANS.md com spec, plano e restrições

E recorta SÓ o primeiro bloco, de preferência o menos arriscado de todos

O bloco chato de renomeação, aquele que ninguém quer fazer

Ele é perfeito pra você calibrar o fluxo antes de encostar no código que dói

O rollout do Astra ainda tá caminhando e a documentação vai mudando junto, então fica de olho por aqui que vem mais coisa sobre ele…

até o próximo post! 🙂