O /goal do Claude Code: como usar, escrever condições e o resultado de testes em trabalhos reais

O /goal do Claude Code é um comando em que você escreve uma condição para "quando isso estará pronto", e o Claude continua trabalhando sozinho até chegar a esse ponto. Cada vez que um turno (uma resposta do Claude) termina, um modelo pequeno e separado verifica se a condição foi atendida. Se não foi, o Claude segue para a próxima etapa do trabalho. Este artigo organiza como usar o comando e quando ele para, com base na documentação oficial (verificada em 24 de outubro de 2026). Também relata os resultados de testes feitos em trabalhos reais neste site, incluindo o consumo de tokens e a verificação da qualidade do resultado final.

1. O que é o /goal: diferença em relação a um pedido comum, ao /loop e aos hooks Stop

Quando você pede um trabalho de forma normal, o Claude para assim que decide que o trabalho terminou e aguarda sua próxima instrução. Quando você define um /goal, uma verificação roda ao fim de cada turno (uma resposta do Claude). Se a condição ainda não foi atendida, o próximo turno começa mesmo que você não envie nada. A documentação oficial dá como bons exemplos os seguintes tipos de trabalho maiores, em que o estado final pode ser verificado:

• Migrar um módulo para uma nova API, até que todos os pontos de chamada compilem e os testes passem
• Implementar um documento de design, até que todos os critérios de aceitação sejam atendidos
• Dividir arquivos grandes, até que todos tenham um tamanho igual ou menor que o definido
• Resolver uma lista de issues com etiqueta até que a lista fique vazia

Existem três mecanismos parecidos. A documentação oficial explica que você deve escolher entre eles com base em "o que inicia o próximo turno".

Na essência, o /goal é um "hook Stop que julga com um prompt", e funciona apenas dentro daquela conversa. Um hook Stop é escrito em um arquivo de configurações e vale para todas as conversas. O /goal é escrito na hora e vale apenas para aquela conversa.

Fonte: Keep Claude working toward a goal (documentação oficial do Claude Code, verificada em 24 de outubro de 2026).

2. Como usar: definir, verificar o status e limpar

Uma conversa pode ter apenas um objetivo. O mesmo /goal faz a definição, a verificação e a limpeza, dependendo do que vem depois dele.

1. Definir um objetivo: digite /goal seguido da condição Exemplo: /goal os testes em test/auth passam todos e o lint também fica limpo. Ao definir, um turno começa imediatamente, e a própria condição funciona como instrução, então você não precisa enviar um pedido separado. Se já houver um objetivo, a nova condição o substitui. As condições podem ter até 4.000 caracteres.
2. Verificar o status: digite apenas /goal Ele mostra a condição, o tempo decorrido, o número de avaliações, os tokens usados e o motivo da avaliação mais recente. A contagem e o motivo aparecem depois da primeira avaliação.
3. Parar: /goal clear Isso remove o objetivo antes de qualquer avaliação. stop, off, reset, none e cancel têm o mesmo efeito. Iniciar uma conversa nova com /clear também remove o objetivo.

Se você retomar uma conversa, um objetivo que ainda não tinha terminado volta. A condição é mantida, mas as contagens de turnos, tempo e tokens recomeçam do zero. Funciona no aplicativo de desktop, em sessões remotas e em execuções automáticas com claude -p. O claude -p "/goal …" continua rodando em uma única execução até o objetivo terminar, então, se você quiser acompanhar o progresso, adicione --output-format stream-json --verbose.

3. Como funciona o julgamento e quando ele para

Cada vez que um turno termina, o Claude Code envia a condição e a conversa até ali para um "modelo pequeno e rápido". O julgamento tem três resultados, cada um com um motivo curto. Neste ambiente do site, o avaliador foi o Claude Haiku 5.5 (confirmado pelos registros da conversa).

O avaliador não usa ferramentas, e ele julga apenas com base no que aparece na conversa. Ele não relê arquivos nem executa testes por conta própria. Se o Claude responder ao avaliador sem usar nenhuma ferramenta por vários turnos seguidos, o Claude Code interrompe o ciclo, mostra um aviso e devolve o controle a você, mantendo o objetivo ativo.

