O que é um 'turn' no reins?

O que é um ’turn’ no reins? Imagem: gerada por IA

Quem já entregou um trabalho grande a um agente de IA sabe disso. O loop desmorona sempre no mesmo ponto: o momento em que o modelo declara por conta própria “terminei” — quando, na verdade, não terminou.

O reins é um framework de quest CLI que tira da IA essa autoridade de declarar a conclusão e a entrega a uma máquina. Ele divide uma lista de trabalho em itens individuais, como quests de um jogo, entrega-os à IA um de cada vez e decide “está pronto?” não pela palavra da IA, mas por inspeção mecânica. E no seu coração há uma pequena unidade chamada turn.

Duas palavras vão aparecer o tempo todo, então vamos fixá-las primeiro.

Gate — um inspetor que verifica mecanicamente a submissão e decreta PASS ou FAIL. Não é a impressão de um humano, nem a autoavaliação da IA.
Ratchet (catraca) — uma engrenagem que gira em um único sentido. Usamos o termo para dizer que um item travado por uma aprovação nunca reabre.

Este artigo acompanha um turn do início ao fim, por tudo o que ele atravessa. O turn parece pequeno, mas, desmontado, é o reins em miniatura.

Os seis elementos centrais da Reins Engineering

Comprima em uma linha a engenharia sobre a qual o reins se apoia e ela diz: a engenharia de mover a autoridade de declarar a conclusão da IA para um gate mecânico determinístico. “Determinístico” aqui não é uma palavra difícil. Significa que a mesma entrada sempre produz o mesmo resultado. Um teste passa ou falha, e o veredicto de ontem não difere do de hoje conforme o humor.

Na linhagem prompt engineering (escolher as palavras) → context engineering (fornecer o contexto) → harness engineering (erguer as cercas), Reins é a rédea que define a direção. Essa engenharia é montada a partir de seis elementos.

#	Elemento	Uma linha	Frase canônica
1	Conclusão julgada pela máquina	A condição de conclusão deve ser respondível por sim/não por uma máquina, e é a máquina que julga — a IA é destituída da autoridade de decidir que terminou	“A conclusão é julgada pelo gate, não reivindicada”
2	Feedback determinístico	Fatos, não opiniões — “onde, o que deveria ser, o que de fato era” torna-se o sinal que aponta a correção	“Dê opiniões e ele bajula; dê fatos e ele corrige”
3	Contexto direcional (manual + exemplos)	Se o feedback é sinal de correção, o manual e os exemplos são sinais de direção — um não substitui o outro	“O gargalo não é a inteligência, é o contexto”
4	Ratchet Pattern (travamento de contrato)	Item aprovado é imutável; o trabalho restante só diminui — terminar é garantido pela estrutura	`remaining(t+1) ≤ remaining(t)`
5	Persistência do progresso	O progresso vive fora do processo (em disco) — mesmo que a IA morra, o progresso permanece	“Agents are disposable; progress is cumulative.”
6	Defesa contra o cheese (gates de domínio)	Mesmo uma verificação mecânica é burlada se só inspeciona a casca — o gate deve reverificar os fatos reais do seu domínio	“Um gate tem um domínio”

Tudo bem se os termos da tabela ainda soarem estranhos. O turn é a menor unidade em que esses seis se encontram dentro de um único ciclo; por isso, seguir um turn até o fim reúne os seis elementos, cada um no seu lugar. Esboçando o mapa de antemão: compose, o primeiro passo do turn, monta o contexto direcional e o feedback determinístico; judge entrega o veredicto mecânico (a defesa contra o cheese é a qualidade de projeto desse gate); record trava a catraca e persiste o progresso.

O que é um Reins Turn?

Um Reins Turn é a menor unidade de execução do reins, na qual uma tentativa sobre um item de quest se conclui como geração → julgamento → registro. Um loop não é nada além da repetição de turns, e o progresso de uma quest não é nada além do acúmulo de turns. Por isso a definição cabe em uma linha.

