Codex CLI: como usar goals para guiar o agente sem microgerenciar

Dar uma tarefa pro Codex é fácil. Você abre o terminal, descreve o que quer e ele edita o arquivo. Isso funciona pra mexer numa função, ajustar um teste, renomear uma variável. O problema aparece quando o trabalho não cabe num único turno.

Aí entra o /goal. É o recurso do Codex CLI que faz o agente perseguir um objetivo sozinho — planejar, agir, testar, revisar e corrigir o rumo — sem você ficar empurrando o próximo passo a cada cinco minutos. Não é mágica. É um contrato com uma condição de parada verificável.

Neste tutorial você vai entender quando usar goal no Codex CLI, como escrever um objetivo que o agente consegue perseguir de verdade, e onde isso quebra se você for ingênuo. Vou usar o que está no cookbook da OpenAI e na documentação oficial.

TL;DR

• O que é: modo /goal do Codex CLI — o agente entra num loop autônomo e persegue um objetivo até a condição de parada ser atingida.
• Stack/Modelos: Codex CLI 0.128.0+, GPT-5.5 (recomendado para a maioria das tarefas no Codex desde abril de 2026).
• Custo/Acesso: incluso no plano do Codex; consome do seu quota semanal. Goal mode saiu de experimental e roda em CLI, IDE e app.
• Link útil: Codex changelog oficial e cookbook de ExecPlans.

O contexto: o que muda quando o Codex CLI persegue um objetivo

Até pouco tempo, agente de código era isso: você manda um prompt, ele responde, você lê, manda o próximo. Loop humano no meio de cada passo. Funciona, mas você é o gargalo. Sai pra almoçar e o agente para. Esse é o ciclo de agentic code — plan, act, observe, reflect — mas com você empurrando cada volta.

O /goal chegou no Codex CLI 0.128.0, em 30 de abril de 2026, e muda a posição do humano no fluxo. Em vez de esperar seu próximo prompt depois de cada ação, o Codex planeja a própria sequência, executa, checa o resultado, corrige quando algo falha e continua — até bater no objetivo ou esbarrar num muro que não atravessa sozinho.

O detalhe que importa: ele valida progresso contra evidência. Resultado de teste, score de eval, saída de build. Não é um agente rodando solto torcendo pra dar certo. É persistência amarrada a um contrato com loop de verificação. Essa é a diferença entre demo bonita e coisa que aguenta produção.

Goal não é prompt. É contrato.

Aqui está a regra que separa quem usa goal de quem só acha que usa. Um bom objetivo é mensurável. Um prompt vago é só um pedido com esperança embutida.

Olha a diferença:

# ruim — isso é um prompt fantasiado de goal
/goal improve auth

# bom — o agente consegue checar o próprio progresso contra evidência
/goal raise src/auth coverage from 38% to 75%, only edit src/auth and tests,
stop when npm test passes and the coverage threshold is met

O segundo tem tudo que o agente precisa pra saber se está perto ou longe: número de partida, número de chegada, escopo do que pode tocar e a condição exata de parada. O primeiro não tem nada disso. "Improve" não tem fim. O agente nunca sabe quando terminou.

A frase que resume isso, do review prático do J.D. Hodges, é direta: "Codex consegue checar o próprio progresso contra evidência. Se você não consegue escrever essa linha, você não tem um goal. Você tem um prompt."

Antes de disparar um /goal, escreva mentalmente cinco coisas:

1. Artefato mensurável — o arquivo ou número que marca "pronto".
2. Comando de verificação — o one-liner que prova que está correto (npm test, pytest, build verde).
3. Escopo de escrita — exatamente quais diretórios o agente pode editar.
4. Condição de parada — a frase ou estado literal que encerra o run.
5. Condição de pausa — quando interromper (limite de tentativas, tempo, aprovação humana).

Se você não consegue preencher os cinco, o trabalho ainda é um prompt. Mantém no fluxo normal e segue empurrando os passos na mão.

Pré-requisitos

Antes de mexer no /goal:

• [ ] Codex CLI versão 0.128.0 ou mais nova (npm install -g @openai/codex).
• [ ] Acesso ao Codex com quota disponível (o loop consome do limite semanal).
• [ ] Em versões iniciais, o recurso vinha atrás de uma flag. Se o /goal não aparecer, habilite no ~/.codex/config.toml:

[features]
goals = true

Reinicie o CLI e qualquer serviço dependente depois de mudar a config. Em builds recentes, goal mode já saiu de experimental e vem ligado por padrão — mas vale conferir a versão antes de assumir.

Mão na massa: guiando o agente sem microgerenciar

Passo 1: escreva o objetivo como contrato

Não comece pelo verbo bonito. Comece pelo número e pelo escopo.

/goal migrate this service from Node 14 to Node 20, only edit package.json,
src/ and the CI config, keep the existing test suite green,
stop when npm ci && npm test passes on Node 20

Repare: tem ponto de partida, escopo apertado, comando de verificação e parada explícita. O Codex vai ler isso, montar um plano de milestones e começar a executar — sem te perguntar "e agora?" a cada arquivo.

Passo 2: aperte o escopo de escrita

A parte mais subestimada do goal é o only edit. Sem isso, o agente pode "consertar" coisas fora do alvo pra fazer o teste passar, e você volta de café com um diff de 40 arquivos. Diga onde ele pode escrever. Quanto mais cirúrgico o escopo, mais previsível o resultado e menos quota desperdiçada.