Quando para por causa de um erro

Quando há subagentes ou trabalhos em segundo plano

Se um subagente ou um comando em segundo plano ainda estiver rodando ao fim de um turno, o julgamento desse turno fica adiado. Quando os resultados chegam, eles chegam ao Claude como um novo turno. Se passarem 30 minutos de espera, uma "verificação intermediária" é feita. Ela lê a saída do trabalho em execução e, se houver progresso, continua esperando. Se o trabalho estiver parado, ela pede ao Claude que corrija o problema ou pare. Por padrão, o intervalo dobra aos 30 minutos, 1 hora e 2 horas, e depois se repete a cada 2 horas. Você pode mudar o primeiro intervalo com a variável de ambiente CLAUDE_CODE_GOAL_CHECKIN_MINUTES. Definindo-a como 0, as verificações intermediárias e as novas tentativas automáticas são interrompidas.

Quando não pode ser usado, e custo

O avaliador faz parte do mecanismo de hooks, então, como acontece com os hooks, não pode ser usado em pastas que você não marcou como confiáveis. Também não pode ser usado quando disableAllHooks está definido como true nas configurações, ou quando allowManagedHooksOnly está ativado nas configurações do administrador. Nesses casos, o motivo é exibido. Os tokens usados no julgamento são cobrados pela tarifa do modelo pequeno e rápido. A documentação oficial diz que isso costuma ser "muito pequeno em comparação com o trabalho principal". Você pode trocar o modelo avaliador com ANTHROPIC_DEFAULT_HAIKU_MODEL, mas essa configuração também afeta outros processos que usam o modelo pequeno, como a sumarização de conversas.

Fonte: Keep Claude working toward a goal (verificada em 24 de outubro de 2026).

4. Como escrever a condição

O avaliador lê apenas a conversa, então escreva a condição de forma que a própria saída do Claude consiga comprová-la. A documentação oficial lista três elementos de uma condição que se mantêm bem em execuções longas.

Se você quiser limitar por quanto tempo ele roda, escreva isso na condição, por exemplo "ou pare depois de 20 turnos". A documentação oficial não tem uma configuração dedicada como o orçamento de tokens do /goal do Codex.

Um cuidado que aprendemos nos testes deste site: escreva o que deve ser mantido na própria condição, e não em um arquivo de instruções separado. O avaliador julga literalmente pela condição, então uma instrução colocada em outro arquivo pode contar como "atendida" mesmo que não tenha sido seguida. Isso aconteceu de fato no experimento deste site (veja o capítulo 5).

5. Resultados de dois testes com /goal (comparados com um pedido comum)

Usamos o /goal em uma tarefa nos artigos deste site: alinhar os pontos finais das frases. Nos artigos em japonês, havia 1.035 casos em artigos existentes em que o "。" de fechamento estava presente ou ausente (contados pelo script de verificação de pontos finais deste site). Como a regra de correção estava definida e o estado final era claramente "0 itens na verificação", escolhemos a tarefa como adequada ao /goal. Executamos o /goal duas vezes com escopos diferentes e, como referência, colocamos ao lado um pedido comum.

A execução de referência foi aquela em que colamos a condição de uma vez, enquanto tentávamos o /goal. Como descrito no cuidado do capítulo 2, ela não funcionou como comando e rodou como um pedido comum. Incluímos essa execução na tabela como valor de referência para o mesmo tipo de tarefa pedido de forma normal (o escopo e as contagens são diferentes, então não é uma comparação rigorosa). Nas duas execuções com /goal, digitamos o /goal manualmente, selecionamos e confirmamos a linha "Goal set:". As execuções aconteceram em 23 de outubro de 2026, no aplicativo de desktop para Windows com Claude Code 2.1.308, com o Claude Opus 5.5 como modelo de trabalho e o modo auto como modo de permissão.