Turn N = o N-ésimo Attempt registrado. O que não foi registrado não é um turn.

Um Attempt é “um registro de uma tentativa”. Aqui há um ponto sutil — um turn não é “o LLM foi chamado uma vez”. A condição de existência de um turn não é a chamada, mas o registro. Se o LLM foi chamado, mas o resultado nunca foi registrado na catraca, esse turn nunca aconteceu. Inversamente, um resultado que um humano submeteu à mão, uma vez registrado, é um turn. Mesmo sem LLM. Quem conta os turns não é o modelo, é a catraca.

Essa definição única é a raiz de todas as propriedades que virão — independência de driver, resiliência a reinícios, auditabilidade. Por ora, deixe os nomes apenas passarem. Reencontraremos cada um em seu devido lugar.

Um turn são exatamente quatro passos

Um turn atravessa quatro passos em ordem. Os passos carregam nomes em inglês, mas o que fazem é simples — montar (compose), gerar (generate), julgar (judge), registrar (record).

Passo	O que faz	Propriedade
① compose	Lê o registro de todos os turns anteriores (o Log) e monta o prompt para o LLM	Função pura
② generate	Chama o LLM uma vez para produzir a saída	O único passo probabilístico
③ judge	O gate decreta sobre a saída (PASS / REVIEW / FAIL)	Determinístico
④ record	Aplica o veredicto à catraca e salva em disco	O único passo irreversível

“Função pura” significa que a mesma entrada sempre produz a mesma saída, sem outros efeitos colaterais, e “irreversível” significa que, uma vez executado, não pode ser desfeito. Então o núcleo da tabela aparece — dos quatro passos, só o ② é probabilístico, e só o ④ é irreversível. A geração não pode julgar, e o julgamento não pode gerar. A incerteza da IA fica confinada a uma célula, e a decisão que não se desfaz, a outra.

Vale registrar uma escolha de projeto peculiar. Essa cascata de quatro passos não está implementada como dois conjuntos de código Go. Ela é definida em um único documento legível por humanos chamado pkg/cli/turn.md (um documento TANGEUL), embutido no binário (go:embed) e interpretado em tempo de execução. A fonte canônica de “como um turn roda” não é código, é um documento legível — a razão dessa escolha retorna no fim deste artigo.

① compose — o contexto vem apenas do Log

O Log é o livro-razão, mantido em disco, no qual todos os turns até agora estão registrados. E a entrada para montar o prompt do turn N é exatamente uma: este Log. Estado que se esconde em algum canto da memória do programa e some quando o processo morre — isso não existe.

O prompt montado a partir do Log tem três camadas.

O que fazer — o que deve ser produzido para este item (as instruções de escrita e o contexto de verificação)
Manual — o prompt de sistema global e, se o turn anterior foi um FAIL, o coaching da regra que o causou (o manual por regra)
Cauda de feedback — os fatos do FAIL anterior. “Onde, o que deveria ser, o que de fato era”

Na linguagem dos seis elementos acima, o manual é o contexto direcional e a cauda de feedback é o feedback determinístico. Ambos são montados mecanicamente a partir do Log, a cada turn.

Há uma regra sutil, mas importante. O que compose toma como referência não é o último Attempt, e sim o último Attempt julgado — levado até o veredicto. Mesmo que um erro de geração, como uma queda do servidor do LLM, se interponha, o que a nova tentativa vê não é a mensagem de erro de infraestrutura, mas o feedback factual do FAIL anterior. Falhas operacionais não contaminam o contexto do trabalho.

② generate — o LLM apenas gera

O prompt montado vai ao backend de LLM em uma única chamada. Não importa se o backend é uma API HTTP (ollama/xai/gemini) ou uma ferramenta de linha de comando (claude/grok/codex/geminicli). De um jeito ou de outro, seu papel é fixo: gerador. O framework não expõe nenhuma API pela qual um LLM pudesse receber autoridade de PASS. Não é que o framework tenha “optado por não conceder” a autoridade de julgar — não há como concedê-la. É assim que o elemento 1 dos seis (conclusão julgada pela máquina) vira estrutura.