Goals brilham em tarefas com critério objetivo: migrações, expansão de suíte de testes, feature construída por TDD, loop de retry de deploy, otimização de performance com threshold medível. Onde eles falham é em design exploratório, decisão de arquitetura e objetivo vago tipo "deixa melhor". Pra isso, o loop humano ainda é o certo.

Passo 3: acompanhe, pause, retome

Você não fica preso assistindo. O Codex CLI te dá controle sobre o run:

/goal          # mostra o status do objetivo atual
/goal pause    # pausa o run em andamento
/goal resume   # retoma de onde parou
/goal edit     # ajusta o objetivo sem zerar o progresso
/goal clear    # descarta o objetivo atual

Num teste real documentado, o autor deu um objetivo de font-matching com cap de 60 minutos. O run terminou em ~5 minutos consumindo 188.832 tokens — fração de um dígito do quota semanal. E o mais importante: quando o Codex não conseguiu o resultado, ele não inventou. Reportou o que tentou, por que falhou e entregou só os leads que conseguiu verificar localmente. Isso é o tipo de honestidade que você quer num agente que roda sem supervisão.

O cookbook entra aqui: goals + PLANS.md

/goal resolve a persistência. Mas pra tarefa de várias horas, o objetivo numa linha não segura tudo. É aí que o cookbook da OpenAI recomenda combinar goals com um PLANS.md — o que eles chamam de ExecPlan.

A ideia é um documento vivo, auto-contido, que serve de especificação e de rastreador de progresso ao mesmo tempo. A regra de ouro do cookbook: "todo ExecPlan precisa ser totalmente auto-contido — conter todo o conhecimento e instruções pra um novato ter sucesso." Isso evita a degradação de contexto em runs longos. O plano tem quatro seções obrigatórias que o agente mantém atualizadas:

• Progress — milestones com checkboxes e timestamps.
• Surprises & Discoveries — o que apareceu de inesperado.
• Decision Log — toda escolha feita no caminho.
• Outcomes & Retrospective — resumo do resultado.

O agente lê o plano inteiro, executa os milestones em sequência sem te perguntar "próximo passo?", e atualiza as seções conforme avança — referenciando o próprio estado no arquivo em vez de depender da memória da conversa. Segundo o cookbook, um ExecPlan bem escrito já fez o Codex trabalhar mais de sete horas a partir de um único prompt.

Junta as duas peças e o desenho fica claro: o PLANS.md é o mapa auto-contido, o /goal é o motor que persegue cada milestone com verificação. Um sem o outro vaza — plano sem goal precisa de você empurrando, goal sem plano se perde em tarefa grande.

Limitações e onde você se queima

goal não é botão de "resolve tudo". Onde dói:

• Não é mais seguro que um run normal. Objetivo vago queima quota num escopo largo. Rode em sandbox e aperte o only edit.
• /goal budget não existe. Várias páginas de SEO inventaram subcomandos que a OpenAI nunca lançou. Confira sempre contra a doc oficial antes de copiar comando de blog aleatório.
• Status é /goal puro, não /goal status. Detalhe bobo que faz gente achar que está quebrado.
• Drift acontece. Se o agente começar a divergir do alvo, pause ou clear na hora. Não deixe rodando "pra ver no que dá" — isso é quota indo embora.
• Objetivo sem critério objetivo não é pra isso. Arquitetura, design, decisão de produto — continua sendo trabalho de humano no loop. Se quiser a lista honesta de onde o agente custa mais caro que o time na mão, veja quando NÃO usar agentic code.

Não pule essa parte. A diferença entre usar goals bem e torrar seu limite semanal está toda no escopo e na condição de parada.

FAQ rápido

Preciso de GPT-5.5 pra usar goals? Não obrigatoriamente, mas a OpenAI recomenda GPT-5.5 como padrão pra maioria das tarefas no Codex — implementação, refactor, debug, teste. Pra exploração leve e subagentes, o GPT-5.4 mini dá conta. Goal mode funciona com o modelo que estiver no picker.

Funciona no CLI ou só no app? Nos dois, mais o IDE. O /goal saiu de experimental e está disponível em Codex CLI, extensão de IDE e app. A sintaxe dos subcomandos é a mesma.

Quanto tempo um goal roda? Até a condição de parada ser atingida ou o quota acabar. Pode ser cinco minutos, podem ser horas. Por isso o cap de tempo e a condição de pausa importam — você define o teto, não o agente.

O agente inventa resultado se não conseguir terminar? Nos testes documentados, não. Ele reporta o que tentou e o que falhou em vez de fabricar. Mas isso depende do objetivo ter critério verificável — se não tem como checar evidência, toda aposta volta a valer.

Conclusão

Goals mudam a pergunta que você faz pro Codex. Não é mais "faz esse passo". É "persegue esse objetivo e me avisa quando bater na evidência". A engenharia toda está em escrever o contrato: artefato mensurável, comando de verificação, escopo apertado, condição de parada. Sem isso, você tem um prompt com esperança embutida — e o agente nunca sabe quando terminou.

O próximo passo é parar de pensar em prompt e começar a pensar em harness: o conjunto de regras, escopo e verificação que faz um agente perseguir um objetivo sozinho sem sair dos trilhos. É exatamente esse caminho — do prompt até o harness de um agente rodando em produção — que a gente constrói ao vivo no workshop Do Prompt ao Harness: construindo um agente de vendas, com código na mesa e decisões de arquitetura, não slide.

O salto não é usar o Codex. É saber desenhar o objetivo que ele persegue sem você no meio de cada passo.