Os números foram somados a partir dos registros de cada conversa (os arquivos JSONL que o Claude Code salva). O custo equivalente é o que o Claude Code calculou e registrou com base nas tarifas da API. Ele não é cobrado no uso por assinatura. Cada resultado vem de uma única execução, e o escopo e as contagens variam de uma execução para outra. Os números mudariam com outro tipo de tarefa ou outro modelo. As gravações de cache do avaliador correspondem à quantidade de conversa carregada para o julgamento. O custo equivalente é o total do trabalho e do avaliador.

As condições que de fato escrevemos

Estas são as condições escritas depois do /goal nas duas execuções. Nomes específicos deste site (o script de verificação, o arquivo de anotações de trabalho e as ferramentas que atualizam registros) foram substituídos por termos que dizem o que fazem. Os passos detalhados do trabalho (os precedentes de correção e os arquivos que não devem ser tocados) foram escritos em um arquivo de anotações de trabalho (um arquivo Markdown), e a condição apontava para esse arquivo.

# Execução menor
Para o texto em japonês dos artigos 200 a 209 (9 artigos), o script de verificação de pontos finais de frase informa 0 itens (mostre na conversa o resultado da verificação de cada um dos 9 artigos), e commit e push são concluídos seguindo os passos das anotações de trabalho. Pare depois de 30 turnos.

# Execução maior
Para o texto em japonês dos artigos 100 a 199, o script de verificação de pontos finais de frase informa 0 itens. Mantenha: siga os passos das anotações de trabalho (corrija apenas a pontuação, seguindo os precedentes definidos; não altere palavras, sentido, traduções, metadados ou ferramentas). Ao fim de cada turno, escreva uma linha dizendo "restam ○ itens (○ artigos)". No final, mostre na conversa o resultado da verificação dos 48 artigos do escopo, a lista de arquivos alterados (somente o texto e os registros de consistência), uma verificação de tags aprovada e o resultado da atualização dos registros de consistência, e então conclua commit e push por caminho. Não faça deploy. Pare depois de 40 turnos.

Na execução menor, "escreva a contagem restante a cada turno" estava escrito apenas nas anotações de trabalho. O Claude terminou sem escrever isso, e o avaliador julgou o objetivo "atendido", observando no motivo que "a instrução do procedimento não foi seguida, mas a condição não exige isso". Incorporamos essa lição (capítulo 4) na condição da execução maior.

Verificando o resultado final

Não aceitamos o "atendido" do avaliador pelo valor aparente. Em cada caso, verificamos as diferenças linha por linha em uma conversa separada e refizemos as verificações.

6. O que aprendemos: tarefas adequadas e inadequadas

Tarefas mecânicas terminam em um turno

Todas as execuções terminaram o trabalho em um turno. Dentro de um turno, o Claude pode usar ferramentas dezenas de vezes (a execução maior usou o Bash 32 vezes), então uma tarefa que um script resolve termina de uma vez, mesmo com 321 itens. Por isso, a principal vantagem do /goal, "se faltar algo, continue no próximo turno", nunca entrou em ação nesse tipo de trabalho. Os resultados vêm de uma execução por escopo, mas entre a referência com pedido comum e as duas execuções com /goal, não vimos grande diferença de tempo ou de qualidade do resultado. O custo adicional foi de uma avaliação por execução, e cada avaliação levou 5,6 segundos e 9,0 segundos (o trabalho inteiro levou cerca de 6 minutos e cerca de 10 minutos).

O avaliador lê a conversa inteira

Na execução maior, o avaliador leu 114.410 tokens, que correspondem à conversa de trabalho inteira repassada como estava. Quanto mais longa a conversa, mais pesada cada avaliação. Para trabalhos que rodam muitos turnos, ou para iniciar o /goal no meio de uma conversa já longa, o custo da avaliação tende a ser maior do que nesta execução.

O avaliador verifica se a condição foi atendida

O avaliador verificou com precisão os itens da condição, como os resultados da verificação e a existência de um commit. Por outro lado, ele não verifica qualidades que não aparecem em números, como se uma frase soa natural. "Atendido" significa que o que foi escrito na condição apareceu na conversa. Ele não substitui a verificação do resultado final.

Este experimento testou apenas "trabalhos que terminam em um turno". A seguir, separamos os exemplos da documentação oficial da visão do autor sobre tarefas adequadas.