Até qual backend usar é recalculado a partir do Log a cada turn. Um item que continua falhando no modelo padrão é enviado a um mais forte (escalação), e essa decisão também é lida do Log a cada turn — “entre as regras causadoras dos FAILs passados, alguma é alvo de escalação?” Não há interruptor deixado ligado em algum lugar, nem variável local dentro do loop. Mesmo programa, mesmo Log — mesmo backend selecionado. A propriedade de se comportar de forma idêntica depois de você matar e reiniciar o processo — a resiliência a reinícios — vem de graça.

③ judge — só o gate julga

Quem decreta sobre a saída é o gate. Um gate é um conjunto de regras de detecção de violações. Cada regra dispara (fire) quando encontra o problema pelo qual é responsável e deixa para trás um fato — onde (Where), o que deveria ser (Expected), o que de fato era (Actual).

A agregação é determinística. Se ao menos uma regra Fail dispara, FAIL. Caso contrário, se uma regra Review dispara, REVIEW (uma zona cinzenta para um humano verificar). Se nada dispara, PASS. Mesma submissão, mesmas regras — sempre o mesmo veredicto. Não há aqui inspetor cuja resposta muda cada vez que se pergunta.

Em domínios complexos onde as regras se entrelaçam — onde uma violação torna outra verificação sem sentido — o veredicto pode ser elevado a um grafo de argumentação (toulmin), e a própria lógica de julgamento pode ser movida para um documento auditável (gate.md). Seja qual for a forma, uma coisa não muda: o juiz é uma máquina.

④ record — o único passo irreversível

Aplicar o veredicto à catraca, salvar em disco e exportar os itens concluídos. Este é o único ponto de um turn que não pode ser desfeito.

PASS / REVIEW / SKIPPED / BLOCKED → trava. A catraca é de sentido único; não volta atrás.
FAIL → o contador de tentativas (Tries) aumenta em 1 e o item permanece TODO. Ao atingir o máximo de tentativas (padrão 3), é travado como DONE. “Este item não funciona deste jeito” também é uma forma de conclusão — um item emperrado não tem permissão para manter o loop inteiro refém para sempre.
Erro de geração → é registrado no Log como um Attempt (o rastro do que aconteceu fica preservado), mas não consome uma tentativa. Um servidor de LLM que cai não é culpa do item; é uma falha operacional. Se a falha persiste, uma salvaguarda separada interrompe o loop (parada após N falhas de geração consecutivas — um circuit breaker).

Só com este passo passa a existir o Log que o compose do próximo turn vai ler. record é a conclusão do turn e o gerador do próximo turn.

A falha é um fato, não uma opinião

Em que forma um FAIL retorna — esta é a chave para um turn convergir (aproximar-se da resposta a cada nova tentativa). Não uma opinião como “a qualidade deixa um pouco a desejar”, mas isto:

FAIL. root cause = who-anchor-present
  Fact: where=who.anchors expected="source substring" actual="subgerente Carlos Mendes"

A leitura é simples. Qual campo (where), o que deveria ser (expected — uma string que existe de fato na fonte), o que de fato era (actual). Localização + valor esperado + valor real. Para o LLM, este é um feedback sem ninguém a quem bajular — números e localizações não são emoções. É esse fato estruturado que conduz um modelo bajulador não à discussão, mas à convergência.

Um bônus por cima. O texto de FAIL alimentado ao modelo é exatamente a mesma renderização da string impressa na tela quando um humano executa o comando submit (feedback parity). O feedback que o humano vê e o feedback que o modelo vê nunca divergem. O mistério de “o que diabos foi enviado à IA para que ela corrigisse assim?” está estruturalmente ausente.

Três pontos de entrada, um único turn