7. Diferenças em relação ao /goal do Codex

A OpenAI Codex também tem um /goal com o mesmo nome. A ideia (continuar trabalhando mantendo uma condição de término) é a mesma, mas as operações e a forma de definir limites são diferentes. Para instruções detalhadas do Codex, veja Como usar o /goal do Codex.

Fontes: para o Claude Code, Keep Claude working toward a goal; para o Codex, Using Goals in Codex (OpenAI Cookbook) e o artigo deste site "Como usar o /goal do Codex". Ambas atualizadas em 24 de outubro de 2026.

Resumo

• O /goal é um comando em que você escreve uma condição de término, e um modelo separado a julga ao fim de cada turno, mantendo o Claude trabalhando até a condição ser atendida. O mesmo comando faz a definição, a verificação do status e a limpeza.
• O avaliador lê apenas a conversa. Escreva a condição de forma que o estado final, a forma de verificação e o que deve ser mantido possam ser comprovados pela saída do Claude, e inclua também o limite nela.
• O modo de permissão não muda, então, se você quiser delegar o trabalho, combine o /goal com o modo auto.
• No experimento deste site, uma tarefa mecânica terminou em um turno mesmo com 321 itens. Para essa tarefa de um turno, o custo adicional foi de uma avaliação. Na visão do autor, o benefício aparece em trabalhos que não conseguem terminar em um turno.
• "Atendido" significa que o que foi escrito na condição apareceu na conversa. Verifique a qualidade do resultado final, como a naturalidade das frases, separadamente.
• Ao colar uma condição inteira no aplicativo de desktop, ela pode não funcionar como comando. Confirme pela linha "Goal set:".

Passos para começar: mude para o modo auto → escreva a condição no formato do capítulo 4 (estado final, forma de verificação, o que deve ser mantido, limite) → digite o /goal manualmente, cole a condição e confirme "Goal set:" → depois que ele informar "atendido", leia você mesmo as diferenças.

FAQ

P. Usar o /goal aumenta o custo?

Sim, na medida das avaliações. As avaliações são feitas por um modelo pequeno e rápido, e a documentação oficial diz que o custo é "geralmente muito pequeno". No experimento deste site, o trabalho que terminou em um turno teve uma avaliação, e ela levou alguns segundos. No entanto, como o avaliador lê a conversa inteira, quanto mais longa a conversa, mais pesada cada avaliação.

P. Como interrompo no meio do caminho?

Remova o objetivo com /goal clear. stop e cancel funcionam da mesma forma. Se estiver rodando com claude -p, interrompa com Ctrl+C. Limpar o objetivo não desfaz as alterações feitas até ali.

P. O avaliador pode dizer "ainda não" mesmo quando o Claude diz que terminou?

Pode. Por isso um modelo separado faz o julgamento. Se o avaliador disser "ainda não", o próximo turno começa usando o motivo dele como pista. Por outro lado, quando resultados que atendem à condição aparecem na conversa, o objetivo é "atendido", então a qualidade que você não escreveu na condição não fica garantida.

P. Em quantos turnos ele para?

Não há limite fixo. Ele para quando a condição é atendida, quando é julgada impossível, quando aparece um erro que precisa de correção, ou quando você o remove. Se quiser um limite, escreva-o na condição, por exemplo "ou pare depois de 20 turnos". Como o avaliador lê apenas a conversa, ajuda incluir na condição algo como "ao fim de cada turno, informe o número de turnos decorridos". (Nenhuma execução deste experimento terminou em um turno só, então não testamos a parada por limite.)

P. Devo usar o /loop ou o /goal?

Use o /goal quando o estado final estiver definido. Use o /loop quando quiser verificar a mesma coisa em intervalos definidos. Por exemplo, "verifique a cada 5 minutos até o deploy terminar" serve para o /loop, e "corrija até que todos os testes passem" serve para o /goal.

Referências: Keep Claude working toward a goal, Run prompts on a schedule e Hooks guide (documentação oficial do Claude Code); Using Goals in Codex (OpenAI Cookbook). Verificadas em 24 de outubro de 2026.