Chame de driver quem quer que conduza o turn. O reins tem três: next, em que um humano recebe o prompt diretamente; submit, em que um humano submete o resultado; e o loop automático, sem supervisão. Mas esses não são três implementações separadas. São três pontos de entrada no mesmo documento de turn. O que separa o manual do automático é exatamente uma regra dentro do documento.

A propriedade prática que isso rende: troque de driver no meio da quest e o prompt permanece idêntico byte a byte. Rode o loop automático ontem, deixe um humano assumir com next hoje — dado o mesmo estado do Log, sai o mesmo prompt. É possível porque o contexto vem apenas do Log (vimos isso no passo ①), e é uma propriedade provada, não uma esperança — um driver-swap golden test verifica a identidade byte a byte comparando as saídas entre drivers.

Acompanhando um turn até o fim

A teoria acabou. Vamos assistir a um turn real do começo ao fim. É um item de uma quest que extrai endereços de e-mail de documentos, na segunda tentativa, depois de o turn anterior ter dado FAIL com “não é um formato de e-mail válido”.

[Verificação de entrada do turn]  O item está TODO? Restam tentativas? → prosseguir
① compose      Encontra no Log o último Attempt judged → FAIL, causa = email-format
               Manual = prompt global + o coaching da regra email-format
               Prompt = o que fazer + "FAIL. Fact: where=email
                        expected='valid email format' actual='kim at example'"
② generate     Chamada ao LLM → {"email":"kim@example.com", ...}
③ judge        Varredura de regras: email-format passa, source-lacks-email passa, freemail passa
               → nenhuma regra Fail disparou → PASS
④ record       A catraca trava (irreversível) → Attempt #2 registrado → salvo → export

O modelo, recebendo o fato da falha anterior (“kim at example não é um formato de e-mail válido”), corrigiu exatamente aquele ponto; o gate confirmou a aprovação; a catraca travou. Este item agora é PASS para sempre. O próximo turn o pula, e o trabalho restante só diminui. Quando todos os itens alcançam um estado concluído (seja PASS, REVIEW ou o máximo de tentativas), o loop termina. Não “quando a IA sente que acabou”, mas quando os itens restantes chegam a zero. A convergência é garantida pela estrutura.

Loop Engineering — a indústria deu nome ao mesmo problema

Em junho de 2026, uma mudança na forma de lidar com agentes ganhou nome. Peter Steinberger escreveu “You shouldn’t be prompting coding agents anymore. You should be designing loops that prompt your agents” (você não deveria mais escrever prompts para agentes de código; deveria projetar os loops que fazem o prompt dos seus agentes), e, no início daquele mês, Boris Cherny, da Anthropic, criador do Claude Code, disse em um evento: “I don’t prompt Claude anymore. I have loops running… My job is to write loops” (eu não faço mais prompt para o Claude; tenho loops rodando… meu trabalho é escrever loops). Poucos dias depois, Addy Osmani, do Google, deu um nome à corrente: Loop Engineering — de uma pessoa que faz prompts para agentes a uma pessoa que projeta os sistemas que fazem prompts para os agentes.

Esse discurso desenha uma única narrativa de transição. Prompt engineering (escolher as palavras) → context engineering (escolher quais informações mostrar) → harness engineering (construir o ambiente de execução) → loop engineering (projetar o próprio ciclo de observar-agir-verificar-recuperar). A alavancagem foi se movendo para fora, uma camada por vez: das palavras à informação, da informação ao ambiente, do ambiente ao ciclo.

A anatomia de um bom loop segundo Osmani deve soar familiar a quem leu até aqui. Externalize o estado para o disco ou um quadro, não para a conversa. Separe o agente que constrói do agente que verifica. Deixe que a terminação seja confirmada por um adjudicador separado, não pela autodeclaração do agente de código. Coloque-a ao lado do turn e a correspondência é nítida.

Recomendação do Loop Engineering	Estruturação no turn do reins
Externalize o estado para disco ou quadro (o modelo esquece)	O Log não é um auxiliar de memória, é a única entrada do turn — compose é uma função pura do Log
Separe quem constrói de quem verifica (subagentes)	O verificador não é outro LLM, é um gate determinístico — não existe API alguma que conceda PASS
Defina condições de término testáveis	A monotonicidade da catraca garante a convergência como invariante — estrutura, não condição
Distinga falhas recuperáveis de falhas fatais	Embutido nas regras de record — um FAIL consome tentativa; erros de geração são assunto do circuit breaker

O coração da diferença é a distância entre recomendação e estrutura. A própria literatura de loop engineering admite a hierarquia da verificação — o LLM-as-judge, confiar o veredicto a uma IA, “can be gamed or can collude with the actor” (pode ser burlado ou pode conluiar-se com o ator), então, onde uma verificação determinística for possível, coloque uma verificação determinística. Mas isso permanece uma boa prática — uma recomendação confiada à boa vontade do projetista. Se o subagente verificador também é, no fim das contas, um LLM, a porta do conluio continua aberta. O reins fecha essa porta por projeto. Só o gate julga, e o framework não expõe nenhum caminho para dar um PASS a um LLM.

E, onde o loop engineering fala do loop inteiro, o reins transforma uma volta desse loop em contrato. Para ir um passo além do “meu trabalho é escrever loops” de Cherny, é preciso definir primeiro o que um loop faz em uma volta — o que é probabilístico, o que é determinístico, o que é irreversível. O nome dessa definição é turn.

Por que esta unidade

Aperte o turn desse jeito e você ganha três coisas. Os nomes que passaram de raspão lá atrás encontram aqui os seus lugares.

Auditabilidade — a resposta a “em que o loop automático difere do next manual?” não é um trabalho de comparar duas bases de código, mas uma única regra em um documento. Você pode confirmar com os próprios olhos que existe exatamente um caminho no documento capaz de travar um PASS. É por isso que a fonte canônica do turn é um documento legível, não código.
Resiliência a reinícios — toda entrada de um turn deriva do Log em disco; assim, mesmo que o processo morra, o mesmo Log reproduz o mesmo turn.
Descartabilidade dos agentes — troque os agentes (LLMs, drivers) e o progresso continua se acumulando, sem jamais retroceder. “Agents are disposable; progress is cumulative.”

Dito ao contrário: um sistema em que o turn é borrado — em que o contexto se esconde na memória da sessão, o modelo autodeclara a conclusão e as novas tentativas se apoiam no histórico da conversa — perde os três.

O turn parece pequeno. Mas, como a menor unidade que separa e serializa geração (probabilidade), julgamento (determinismo) e registro (irreversibilidade) dentro de um único ciclo, entender o turn é entender o reins por inteiro.

Leitura adicional (externa)

Building Effective Agents — Anthropic — o clássico do desenho de loops de agentes. Sua distinção entre “workflows (orquestração determinística) e agentes (dirigidos pelo modelo)” ressoa com a separação geração/julgamento deste artigo.
Agentic Loops: From ReAct to Loop Engineering — Data Science Dojo — um panorama da linhagem dos loops de agentes, do ReAct ao loop engineering.
The Anthropic leader who built Claude Code says he ditched prompting — now he just writes loops — The New Stack — a cobertura da indústria sobre a virada de Boris Cherny.

Fontes

Loop Engineering — Addy Osmani — 2026-06. A cunhagem do termo e a anatomia de um bom loop (automação, worktrees, skills, subagentes, adjudicadores separados, externalização de estado).
What Is Loop Engineering? A Complete Guide from Prompt to Harness Engineering — Tosea.ai — a transição em quatro estágios prompt→contexto→harness→loop, a hierarquia de verificação com o determinismo em primeiro lugar e o risco de conluio do LLM-as-judge.
Claude Code’s Creators Explain Agent Loops — The Neuron — Boris Cherny e Cat Wu sobre a operação de loops em detalhe: /loop e /goal, externalização de estado para disco e Linear, separação entre quem constrói e quem verifica.