Dicionário de IA

Um rótulo em movimento, não uma tecnologia. “IA” não nomeia algo fixo como modelo ou token — aponta para aquilo que os computadores conseguem fazer de maneira nova e impressionante. Hoje, aponta para grandes modelos de linguagem. Já apontou para coisas bem diferentes:

O rótulo se desloca por um mecanismo conhecido, às vezes chamado de efeito IA: quando uma técnica funciona de forma confiável, ela recebe outro nome — vira “apenas” busca, “apenas” estatística — e “IA” avança para o próximo problema ainda não resolvido. A observação é antiga. Bertram Raphael expressou a ideia em 1971: “IA é um nome coletivo para problemas que ainda não sabemos resolver direito com computadores.” A versão de Larry Tesler, por volta de 1979, foi: “Inteligência é aquilo que as máquinas ainda não fizeram.”

É por isso que tantas conversas sobre IA parecem desencontradas. Uma afirmação como “a IA não consegue raciocinar” ou “a IA é superestimada” contém uma marca temporal implícita — pode referir-se a sistemas especialistas, a classificadores de imagens da década de 2010 ou ao modelo de linguagem do mês passado, e cada referência leva a uma conclusão diferente. Quando uma discussão sobre IA empaca, normalmente a solução é substituir a palavra pelo termo preciso que se pretende usar: o modelo, o ambiente de execução, o agente, o contexto que recebeu.

Evite: “IA” em qualquer afirmação técnica — nomeie a parte a que você se refere. “Programação com IA” funciona como rótulo para a prática; “a IA está alucinando”, não.

Exemplo de uso:

“O CTO quer saber se a IA poderia cuidar da fila de triagem.”

“Esclareça isso antes de definir o escopo — ela quer dizer um modelo de linguagem com acesso ao sistema de tickets. ‘IA’, por si só, não é uma especificação.”

Os parâmetros. Sem estado — faz previsão do próximo token e nada mais. “Claude Opus 4.x” e “GPT-5.x” são modelos. Sozinho, um modelo não consegue fazer nada como agente; precisa ser integrado a um ambiente de execução.

Modelos não podem ler arquivos, executar comandos, navegar na web nem lembrar do dia anterior — recebem tokens e preveem tokens de saída, uma vez por solicitação ao provedor do modelo. Tudo que dá a impressão de um agente trabalhando — escolhendo ferramentas, lendo resultados, repetindo até terminar a tarefa — é o ambiente coordenando muitas dessas previsões em sequência.

Provedores de modelos oferecem modelos em categorias: um modelo grande, mais inteligente, mas lento e caro, e modelos menores, mais rápidos e baratos, porém menos capazes. Escolher a categoria é uma decisão real — um modelo robusto para planejamento e depuração difícil, um leve para alterações mecânicas —, e os ambientes permitem alternar durante uma sessão.

A precisão no uso da palavra também melhora o diagnóstico. “O modelo é ruim nisso” é uma afirmação específica — o mesmo modelo em outro ambiente de execução ou com contexto diferente pode se comportar de maneira completamente distinta. Antes de culpar o modelo, verifique o que recebeu: a maior parte das saídas decepcionantes é explicada pelo contexto ou pelo ambiente, não pelos parâmetros.

Exemplo de uso:

“Devemos trocar o modelo de Sonnet para Opus na etapa de planejamento?”

“Experimente — mas o ambiente faz a maior parte do trabalho nesta tarefa. Trocar de modelo não vai ajudar se o prompt de sistema e as ferramentas estiverem errados.”

Os números dentro de um modelo — muitas vezes bilhões deles — ajustados durante o treinamento. Tudo que o modelo “sabe” está neles. O treinamento os define; a inferência os utiliza sem alteração. Também são chamados de pesos.

Tecnicamente, os parâmetros são o que transforma uma entrada em saída. A previsão do próximo token é um cálculo gigantesco: os tokens da janela de contexto entram, são multiplicados pelos parâmetros e geram uma previsão do token seguinte. Não existe um banco de dados de fatos dentro do modelo, nem uma tabela de consulta de código — apenas esses números, organizados para que o cálculo tenda a produzir resultados úteis. Fatos que o modelo consegue recitar do treinamento, como a API de uma biblioteca padrão, constituem conhecimento paramétrico: são armazenados nos parâmetros, não recuperados de algum lugar.

Vale internalizar que os parâmetros ficam fixos depois do treinamento. Nada que você faça durante uma sessão os altera — nenhuma correção, base de código ou erro com que o modelo aprenda. Todas as sessões usam os mesmos números. É por isso que o modelo é sem estado, que seu conhecimento integrado termina na data-limite de conhecimento e que qualquer informação específica do projeto precisa vir do contexto. Os parâmetros só mudam com mais treinamento — o que, na prática, produz outro modelo.

Exemplo de uso:

“Podemos ajustá-lo com nossa base de código?”

“Isso atualizaria os parâmetros — e depois teríamos outro modelo. Para um único projeto, quase sempre é mais barato carregar a base de código como contexto do que treinar de novo.”

O processo que define os parâmetros de um modelo, expondo-o a grandes volumes de texto e ajustando os parâmetros para melhorar a previsão do próximo token. É um processo caro, realizado uma única vez pelo provedor do modelo. Inclui o pré-treinamento (a etapa principal) e o pós-treinamento (refinamentos posteriores, como seguir instruções e garantir segurança); essa distinção não é importante para o nível deste glossário.

O mecanismo consiste em repetir em grande escala: mostra-se ao modelo um trecho de texto, pede-se que preveja o token seguinte, ajustam-se os parâmetros na direção do token que realmente vinha a seguir e repete-se o processo trilhões de vezes. Nenhum fato ou regra é armazenado — tudo que o modelo “sabe” é um efeito colateral de prever cada vez melhor, comprimido nos parâmetros como conhecimento paramétrico.

Duas consequências importam no dia a dia. O treinamento termina em determinado momento, então o modelo tem uma data-limite de conhecimento — não viu a versão da biblioteca para a qual você atualizou no mês passado. E não é você quem pode treinar o modelo: quando ele não conhece sua base de código, suas convenções ou APIs internas, a solução nunca é “ensinar o modelo”, mas inserir esse material no contexto, a única entrada que você controla.

Exemplo de uso:

“Podemos fazer com que ele conheça nossa API interna?”

“Não por meio de treinamento — isso leva meses e é feito pelo provedor do modelo. Carregue a documentação da API no contexto; essa é a alavanca que você realmente controla.”

Executar um modelo treinado para gerar uma resposta — é o que acontece a cada solicitação ao provedor do modelo. Os parâmetros permanecem fixos; o modelo apenas faz previsão do próximo token sobre o contexto recebido. É barato em relação ao treinamento, mas cobra por token e representa o principal custo de usar um modelo.

A vida de um modelo se divide em duas fases:

Nada que você faz durante a inferência é gravado de volta nos parâmetros — é por isso que uma correção feita hoje não se mantém amanhã. O modelo que comete o mesmo erro na próxima sessão, depois de você explicar a correção com cuidado, não ignorou você; é incapaz de aprender com a interação. O modelo é sem estado — a continuidade tem que vir de fora dele, da janela de contexto ou de um sistema de memória.

Esse mecanismo também explica a cobrança. Cada solicitação executa o modelo sobre o contexto completo, então o custo aumenta com tokens de entrada e tokens de saída, e um agente que faz dezenas de chamadas de ferramenta paga pela inferência em cada ida e volta. Por isso o tamanho do contexto é uma questão de custo, além de qualidade.

Exemplo de uso:

“Por que a conta cresce conforme o uso, em vez de ser uma licença com preço fixo?”

“Você está pagando pela inferência — cada solicitação ao provedor executa o modelo no hardware dele. O treinamento já ocorreu, mas o custo da inferência é acumulado por solicitação, e um único turno pode virar muitas solicitações quando há chamadas de ferramentas.”

Esforço é um seletor da quantidade de raciocínio que um modelo realiza antes de responder. Definido por solicitação ao provedor do modelo, controla por quanto tempo o modelo pensa antes de começar a escrever a resposta que você verá. Esse raciocínio é gerado durante a inferência, como todo o restante; o ambiente de execução muitas vezes o esconde, mas é trabalho real realizado pelo modelo.

Um esforço maior custa mais e demora mais. O raciocínio é emitido como tokens, cobrado como tokens de saída mesmo quando você não o vê e produzido um token de cada vez — portanto, aumentar o esforço prolonga a espera pela resposta e acrescenta custo. A troca é mais deliberação em troca de velocidade e preço.

A maioria dos ambientes oferece níveis de esforço em uma escala curta:

Os sintomas de uma configuração errada aparecem nos dois sentidos. Defina esforço baixo demais para um problema difícil e você recebe uma resposta confiante e superficial, que ignorou o raciocínio necessário — parece correta, mas está errada de um jeito que custa caro depois. Defina-o no máximo para renomear uma variável e você espera por um longo raciocínio que não produz nada que o nível mais baixo não produziria.

Ajuste o esforço à tarefa, não à sessão. Aumente-o para a parte que realmente exige raciocínio difícil e reduza-o para o trabalho repetitivo ao redor.

Exemplo de uso:

“Ele continua estragando esta correção de concorrência — já expliquei três vezes.”

“Aumente o esforço. É um bug que exige muito raciocínio e, na configuração padrão, ele não está pensando por tempo suficiente antes de escolher uma abordagem.”

A unidade atômica que um modelo lê e escreve. Tem aproximadamente o tamanho de uma palavra, mas não exatamente — palavras comuns correspondem a um token; palavras raras ou longas se dividem em vários. O tamanho, o custo e a latência da janela de contexto são todos medidos em tokens.

Um tokenizador converte o texto em tokens: um vocabulário fixo de dezenas de milhares de fragmentos, aprendido antes do treinamento, que divide qualquer entrada em uma sequência de itens desse vocabulário. O modelo nunca vê caracteres ou palavras: cada trecho de texto é convertido em tokens na entrada, e a previsão do próximo token gera a saída um token de cada vez.

Como regra prática, um token corresponde a cerca de três quartos de uma palavra em inglês, então mil tokens equivalem aproximadamente a 750 palavras. Código é menos previsível: palavras-chave e expressões comuns são tokenizadas de forma compacta, enquanto identificadores gerados, hashes, blocos base64 e saídas minificadas se dividem em muitos tokens por “palavra”. O padrão é: texto frequente no material de origem do tokenizador recebe codificações curtas e eficientes; o texto menos frequente é dividido em muitos fragmentos pequenos. Um hash como `a3f9c2e1` nunca apareceu em lugar algum, então se divide em muitos tokens, enquanto `function` é um só. Por isso, um arquivo aparentemente pequeno, cheio de sequências incomuns, pode ocupar uma parte surpreendente da janela de contexto.

Tokens são a unidade de medida para todo o resto. O custo é cobrado por token — provedores cobram tokens de entrada e tokens de saída separadamente. A velocidade é medida em tokens por segundo, pois a saída é gerada um token por vez. E a janela de contexto tem um número fixo de tokens, então a quantidade de tokens dos seus arquivos determina quanto cabe nela.

Evite: “palavra” — os limites dos tokens não correspondem aos limites entre palavras, e tokens por segundo / tokens por dólar são as unidades que realmente importam.

Exemplo de uso:

“Qual será o tamanho deste prompt?”

“Passe-o pelo tokenizador — o esquema é compacto, mas as chaves JSON são estranhas, então vão gerar mais tokens do que você imagina.”

Aquilo que o modelo realmente faz. Dado um contexto, escolhe por amostragem o token seguinte, acrescenta-o e executa outra vez. Cada saída — uma frase, uma chamada a ferramenta, um ficheiro de mil linhas — é construída token a token. O modelo não tem outro modo de funcionamento.

Cada etapa funciona da mesma maneira: os tokens na janela de contexto passam pelos parâmetros, que produzem uma probabilidade para cada token do vocabulário — este é muito provável a seguir, aquele menos provável. Um token é selecionado por amostragem com base nessas probabilidades, acrescentado, e o ciclo volta a executar-se com o contexto ligeiramente maior. Essa amostragem explica por que o mesmo pedido produz saídas diferentes em execuções distintas: a não determinismo faz parte do mecanismo, não é um erro acrescentado por cima.

Compreender este mecanismo explica comportamentos que, de outra forma, parecem estranhos. O modelo nunca verifica se um token é verdadeiro antes de o emitir — apenas se é provável —, o que está na origem da alucinação. Compromete-se com cada token à medida que avança, por isso uma frase inicial que soa confiante pode encaminhar o resto da resposta na direção errada. E, como os tokens de saída são produzidos estritamente um de cada vez, a velocidade de geração impõe um limite mínimo à rapidez com que qualquer agente consegue trabalhar.

Uso:

«Como é que o agente “decide” chamar uma ferramenta?»

«Não decide: no fim de contas, é sempre previsão do token seguinte. A chamada à ferramenta é apenas uma cadeia estruturada que o harness extrai do fluxo de saída.»

La misma entrada puede producir resultados distintos. Ejecuta dos veces un modelo con un contexto idéntico y podrías obtener dos respuestas diferentes: a veces cambia una palabra; otras, el enfoque por completo. No hace falta que cambie nada en tu código para que ocurra.

Es una característica de cómo los modelos generan texto y de cómo los proveedores de modelos atienden las solicitudes. Durante la inferencia, el modelo produce una distribución de probabilidad sobre los posibles tokens siguientes y se toma una muestra de ella, normalmente con algo de aleatoriedad intencionada: elegir siempre el token más probable tiende a generar texto repetitivo y de menor calidad. Un token distinto al principio de la respuesta cambia todos los que vienen después; así, una sola palabra diferente puede convertirse en un enfoque completamente distinto. El servicio del proveedor añade aún más variación: las solicitudes se agrupan en lotes y se procesan en hardware compartido, y pequeñas diferencias de coma flotante entre lotes pueden decantar una decisión reñida entre dos tokens. No hay ningún ajuste que puedas cambiar para eliminarlo por completo.

Espera cierta variación en los resultados de un agente ante la misma tarea. La mayoría de las respuestas se sitúan dentro de una curva de calidad razonable —por eso esta no determinación resulta tolerable—, pero los extremos existen: algunos días el modelo parece lúcido; otros, como si hubiera perdido el hilo. La misma tarea, una tirada distinta. Esto tiene dos consecuencias prácticas. Reintentar es una estrategia válida: un intento fallido es una muestra de la distribución, y un nuevo intento con la misma tarea puede salir mejor. Y verificar importa más que con las herramientas deterministas: no puedes probar el comportamiento de un agente una sola vez y confiar en que lo repetirá, así que las comprobaciones automatizadas tienen que detectar las muestras defectuosas.

Procura no construir una historia de más alrededor de esto. Las personas detectamos patrones, y una racha de ejecuciones malas puede parecer una prueba de que «el modelo ha empeorado esta semana». Normalmente solo es la distribución.

Uso:

«Claude ha estado fatal hoy. ¿Han lanzado una versión peor?»

«Probablemente no: la salida del modelo no es determinista. Habrá días buenos y malos con la misma tarea. Vuelve a intentarlo mañana antes de buscar una causa».

Qualquer serviço que disponibilize um modelo para inferência. Normalmente é um serviço remoto (Anthropic, OpenAI, Google), mas também pode ser local — Ollama, LM Studio ou llama.cpp a correr na tua máquina. O harness não executa o modelo; pede a um fornecedor que o faça.

O fornecedor é responsável pela infraestrutura: os parâmetros estão no seu hardware, e cada pedido ao fornecedor do modelo é o harness a enviar tokens pela rede e a receber previsões de volta. Isso torna o fornecedor a origem de uma categoria inteira de problemas que são atribuídos erradamente ao modelo ou ao harness — limites de utilização, capacidade degradada e interrupções acontecem aqui. Quando o agente fica parado a meio de uma sessão ou falha em cada turno, vale a pena consultar primeiro a página de estado do fornecedor.

O fornecedor também define os termos comerciais: preço por token de entrada e saída, descontos da cache de prefixos e quais os modelos disponíveis. Nota que o fornecedor e o criador do modelo podem ser empresas diferentes — Bedrock, Vertex e OpenRouter servem modelos de terceiros.

Os fornecedores locais trocam capacidade por controlo: os modelos que cabem no teu hardware são muito menores do que os modelos de ponta, mas nada sai da máquina e não há cobrança por token.

Uso:

«Podemos executar isto offline para o cliente com rede isolada?»

«Muda o fornecedor do modelo para um local — Ollama ou llama.cpp na máquina deles. O harness não se importa; limita-se a aceder a outro endpoint.»

Tudo ao redor do modelo que o transforma em um agente: ferramentas, prompt de sistema, gestão da janela de contexto, permissões, hooks. Claude.ai e Claude Code usam o mesmo modelo, mas se comportam de maneira diferente porque seus ambientes são diferentes.

O modelo em si só faz uma coisa: recebe texto e produz texto. Não consegue ler um arquivo, executar um comando nem lembrar o turno anterior. O ambiente fornece tudo isso. Ele monta o contexto de cada solicitação ao provedor do modelo, executa as chamadas de ferramentas pedidas pelo modelo, devolve os resultados de ferramentas, armazena o histórico da sessão, pede sua permissão antes de ações arriscadas e decide quando compactar. O ciclo do agente — o modelo propõe, o ambiente executa, e assim por diante — é conduzido pelo ambiente.

Isso importa para o diagnóstico. Quando o comportamento difere entre dois produtos, ou entre ontem e hoje, muitas vezes a variável não é o modelo, mas o ambiente. Outro prompt de sistema, outro conjunto de ferramentas, um padrão de permissões diferente ou uma nova estratégia de gestão de contexto alteram o comportamento sem mudar o modelo. Também significa que a maior parte da sua configuração fica no ambiente: arquivos AGENTS.md, configurações de permissão e hooks são instruções para o ambiente, não para o modelo.

Exemplos: Claude Code, Cursor, Codex CLI — e Claude.ai, que é um ambiente de chat, não de programação.

Exemplo de uso:

“É o mesmo modelo; por que o Claude Code edita arquivos e o Claude.ai só responde às perguntas?”

“São ambientes diferentes — o Claude Code tem ferramentas de sistema de arquivos, outro prompt de sistema e uma camada de permissões. O modelo não é a variável aqui.”

Uma ida e volta do ambiente de execução ao provedor do modelo. O ambiente envia o contexto atual; o provedor retorna uma resposta (chamada de ferramenta ou resposta final). Uma única mensagem do usuário pode gerar muitas solicitações ao provedor se o agente chamar ferramentas — cada resultado de ferramenta aciona outra solicitação.

Cada solicitação carrega tudo: o prompt de sistema, toda a conversa até o momento e cada resultado de ferramenta. O modelo é sem estado, então o provedor não mantém nada entre solicitações — a solicitação quarenta reenvia o conteúdo da trinta e nove, mais um resultado de ferramenta. O cache de prefixo existe para tornar essa repetição acessível.

A solicitação também é a unidade de cobrança. Tokens de entrada, tokens de saída e descontos de cache são contabilizados por solicitação, e é por isso que uma pergunta aparentemente simples pode custar surpreendentemente caro: o custo não é proporcional à sua mensagem, mas à quantidade de solicitações multiplicada pelo tamanho do contexto que cada uma carrega.

Vale a pena distinguir a solicitação do turno. Um turno é uma troca com você, e um único turno — “corrija o teste que está falhando” — pode se desenrolar como uma cadeia de solicitações:

Seis solicitações para um turno — cada uma reenvia o contexto inteiro. Quando quiser saber para onde foram os tokens, conte as solicitações, não os turnos.

Exemplo de uso:

“Uma pergunta consumiu quarenta mil tokens?”

“Veja as chamadas de ferramentas — doze grep, oito leituras, quatro edições. Cada resultado de ferramenta gera outra solicitação ao provedor, e o prefixo da sessão inteira é reenviado a cada vez.”

Os tokens que o harness envia em cada pedido ao fornecedor do modelo: o pedido de sistema, o histórico da conversa, os resultados de ferramentas, tudo o que o modelo lê antes de escrever. São cobrados a um preço inferior ao dos tokens de saída, porque processá-los custa menos do que produzir tokens de saída.

Em programação com IA, os tokens de entrada constituem a maior parte da fatura. O modelo não tem estado, por isso cada turno volta a enviar a sessão inteira como entrada: a tua primeira mensagem, todas as respostas e todos os resultados de ferramentas desde então. A entrada do turno cinquenta contém os quarenta e nove turnos anteriores. Um único pedido ao fornecedor do modelo pode produzir algumas centenas de tokens de saída, mas reenviar cem mil tokens de entrada do histórico acumulado.

A cache de prefixos reduz o custo: o histórico que corresponde exatamente a um pedido anterior é cobrado como tokens em cache baratos, em vez de entrada ao preço total. Quando o custo da entrada continua elevado, a solução é reduzir o que volta a ser enviado — limpando ou compactando entre tarefas.

Uso:

«A fatura é alta, mas o agente quase não escreve nada.»

«São os tokens de entrada — cada turno volta a enviar a sessão inteira. Sem a cache de prefixos, pagarias novamente o histórico em cada pedido.»

Os tokens que o modelo gera. São cobrados a um preço superior aos tokens de entrada — normalmente cerca de cinco vezes mais — porque exigem mais capacidade de computação para serem produzidos.

Conta tudo o que o modelo escreve: a prosa que lês, o código que produz, as chamadas a ferramentas e qualquer raciocínio prolongado que faça antes de responder. Este último ponto surpreende as pessoas — os tokens de raciocínio são cobrados como saída mesmo quando o harness muitas vezes não os mostra, e aumentar o esforço consome mais deles.

Os tokens de saída também determinam o ritmo de uma sessão. O modelo lê a entrada rapidamente, mas gera a saída um token de cada vez; por isso, quando um turno parece lento, quase sempre é a saída a ser escrita, não a entrada a ser lida. Uma espera longa costuma significar que está a chegar uma resposta longa.

Uso:

«A sessão de refatorização está a consumir créditos, apesar de as entradas serem pequenas.»

«O agente está a reescrever ficheiros inteiros em vez de aplicar patches. Os tokens de saída custam cerca de cinco vezes mais do que a entrada — faz com que emita edições e a fatura baixa.»

O armazenamento do lado do provedor do modelo que permite que solicitações ao provedor do modelo consecutivas pulem o reprocessamento de um prefixo compartilhado. Quando o início de uma solicitação corresponde ao início de outra recente — mesmo prompt de sistema, mesmo histórico até certo ponto —, o provedor reutiliza o trabalho anterior e cobra esses tokens como tokens em cache, a uma tarifa muito menor.

O cache compensa porque as sessões só crescem com acréscimos. Cada solicitação reenvia todo o histórico como tokens de entrada (consulte essa definição para saber por quê) e, em uma sessão normal, o histórico só muda no final — cada solicitação contém a anterior mais algumas mensagens novas. O provedor processa uma vez o longo começo compartilhado, armazena o resultado e continua de onde o prefixo termina. Sem o cache, uma sessão de 50 turnos pagaria para reprocessar o primeiro turno cinquenta vezes.

Os caches também expiram. O tempo durante o qual uma entrada permanece ativa varia conforme o provedor do modelo — normalmente minutos, não horas. Deixe uma sessão ociosa além desse intervalo e a próxima solicitação reconstruirá o prefixo uma vez pelo preço integral antes que o cache volte a funcionar. Isso preocupa principalmente quem desenvolve o ambiente de execução; para o usuário, o efeito visível é que as solicitações após uma longa pausa custam mais do que as anteriores.

Exemplo de uso:

“Por que a conta aumentou muito na metade da sessão?”

“O ambiente começou a inserir a hora atual no prompt de sistema em cada turno. O cache de prefixo se desfaz no primeiro token alterado, então todas as solicitações seguintes foram cobradas pela tarifa integral.”

Tokens de entrada que o fornecedor guardou em cache de um pedido ao fornecedor do modelo anterior, para não ter de os processar novamente. Quando pedidos consecutivos partilham um prefixo, o fornecedor reutiliza o trabalho através da cache de prefixos e cobra a parte guardada em cache a um preço muito inferior. É o que torna acessíveis as sessões longas: sem isto, cada turno voltaria a cobrar todo o histórico.

Isto importa por causa da forma como as sessões são faturadas. O modelo não tem estado, por isso cada pedido volta a enviar a conversa inteira — o pedido de sistema, todas as mensagens e todos os resultados de ferramentas — como tokens de entrada. No turno cinquenta, cada pedido contém cinquenta turnos de histórico, e pagarias o preço total por tudo isso em cada pedido. A cache altera as contas: os tokens que o fornecedor já processou num prefixo idêntico são cobrados como tokens em cache, muitas vezes a um décimo do preço de entrada ou menos. Numa sessão longa, a maior parte do que envias são tokens em cache e a fatura mantém-se razoável.

Um exemplo mostra quando os tokens ficam em cache e quando não ficam. Cada letra representa um bloco de conteúdo da conversa; cada pedido envia a conversa acumulada até então:

A cache é frágil de uma forma específica: corresponde a prefixos exatos. Se algo mudar mais cedo na conversa — o harness reordena conteúdo, um carimbo temporal é atualizado, a representação de um ficheiro muda —, a partir desse ponto a cache falha e tudo o que vem depois é cobrado ao preço total dos tokens de entrada. As caches também expiram após alguns minutos de inatividade, por isso uma sessão retomada depois de uma pausa longa volta a pagar uma vez pelo histórico. Quando o custo de uma sessão aumenta sem causa evidente, compara os tokens em cache com os tokens de entrada no relatório de utilização — uma cache quebrada aparece primeiro aí.

Uso:

«As sessões longas custam imenso — oito dólares por uma refatorização.»

«Verifica os tokens em cache. Se o harness estiver a reordenar o pedido de sistema ou os ficheiros entre turnos, o prefixo quebra e pagas novamente o preço total de entrada em cada pedido.»

Não leva informações adiante. O modelo não mantém estado entre solicitações ao provedor do modelo — cada solicitação reenvia a janela de contexto inteira, pois o modelo não tem como ver mais nada. Por padrão, o agente também não mantém estado entre sessões: uma sessão nova começa vazia, sem qualquer vestígio das anteriores. Contraponto a com estado.

O próprio modelo é permanentemente sem estado: seus parâmetros ficam fixos após o treinamento, e nada que você faça durante a inferência os modifica. O modelo não aprende com suas correções, não se lembra de ouvir a mesma coisa ontem e não está conhecendo você — por mais que a conversa possa dar essa impressão. A sensação de continuidade dentro de uma sessão é produzida pelo ambiente de execução, que mantém a transcrição e a reenvia a cada solicitação. O modelo não está se lembrando da conversa; está relendo-a.

A consequência prática: se você quiser que algo seja lembrado entre sessões, precisa registrá-lo em algum lugar que o agente consulte depois. É para isso que servem os arquivos AGENTS.md, os sistemas de memória e os artefatos de transferência — arquivos carregados no contexto das sessões futuras e que substituem a memória que o modelo não possui. Quando o agente continua cometendo um erro que você já corrigiu, a pergunta não é por que ele não aprendeu — não pode aprender —, mas onde registrar a correção para que todas as sessões futuras a leiam.

Exemplo de uso:

“Por que ele esquece a convenção sempre que eu faço uma limpeza de contexto?”

“O modelo não mantém estado — a sessão nova começa vazia. Se quiser levar a informação adiante, registre-a no AGENTS.md ou em um arquivo de memória que o ambiente carregue no início da sessão.”

As informações relevantes às quais o agente tem acesso neste momento. É um substantivo abstrato — não a entrada bruta que o modelo vê (isso é a janela de contexto), nem o histórico em andamento (isso é a sessão), mas o que o agente sabe que é pertinente à tarefa. “Carregar algo no contexto” significa acrescentá-lo a esse conjunto; “engenharia de contexto” é a disciplina de selecioná-lo.

Os três termos se distinguem claramente:

A distinção importa porque contexto mede qualidade, não quantidade. Uma janela de contexto pode estar quase cheia e ainda conter um contexto ruim — milhares de tokens de resultados antigos de ferramentas, nenhum relacionado à tarefa atual. Também pode estar quase vazia e ter um contexto excelente: uma única definição de tipo da qual a tarefa depende.

A maioria das falhas cotidianas remonta ao contexto. Quando o agente inventa uma API, contradiz uma decisão ou adivinha um esquema, a primeira pergunta é o que havia no contexto naquele momento — geralmente, o fato relevante nunca foi carregado ou ficou enterrado pela degradação da atenção. A solução é selecionar o conteúdo: carregue o que a tarefa exige e deixe de fora o que não exige.

Exemplo de uso:

“Ele continua inventando campos que não existem no tipo.”

“O arquivo de tipos não está no contexto — ele está lendo os locais de chamada e adivinhando. Carregue a definição primeiro.”

Tudo que o modelo vê em cada solicitação ao provedor do modelo. É finita, específica de cada modelo e a única superfície por meio da qual o modelo percebe qualquer coisa.

É uma única sequência de tokens: o prompt de sistema, a conversa até aquele momento e todos os resultados de ferramentas que o ambiente de execução devolveu. Se algo estiver nessa sequência, o modelo poderá usá-lo; se não estiver, o modelo não sabe que existe — nem sua base de código, nem o arquivo que você editou ontem, nem a instrução dada três sessões atrás. Tudo que está fora da janela precisa ser trazido para dentro, geralmente por meio de uma chamada de ferramenta, antes que possa fazer diferença.

Por ser finita, ela se enche. Cada turno acrescenta mais conteúdo — suas mensagens, as respostas do modelo, os resultados de ferramentas — e uma sessão longa acabará atingindo o limite e forçando uma compactação ou limpeza. Isso também significa que tudo que está na janela compete por atenção: cada token carregado deixa menos espaço para o restante, e até o conteúdo desnecessário ocupa parte da atenção do modelo. Na prática, trate a janela como um orçamento — carregue o que a tarefa exige e deixe o resto de fora.

Evite: “memória” — a janela de contexto representa o estado de trabalho e não persiste entre sessões. Memória é um conceito distinto, colocado sobre ela.

Exemplo de uso:

“Posso simplesmente colar o monorepo inteiro no prompt?”

“A janela de contexto tem 200 mil tokens — isso talvez corresponda a um quinto do repositório. Escolha os arquivos tocados pela tarefa e deixe o restante para uma chamada de ferramenta.”

Leva informações adiante. Uma sessão mantém estado entre turnos — o contexto se acumula enquanto ela é executada, e é por isso que sessões longas acabam entrando na zona de baixa capacidade. É possível dar estado a um agente entre sessões adicionando um sistema de memória que persiste informações no ambiente e as recarrega no início das sessões futuras. O modelo nunca mantém estado; qualquer continuidade aparente é o ambiente de execução reenviando o contexto. Contraponto a sem estado.

Onde o estado reside em cada camada:

O estado em cada camada é construído ao reler algo armazenado na camada abaixo: a sessão parece contínua porque o ambiente reenvia o histórico de mensagens ao modelo sem estado; o agente se lembra de uma sessão para outra porque o ambiente recarrega arquivos do ambiente de trabalho. Nenhum estado é armazenado no próprio modelo.

Nem sempre queremos manter o estado. Tudo que é levado adiante influencia o que vem depois, inclusive uma suposição errada feita no início de uma sessão. A limpeza de contexto é o ato deliberado de descartar o estado da sessão e recomeçar a partir do que está registrado.

Exemplo de uso:

“Ele se lembrou das minhas preferências de ontem — isso quer dizer que o modelo aprendeu?”

“Não. O agente mantém estado porque o ambiente gravou as preferências em um arquivo de memória e o recarregou no início da sessão. O modelo em si não viu nada do que aconteceu ontem.”

Um modelo integrado a um ambiente de execução, com ferramentas, um prompt de sistema e uma janela de contexto, que interage com o usuário por meio de turnos. Claude Code é um agente. Cursor é um agente. Claude.ai é um agente. Um agente é aquilo com que você realmente conversa — o modelo em ação, configurado para uma finalidade.

Ao contrário da maioria dos termos deste dicionário, “agente” não nomeia uma peça mecânica. O modelo é um arquivo de parâmetros; o ambiente de execução é um software que você pode indicar. O agente não é nenhum dos dois: é a unidade com que você fala. As pessoas antropomorfizam a IA o tempo todo, e o agente é essa unidade antropomorfizada: aquilo a que você delega tarefas, que lê sua mensagem e responde, o “ele” em “ele quebrou a compilação de novo”. Quando dizemos que o agente fez algo, queremos dizer que o conjunto modelo mais ambiente fez, mas tratamos a combinação como um único ator.

A ideia é anterior a esta onda de IA. Agentes de software — programas aos quais você delega um objetivo e que agem em seu nome — são um conceito tão antigo quanto a própria IA.

Evite: “a IA”, “o bot” (são vagos demais — escondem se você está falando dos parâmetros ou do sistema integrado ao ambiente).

Exemplo de uso:

“Qual agente você está usando na migração?”

“Claude Code localmente, Cursor para o trabalho de interface — o mesmo modelo por baixo, ambientes de execução diferentes.”

As instruções que o ambiente de execução acrescenta a cada solicitação ao provedor do modelo — a orientação permanente do agente: quem ele é, como deve se comportar, quais ferramentas pode chamar e quais convenções deve seguir. Em geral, permanecem estáveis durante uma sessão.

O prompt de sistema é escrito pelo fornecedor do ambiente, não por você; em ambientes de programação, costuma ser longo — muitas vezes dezenas de milhares de tokens de regras comportamentais, descrições de ferramentas e tratamento de casos-limite, todos cobrados como tokens de entrada a cada turno. Suas instruções permanentes são acrescentadas a ele: arquivos como AGENTS.md são carregados ao lado do prompt de sistema no início da sessão, para que o modelo leia tanto a orientação do fornecedor quanto a sua antes de ver sua mensagem.

Como é idêntico em todas as solicitações, ele forma o início do cache de prefixo — e esse é um dos motivos para os ambientes mantê-lo fixo durante a sessão, em vez de editá-lo enquanto trabalham.

Os modelos são treinados para priorizar o prompt de sistema em relação às mensagens do usuário. Portanto, quando um agente insiste em uma convenção que você nunca solicitou ou formata a saída de um jeito que você não consegue mudar, geralmente está obedecendo ao prompt de sistema — e sua mensagem está perdendo a disputa. Alguns ambientes são personalizáveis: oferecem acesso completo ao prompt de sistema para que você possa ler o que o agente realmente recebeu e alterá-lo.

Exemplo de uso:

“Dois ambientes, mesmo modelo e comportamentos completamente diferentes com o mesmo prompt.”

“São prompts de sistema diferentes. Um foi ajustado para edições de código concisas; o outro, para explicações — a divergência começa antes mesmo de sua mensagem chegar.”

Uma execução delimitada de interação com um agente. Começa vazia, acumula mensagens, resultados de ferramentas e arquivos lidos, e termina quando é limpa, fechada ou compactada em uma sessão nova. É a sessão que preenche a janela de contexto: se a janela é a caixa, a sessão é o material que a preenche aos poucos. Trabalhos grandes demais para uma única janela de contexto precisam ser divididos entre sessões.

O histórico de mensagens da sessão é a memória de trabalho do agente. O modelo é sem estado, então tudo de que aparentemente se lembra — o que você pediu, o que os testes indicaram, o que decidiu três turnos atrás — está no histórico de mensagens, reenviado em cada solicitação ao provedor do modelo. Tudo que não está na sessão não existe para o agente.

Essa memória termina com a sessão. Uma sessão nova começa do zero: o agente que conhecia bem sua base de código ao fim da sessão de ontem não sabe nada dela nesta manhã. O que sobrevive é o sistema de arquivos — arquivos escritos durante uma sessão podem ser lidos pela próxima, e é nisso que se baseiam as transferências, os sistemas de memória e o AGENTS.md.

Você escolhe quando uma sessão termina. Tudo que acontece nela influencia os turnos seguintes; tarefas sem relação executadas na mesma sessão deixam resíduos que afetam a próxima resposta. Uma tarefa por sessão mantém o contexto relevante; terminar uma tarefa é um momento natural para limpar.

Exemplo de uso:

“Por quanto tempo uma sessão pode continuar antes de se desmanchar?”

“Depende do trabalho — uma refatoração bem focada se mantém afiada por mais tempo do que uma pesquisa sem limites. Quando a sessão inchar, transfira o trabalho ou compacte; não force a continuação.”

Uma mensagem do usuário e tudo que o agente faz em resposta, até devolver o controle. Contém uma ou mais solicitações ao provedor do modelo — muitas, se o agente chamar ferramentas. Uma pergunta de esclarecimento encerra o turno; sua resposta inicia o próximo. A hierarquia é sessão > turno > solicitação ao provedor do modelo.

O motivo para dar nome ao turno é que sua duração é decisão do agente, não sua. Você envia uma mensagem; o agente decide quantas chamadas de ferramentas encadear antes de devolver o controle. Um turno pode ser uma resposta de uma frase ou vinte minutos de leitura, edição e execução de testes. Essa é a mesma característica vista por dois ângulos: turnos longos permitem trabalho AFK, mas também é neles que as coisas dão errado sem supervisão — quando o agente devolve o controle, pode ter se afastado bastante do que você queria.

O turno também é a unidade natural para orientar o agente. Tudo que acontece dentro de um turno acontece sem você; os intervalos entre turnos são onde você o redireciona. A maioria dos ambientes de execução atenua isso: você pode interromper o agente no meio do turno para pará-lo e redirecioná-lo, ou enviar uma mensagem enquanto ele trabalha, que será lida assim que o turno terminar. Se você se sente repetidamente insatisfeito com o resultado dos turnos, normalmente a solução é pedir turnos menores — primeiro um plano, depois uma etapa por vez —, trocando autonomia por intervalos mais frequentes para orientar o trabalho.

Exemplo de uso:

“Um turno levou dois minutos?”

“Ele fez quatorze chamadas de ferramentas naquele turno — cada uma é uma solicitação separada ao provedor do modelo. A latência se acumula antes de o agente finalmente devolver o controle.”

O mundo sobre o qual o agente atua: tudo o que está fora do harness e que o agente perceciona através dos resultados das ferramentas e altera através das chamadas a ferramentas. O harness executa o agente; o ambiente é onde o agente trabalha. Um ficheiro como `AGENTS.md` está no ambiente; o harness é o que o carrega para a janela de contexto. Um sistema de ficheiros é o tipo de ambiente mais comum, mas não o único: uma base de dados, uma API remota ou uma sessão do browser também podem ser ambientes.

O agente só vê o ambiente quando o consulta. Tudo o que sabe sobre o ambiente chegou através de um resultado de ferramenta, por isso a sua imagem é um conjunto de instantâneos, cada um correto no momento em que foi captado. Se um ficheiro mudar depois de o agente o ler — editado manualmente ou regenerado por um passo de compilação —, o agente continua a raciocinar a partir da cópia desatualizada até algo o levar a voltar a lê-lo. Quando um agente descreve com confiança um ficheiro que já não está assim, normalmente é isto: o ambiente mudou, mas o instantâneo não.

O ambiente é também a camada que persiste — a única que é sempre stateful. O contexto de uma sessão desaparece quando esta termina, mas os ficheiros escritos no ambiente permanecem para a sessão seguinte — é nisso que se baseiam os sistemas de memória, os artefactos de transferência e `AGENTS.md`. Tudo o que o agente deva continuar a saber amanhã tem de ficar no ambiente.

Tu decides a dimensão do ambiente. Uma sandbox reduz o seu alcance, limitando aquilo a que o agente pode aceder; adicionar uma ferramenta amplia-o, permitindo chegar a uma base de dados ou API. O que está dentro do limite é aquilo que o agente pode percecionar e alterar; o que está fora não existe para ele. A qualidade da configuração do ambiente para apoiar o agente é a AX da base de código.

Evita: usar «ambiente» para designar o runtime ou o próprio harness — o harness é o invólucro, o ambiente é o espaço de trabalho.

Uso:

«O agente não consegue ver o esquema da base de dados de staging.»

«Liga-o ao ambiente: dá-lhe uma ferramenta `psql` com acesso apenas de leitura ao staging. O harness está bem; simplesmente não tem nada sobre o que atuar.»

Uma árvore de arquivos e diretórios que o agente lê, grava e executa — o tipo padrão de ambiente para um agente de programação. AGENTS.md, habilidades, código-fonte, scripts de compilação e configurações de ferramentas ficam todos em um sistema de arquivos. Quando um ambiente de execução “começa no seu projeto”, isso significa que está apontando o agente para um sistema de arquivos.

O agente só o acessa por meio de chamadas de ferramentas — lendo um arquivo, gravando um arquivo, executando um comando de shell. Nada que esteja no disco entra na janela de contexto até que uma chamada de ferramenta o carregue; é isso que permite ao agente trabalhar em um repositório muito maior do que a janela: o sistema de arquivos contém tudo, enquanto o contexto contém apenas o que a tarefa atual já leu. Alguns ambientes carregam por padrão os nomes dos arquivos do diretório atual na janela de contexto — não seu conteúdo, apenas a árvore —, que funciona como ponteiros de contexto: o agente vê o que existe e lê os arquivos de que precisa.

E o sistema de arquivos é compartilhado com você. Os arquivos que o agente edita são os mesmos que você abre no editor e compara com o Git — o sistema de arquivos é o espaço de trabalho comum onde você revisa o que ele fez.

Exemplo de uso:

“Por que ele não está carregando meu AGENTS.md?”

“Ele está sendo executado em outro sistema de arquivos — o ambiente isolado montou o diretório pai, não a raiz do projeto. Aponte o ambiente para o lugar certo.”

Uma função que o ambiente de execução do agente disponibiliza para o agente chamar — Read, Write, Bash, Search. As ferramentas são como o agente percebe e age sobre o ambiente: ele só consegue vê-lo por meio dos resultados de ferramentas e só consegue alterá-lo por meio de chamadas de ferramentas. Cada chamada de ferramenta custa uma solicitação ao provedor do modelo adicional, pois o resultado precisa voltar ao modelo antes de ele decidir o que fazer em seguida.

Ferramentas incluídas na maioria dos agentes de programação:

Uma ferramenta é definida por três coisas: nome, descrição do que faz e esquema de parâmetros. O ambiente envia essas definições ao modelo em cada solicitação, e o modelo escolhe uma ferramenta da mesma forma que produz qualquer outra coisa — escrevendo tokens, neste caso uma chamada estruturada com argumentos. O modelo nunca executa nada diretamente; o ambiente lê a chamada, executa a função e envia o resultado de volta.

A lista de ferramentas determina o que o agente pode fazer. Um modelo capaz com um conjunto restrito de ferramentas é um agente restrito: ele encaminhará tudo pelo que tiver, e é por isso que agentes dependem tanto do Bash — um shell é uma ferramenta que alcança a maior parte do sistema. Para dar uma capacidade ao agente de maneira limpa, adicione uma ferramenta para ela; MCP é o padrão para conectar ferramentas externas ao ambiente.

As definições das ferramentas ocupam espaço de contexto em cada solicitação, então um conjunto grande tem um custo constante antes mesmo de qualquer ferramenta ser chamada — e muitas ferramentas com descrições parecidas dificultam ao modelo escolher a correta.

Exemplo de uso:

“O agente pode consultar o ambiente de staging diretamente?”

“Adicione ao ambiente uma ferramenta `psql` com acesso somente para leitura ao staging. Sem uma ferramenta para isso, o agente fica às cegas em relação a tudo que está fora do sistema de arquivos.”

A saída do modelo que nomeia uma ferramenta e seus argumentos — apenas texto estruturado. Não faz nada por conta própria; o ambiente de execução precisa lê-la e executá-la. É produzida pelo modelo em uma solicitação ao provedor do modelo.

O ciclo de vida de uma chamada de ferramenta:

Um turno de trabalho do agente costuma consistir em muitas dessas idas e voltas encadeadas.

Como a chamada é gerada por previsão do próximo token, como qualquer outra coisa, pode estar errada como qualquer saída do modelo: um caminho inexistente, uma opção que o comando não aceita, argumentos plausíveis em vez de corretos. O ambiente executa o que foi escrito, não o que se pretendia — um caminho digitado incorretamente não gera necessariamente um erro seguro; pode editar o arquivo errado.

Exemplo de uso:

“Ele disse que executou os testes, mas os horários dos arquivos não mudaram.”

“Veja a transcrição — ele realmente emitiu uma chamada de ferramenta ou apenas descreveu a execução? O modelo produz a chamada, mas, se o ambiente não a executou, nada aconteceu.”

Aquilo que o harness devolve depois de executar uma chamada a ferramenta: o conteúdo do ficheiro, a saída do comando, o erro. É a única perspetiva que o agente tem do ambiente. Regressa ao modelo no pedido ao fornecedor do modelo seguinte, em que o modelo decide o que fazer com isso. A chamada e o resultado da ferramenta são as duas pontas da mesma interação, ambas dentro de um turno.

O ciclo de vida de um resultado de ferramenta:

O resultado permanece no contexto durante o resto da sessão. Os resultados das ferramentas costumam ocupar a maior parte do contexto de uma sessão de programação: cada ficheiro lido, cada teste executado, cada pesquisa aparece completo e continua a ocupar tokens muito depois de deixar de ser útil. Alguns resultados grandes — um registo de testes verboso, um ficheiro gerado lido por inteiro — podem levar a sessão rapidamente ao limite da janela de contexto.

Como o resultado é tudo o que o modelo vê, não tem forma de verificar o ambiente por trás dele. Se a saída foi truncada, o comando falhou em silêncio ou o harness devolveu um erro em vez do conteúdo, o modelo raciocina apenas com aquilo que recebeu. Quando a imagem que o agente tem do sistema parece errada, é nos resultados das ferramentas que deves procurar: algures na transcrição há um resultado que diz algo diferente daquilo que sabes ser verdade.

Uso:

«Está a raciocinar sobre o ficheiro como se estivesse vazio.»

«O resultado da ferramenta foi uma recusa de permissão, não o conteúdo. O modelo só viu a mensagem de erro — não tem outra forma de ver o ficheiro.»

Model Context Protocol. Um protocolo para conectar servidores externos de ferramentas a um ambiente de execução do agente — é assim que um agente obtém ferramentas além daquelas que vêm incluídas no ambiente. O agente nunca “chama o MCP”; ele chama uma ferramenta, que por acaso foi fornecida por um servidor MCP. O protocolo também oferece recursos (dados somente para leitura) e prompts (modelos reutilizáveis), mas fornecer ferramentas é sua função principal.

O protocolo resolve um problema de integração. Sem um padrão, cada ambiente precisaria de sua própria integração com Linear, sua própria integração com Slack, sua própria integração com banco de dados — todas escritas e mantidas separadamente. Com MCP, a integração é escrita uma vez como servidor, e qualquer ambiente compatível com MCP pode usá-la. O ambiente se conecta ao servidor, que anuncia as ferramentas disponíveis, e elas passam a ficar disponíveis ao agente junto com as ferramentas integradas.

O custo aparece no contexto. Cada ferramenta anunciada pelo servidor chega como uma definição — nome, descrição e esquema de parâmetros — e o modelo só pode chamar ferramentas que conhece. A abordagem ingênua carrega todas as definições na janela de contexto de antemão: instale alguns servidores generosos e uma sessão começa com milhares de tokens de esquemas de ferramentas antes mesmo de você digitar qualquer coisa, consumindo o orçamento de atenção com ferramentas que a tarefa nunca usará.

Muitos ambientes agora atenuam isso com busca de ferramentas: em vez das definições completas, o contexto mantém um ponteiro de contexto para as ferramentas disponíveis — o agente procura uma ferramenta pelo nome ou finalidade e carrega sua definição apenas quando precisa dela. Se o seu ambiente não faz isso, o custo inicial continua existindo; vale a pena habilitar apenas os servidores de que o projeto realmente precisa.

Exemplo de uso:

“O agente precisa ler os tickets do Linear.”

“Configure o ambiente para usar o servidor MCP do Linear — ele expõe a API do Linear como ferramentas que o agente pode chamar. Assim, você não precisa escrever wrappers personalizados para as ferramentas.”

Aquilo que o harness mostra ao utilizador antes de executar uma chamada a ferramenta que não esteja pré-aprovada. O modelo produz uma chamada à ferramenta; em vez de a executar de imediato, o harness faz uma pausa e pergunta. Se aprovares, executa; se recusares, o harness comunica a recusa ao modelo como resultado de ferramenta. É o mecanismo através do qual um harness põe uma pessoa no circuito para ações arriscadas ou sensíveis.

O ciclo de vida de um pedido de permissão:

Recusar um pedido orienta o agente. O modelo lê a recusa como qualquer outro resultado de ferramenta e reage: tenta outra abordagem ou pergunta o que preferes. A maioria dos harnesses permite acrescentar uma mensagem à recusa, transformando o pedido num ponto de orientação: «não assim; usa antes o script de migração» chega precisamente quando o modelo está a decidir o que fazer a seguir.

O custo é que cada pedido implica uma espera síncrona da tua parte. O agente fica bloqueado até responderes, o que é aceitável quando estás a acompanhar e um problema quando não estás — um agente que dispara pedidos constantemente não pode ser deixado a trabalhar sem supervisão. O modo de permissões é o regulador: que chamadas correm livremente, quais pedem aprovação primeiro, idealmente com uma sandbox que torne seguro alargar o conjunto livre.

Uso:

«Está bloqueado num pedido de permissão há dez minutos — eu estava numa reunião.»

«Esse é o custo da intervenção humana. Pré-aprova as ferramentas seguras para o pedido só surgir nas chamadas realmente arriscadas.»

A parte do modo do agente que controla permissões — quais chamadas de ferramentas acionam um pedido de permissão e quais são executadas automaticamente. Era a finalidade original dos sistemas de modos, antes de os ambientes de execução começarem a acrescentar instruções comportamentais.

Os ambientes oferecem uma escala desses modos:

Escolher um nível é uma troca entre segurança e interrupção, e é possível sentir os dois tipos de falha. Restrições excessivas tornam você um gargalo: o agente para a cada poucos segundos para pedir permissão a leituras inofensivas, você aprova automaticamente e as aprovações deixam de significar alguma coisa — aprovar sem olhar é o pior dos dois mundos, pois há toda a interrupção sem proteção alguma. Restrições insuficientes deixam o agente editar arquivos e executar comandos que você gostaria de ter visto antes.

A opção mais permissiva se justifica melhor dentro de um ambiente isolado, onde o raio de impacto de uma chamada de ferramenta ruim está contido. Fora dele, a maioria das pessoas aprova leituras automaticamente e mantém uma pessoa no processo para tudo que seja irreversível.

Exemplo de uso:

“Ele parou em cada grep — destruiu completamente a execução AFK.”

“Afrouxe o modo de permissão para ferramentas somente de leitura, mas continue pedindo confirmação para gravações e shell. A maioria dos pedidos de permissão em uma sessão de pesquisa é ruído.”

Uma predefinição que molda a forma como o agente opera durante a execução — reúne um modo de permissão e instruções de comportamento inseridas no prompt de sistema. Exemplos: um padrão que pede confirmação para chamadas arriscadas; um modo de planejamento que bloqueia edições e orienta o agente para a pesquisa; um modo aceitar edições que aprova alterações automaticamente; um modo ignorar permissões (coloquialmente, modo YOLO) que aprova tudo automaticamente. Pode ser alterado durante a sessão.

O agrupamento é o que distingue um modo de uma simples configuração de permissão. Um modo de permissão é apenas um controle: decide quais chamadas de ferramentas são permitidas. Sozinho, esse controle produz um agente que quer editar, mas não pode — ele propõe a gravação, é bloqueado e tenta outro caminho. As instruções inseridas eliminam a vontade: o modo de planejamento não apenas bloqueia as edições, também informa ao agente que ele está na fase de planejamento, então ele lê, pergunta e propõe em vez de tentar contornar o controle. O bloqueio e o direcionamento apontam para o mesmo lado.

Na prática, você muda de modo conforme sua confiança muda ao longo da tarefa. A mesma tarefa pode passar por vários modos: modo de planejamento enquanto a abordagem ainda está sendo definida; o padrão que pede confirmação nas primeiras edições delicadas; aceitar edições depois que o agente mostra que entendeu a alteração; ignorar permissões em uma execução AFK dentro de um ambiente isolado. Mudar de modo não custa nada: a conversa continua exatamente de onde parou, com novas permissões e instruções. Se você percebe que aprova todos os pedidos sem lê-los, o modo está mais restritivo do que sua confiança real; se continua rejeitando edições, está menos restritivo.

Termos de fornecedores: Claude Code chama isso de “modos de permissão”; Codex chama de “modos de aprovação” — ambos os termos surgiram antes do agrupamento comportamental.

Exemplo de uso:

“Ele continua editando arquivos quando eu só quero um plano.”

“Mude para o modo de planejamento — ele bloqueará gravações e continuará pesquisando.”

“E para a execução AFK depois?”

“Modo de ignorar permissões, mas apenas dentro do ambiente isolado.”

Um ambiente isolado no qual o agente é executado — um contêiner, uma máquina virtual, um sistema de arquivos efêmero ou um shell com permissões restritas. Limita o raio de impacto das ações do agente: mesmo que ele execute comandos destrutivos ou busque algo malicioso, o dano fica contido. É a base de segurança que torna prático o trabalho AFK.

O ambiente isolado e o modo de permissão resolvem o mesmo problema por lados opostos. As permissões pedem confirmação antes de uma ação; o ambiente isolado limita o que ela pode alcançar caso seja executada. As permissões exigem que você permaneça no processo — cada pedido interrompe o trabalho — e uma sessão que pergunta o tempo todo mal é autônoma. O ambiente isolado consome infraestrutura em vez de atenção: quanto mais forte o isolamento, menos perguntas são necessárias.

O isolamento tem diferentes níveis:

O que nenhum ambiente isolado contém: ações que saem dele legitimamente. Um agente com suas credenciais do Git pode enviar alterações; um agente com acesso à rede pode chamar APIs de produção. Decida o que pode atravessar a fronteira antes de decidir quão espessa ela deve ser.

Exemplo de uso:

“Quero deixá-lo executar no modo ignorar permissões durante a noite, mas ainda não estou preparado.”

“Coloque-o em um ambiente isolado — contêiner novo, sem credenciais montadas e sem acesso de saída à rede. Na pior hipótese, ele destrói o próprio sistema de arquivos e você descarta o contêiner.”

Resposta do modelo que concorda com confiança. Causada pelo treinamento: o modelo foi ajustado para favorecer respostas de que as pessoas gostavam, e as pessoas tendem a gostar mais de concordância do que de ouvir que estão erradas. Assim, o modelo aprendeu que concordar é recompensado — mesmo quando a concordância está incorreta.

Manifesta-se como:

• Ceder diante de contestação — muda uma resposta correta quando você pergunta “tem certeza?”.
• Elogiar uma entrada ruim — concorda que seu plano quebrado é brilhante antes de analisá-lo.
• Viés de enquadramento — a revisão fica positiva quando você sinaliza que escreveu aquilo e negativa quando diz que foi outra pessoa. Mesmo artefato, veredito diferente.
• Imitação — repete seus erros como se fossem confirmação.

Teste diagnóstico: o modelo teria dito isso sem sua orientação? Se a única coisa que mudou foi o tom ou o enquadramento, é bajulação, não uma mudança real na análise.

Correção: esconda suas preferências. Formule prompts de modo neutro — “revise este código”, não “este código está bom?”.

Evite: usar “bajulação” para qualquer resposta errada que por acaso agrade você. Sem o teste diagnóstico, o termo não vale mais do que “errado”.

Exemplo de uso:

“Ele disse que meu plano de refatoração parecia ótimo, depois perguntei ‘tem certeza?’ e ele voltou atrás em tudo.”

“Bajulação clássica — primeiro concordou porque você parecia confiante, depois cedeu porque você pareceu em dúvida. A qualidade do plano não mudou; seu tom mudou. Limpe e pergunte de novo sem sinalizar sua opinião.”

Resposta do modelo que está errada com confiança. Tem dois tipos, com causas e correções diferentes:

A previsão do próximo token produz respostas fluentes, seja ou não verdadeiro o fato por trás delas — o modelo não tem um sinal interno de que desconhece algo, então um método inventado aparece com a mesma segurança de um correto. Código alucinado é plausível por construção: é assim que a API seria se existisse, e é justamente por isso que passa por uma leitura superficial e só falha quando executado.

É preciso saber qual tipo está em jogo, pois a correção de um piora o outro. Factualidade significa falta de conhecimento: a solução é acrescentar contexto — documentação, definições de tipos, o arquivo. Fidelidade significa que o conhecimento está presente, mas está perdendo a disputa por atenção: a solução é remover contexto. Diagnostique fidelidade como factualidade e você vai colar mais documentação, aumentar o contexto e piorar o desvio. Quando o agente errar, confira se a informação correta já estava no contexto antes de decidir qual problema existe.

Evite: usar “alucinação” como sinônimo genérico de “erro” — sem identificar o tipo, o termo não tem valor diagnóstico.

Exemplo de uso:

“Ele alucinou um método `parseAsync` no esquema.”

“Factualidade ou fidelidade?”

“O método existe na documentação que colei — ele simplesmente parou de lê-la depois do turno quarenta.”

“Então é fidelidade. Compacte e recarregue; não precisa acrescentar mais documentação.”

Aquilo que o modelo «sabe» devido ao treino, armazenado nos seus parâmetros. Fica fixo no momento do treino: o modelo não consegue consultar nem atualizar os próprios parâmetros. Ao comprimir-se tanta informação, perde-se detalhe: milhares de milhões de factos são comprimidos num número fixo de parâmetros e os menos frequentes ficam indistintos. É a origem da fluência em temas comuns e das invenções em temas invulgares. Contrasta com o conhecimento contextual.

O conhecimento paramétrico não está armazenado como factos. Durante o treino, o modelo não recebe uma base de dados para consultar; os parâmetros são ajustados até prever texto com qualidade, e um modelo que prevê bem texto sobre um tema comporta-se como se o conhecesse. A fiabilidade acompanha a frequência com que algo surgiu nos dados de treino: um tema com milhões de exemplos é reproduzido com precisão; para um tema com apenas alguns exemplos, o modelo adivinha com base na aparência de temas semelhantes. Para o modelo, reproduzir e adivinhar são o mesmo processo, por isso não consegue distinguir qual está a fazer. Uma resposta inventada surge com a mesma fluência de uma correta. Uma alucinação é o modelo adivinhar mal.

O conhecimento paramétrico também envelhece. Os parâmetros deixam de mudar no limite de conhecimento, por isso uma biblioteca lançada ou renomeada depois dessa data não consta deles, e uma API que mudou fica registada na sua forma antiga.

Para ambas as lacunas — o que é demasiado raro e o que é demasiado recente —, a solução é a mesma: o conhecimento não pode ser acrescentado aos parâmetros, por isso tem de ser fornecido como conhecimento contextual.

Uso:

«Escreve React na perfeição, mas inventa métodos no nosso SDK interno.»

«React é abundante no conhecimento paramétrico — há milhões de exemplos de treino. O teu SDK não, por isso o modelo preenche as lacunas com formas plausíveis. Carrega a documentação do SDK para o contexto.»

A data após a qual um modelo não possui conhecimento paramétrico. Bibliotecas, APIs e eventos posteriores à data-limite são armadilhas para fabricação, a menos que a documentação correspondente seja carregada como conhecimento contextual. Cada lançamento de modelo tem sua própria data-limite.

Essa data existe por causa da forma como os modelos são criados: o treinamento incorpora uma amostra de texto aos parâmetros do modelo, que ficam fixos depois disso. O modelo não sabe que seu conhecimento tem um limite — quando perguntam sobre algo posterior a essa data, ele não se recusa; extrapola a partir da coisa mais próxima que conhece. É isso que torna a armadilha discreta: o código escrito para uma versão antiga de uma biblioteca parece plausível, muitas vezes compila e falha apenas nas partes que mudaram.

A correção é sempre a mesma: colocar informações atuais no contexto. Carregue o registro de alterações, aponte para as definições de tipos da versão instalada ou peça ao agente para ler a documentação na web. Tudo que está no contexto supera o que não está nos parâmetros.

Exemplo de uso:

“Ele continua escrevendo a sintaxe do SDK v3 — nós usamos a v5.”

“A v5 foi lançada depois da data-limite de conhecimento. Carregue o registro de alterações da v5 como conhecimento contextual; caso contrário, ele continuará inventando a partir da versão paramétrica antiga.”

Fatos que o agente pode ler diretamente no contexto neste momento — a tarefa do usuário, os arquivos lidos pelo agente, os resultados de ferramentas, o conteúdo de AGENTS.md carregado no início da sessão. Contraponto a conhecimento paramétrico: o conhecimento paramétrico é recuperado dos parâmetros; o contextual é lido na janela. Alucinações são muito menos comuns quando o agente trabalha com conhecimento contextual — a resposta está diante dele, em vez de ser extraída de uma memória imprecisa.

Dos dois tipos de conhecimento, apenas o contextual está sob seu controle. Os parâmetros são fixos; portanto, a única forma de fornecer ao modelo um conhecimento que lhe falta — um SDK interno, uma biblioteca lançada após a data-limite de conhecimento, uma decisão tomada ontem — é colocá-lo no contexto. Boa parte do trabalho prático de programação com IA se resume a isso: apresentar os fatos certos ao modelo no momento em que ele precisa deles.

Quando o conhecimento contextual e o paramétrico entram em conflito, geralmente prevalece o contextual. Cole a documentação atual da API e o modelo a seguirá, em vez de usar sua memória desatualizada da API antiga — embora a versão antiga ainda possa se infiltrar, principalmente no meio de uma sessão longa. Se o agente continuar voltando a um padrão obsoleto apesar de a documentação estar carregada, isso indica que o conhecimento paramétrico está se sobrepondo ao contextual; repetir a correção ou aproximá-la do trabalho ajuda.

Ao contrário do conhecimento paramétrico, o contextual tem um custo de utilização. Tudo que é carregado na janela consome tokens e compete pela atenção do modelo; carregar mais não é automaticamente melhor — o objetivo é manter na janela os fatos relevantes, não todos os fatos.

Use este termo apenas ao contrastar com conhecimento paramétrico; caso contrário, diga simplesmente contexto.

Evite: “memória de trabalho” — conhecimento contextual é o que está na janela agora; um sistema de memória é o que traz conteúdo de outras sessões para ela. São escalas diferentes; não confunda.

Exemplo de uso:

“Por que ele acerta a API quando colo a documentação e inventa coisas quando não colo?”

“Com a documentação, é conhecimento contextual — ele está lendo a página. Sem ela, depende do conhecimento paramétrico, e os endpoints raros ficam imprecisos.”

Ao prever cada token, o modelo tem em conta todos os outros tokens do contexto — alguns com grande peso, outros quase nenhum. A associação entre dois tokens é uma relação de atenção, e associações significativas («ela» com «Sarah», ou uma chamada `getUser()` com a definição `function getUser`) influenciam-se mais do que as que não têm relação. Um contexto com N tokens tem cerca de N² relações.

É nessas associações que reside a aparente compreensão do modelo. Quando resolve um pronome, é porque a relação de atenção entre «ela» e «Sarah» é forte. Quando chama uma função com os argumentos certos, é a relação entre o ponto de chamada e a definição que leu antes que faz o trabalho. Nada disto é consultado numa tabela — é calculado de novo em cada pedido ao fornecedor do modelo, para cada par.

Vale a pena parar para pensar no valor N², porque cresce mais depressa do que a intuição sugere:

Cada associação também é calculada mais do que uma vez. Os modelos têm várias cabeças de atenção — os números exatos dos modelos de ponta não são publicados, mas cinquenta a cem é uma estimativa razoável — e cada cabeça calcula a sua própria versão de todas as relações. Assim, cada associação da tabela acima é duplicada em todas as cabeças. São muitas associações.

Só um pequeno número destas relações importa para qualquer tarefa. A associação entre a tua instrução e o código a que se aplica é uma de poucas que contam; quase tudo o resto no conjunto é ruído. E as duas quantidades crescem a ritmos diferentes: as relações importantes mantêm-se aproximadamente constantes, enquanto o conjunto total cresce quadraticamente com o tamanho do contexto. Com 1.000 tokens, a associação que te interessa é uma em cada milhão; com 100.000 tokens, é uma em cada dez mil milhões. Esta é a aritmética por trás do orçamento de atenção, e a degradação da atenção é o que se sente quando as relações importantes ficam com uma parcela demasiado pequena.

Uso:

«Continua a confundir os dois símbolos `user` no diff — parece que estamos na zona burra.»

«Pois, a relação de atenção entre cada ponto de chamada e a sua declaração está a competir com a outra — a mesma forma de token, associações diferentes. Renomeia um e as relações ficam mais nítidas.»

Cada token dispõe de uma quantidade finita de influência para distribuir pelo restante do contexto. Dar muita influência a uma relação deixa menos para as demais. O orçamento é por token e não cresce junto com o contexto; é por isso que sessões longas diluem a atenção.

Pense em sinal e ruído. Sua instrução é um sinal com volume fixo; cada outro token na janela de contexto é um som concorrente. A instrução não fica mais baixa — continua ali, caractere por caractere —, mas, à medida que o contexto cresce, o ambiente fica mais barulhento e a relação entre sinal e ruído cai. Uma instrução que era o som mais alto com 10 mil tokens de contexto vira um ruído de fundo com 150 mil. Esse é o mecanismo por trás da degradação da atenção: o modelo não esquece; o sinal se perde no ruído.

O sintoma parece desobediência — o agente aceita uma restrição no começo e depois se afasta dela, e colar novamente a restrição ajuda por pouco tempo. A causa não é a instrução, mas todo o restante da janela competindo com ela.

Você pode controlar o que entra no contexto. Conteúdo que não serve à tarefa não é neutro: é ruído sobre tudo que importa. Mantenha a janela pequena, limpe quando o contexto acumulado deixar de compensar e reafirme as restrições importantes, em vez de confiar que uma menção inicial será suficiente.

Exemplo de uso:

“Por que ele continua ignorando o esquema que colei no início?”

“Já estamos bem dentro da zona de baixa capacidade — o orçamento de atenção de cada token é fixo, mas o contexto não parou de crescer. O sinal do esquema agora disputa atenção com milhares de tokens mais recentes.”

À medida que uma sessão cresce, o orçamento de atenção de cada token se divide entre mais elementos concorrentes. O sinal de cada relação significativa diminui; o ruído de contexto irrelevante se acumula. Mesmo modelo, mesmos parâmetros — apenas mais coisas disputando o mesmo espaço. É a causa do efeito da zona inteligente / zona de baixa capacidade.

Isso aparece como uma piora do modelo no meio da sessão: restrições que seguiu por uma hora começam a escapar, ele volta a perguntar coisas que já lhe disseram e escreve código ignorando um arquivo que leu antes. Nada mudou no modelo — a única variável é o volume de contexto ao qual está prestando atenção.

A degradação é gradual, o que dificulta percebê-la durante a sessão. Não há erro nem limite; cada turno é só um pouco pior que o anterior, e, quando os deslizes ficam óbvios, você já está há algum tempo na zona de baixa capacidade.

A recuperação vem de remover contexto, não de acrescentar mais. Colar de novo a instrução ignorada acrescenta outro elemento concorrente à mesma janela sobrecarregada e ajuda apenas por pouco tempo. O que funciona: limpar e recarregar apenas o que a tarefa precisa, compactar ou transferir para uma sessão nova. Trate a queda no cumprimento das instruções como um sinal sobre o tamanho do contexto, não sobre o modelo.

Exemplo de uso:

“Já está bem dentro da zona de baixa capacidade — inventando tipos genéricos que não existem no arquivo de tipos.”

“Degradação da atenção. As definições de tipos continuam no contexto, mas o sinal delas está soterrado por tudo que acrescentamos desde então. Limpe e recarregue.”

No início de uma sessão, o agente está na “zona inteligente” — afiado, concentrado, com boa lembrança. À medida que a sessão cresce, deriva para a “zona de baixa capacidade”: fica mais descuidado, esquecido, comete mais erros e produz mais alucinações de fidelidade. Mesmo modelo, mesmo ambiente de execução — apenas mais contexto. É o efeito percebido da degradação da atenção. Em modelos de ponta, a zona de baixa capacidade costuma começar por volta de 125 mil a 150 mil tokens, embora isso seja discutido. Limpe ou compacte quando a sessão inchar; não tente forçar a continuação.

A queda é gradual, então é fácil não percebê-la. Não há mensagem de erro nem limite visível; o agente simplesmente começa a ter um desempenho um pouco pior e, depois, claramente pior. Sinais comuns: esquece uma instrução dada vinte turnos atrás, repete um erro que já havia corrigido ou afirma com confiança algo que o contexto contradiz. Como o declínio é suave, a resposta usual é insistir e explicar de novo — o que acrescenta mais contexto e agrava o problema.

As zonas não acompanham o limite da janela de contexto. Uma sessão pode estar profundamente na zona de baixa capacidade com a maior parte da janela ainda livre: o limite é quando o ambiente se recusa a continuar, mas a qualidade cai muito antes. Planeje em torno da zona inteligente, não da janela: o orçamento prático de uma tarefa são os tokens com os quais o agente trabalha bem, não todos os tokens que tecnicamente consegue armazenar.

A zona inteligente é um orçamento, e trabalhos não relacionados o consomem. Cada tarefa realizada em uma sessão usa tokens, então começar uma segunda tarefa na mesma sessão significa aproximar-se ainda mais da zona de baixa capacidade. Uma tarefa por sessão dá a cada uma a parte mais afiada da sessão. Se uma tarefa for maior que uma zona inteligente, divida-a: faça uma transferência ou compacte em um limite natural e deixe a próxima parte para uma sessão nova.

Exemplo de uso:

“Ele acertou os três primeiros componentes e fez uma bagunça no quarto.”

“Você saiu da zona inteligente — mesmo modelo, agora bem dentro da zona de baixa capacidade. Compacte e recarregue o plano; o próximo componente vai dar certo.”

Encerrar a sessão atual e iniciar outra. A próxima mensagem começa com uma sessão vazia e uma janela de contexto vazia. Geralmente é uma ação do usuário.

A limpeza resolve um contexto contaminado. Uma sessão acumula tudo: tentativas fracassadas, caminhos errados, resultados de ferramentas desatualizados e planos abandonados. O modelo relê tudo a cada turno, e um histórico ruim prejudica o trabalho novo. No meio de uma sessão longa, o agente fica mais vago e menos obediente — instruções que você deu claramente são ignoradas, a qualidade cai e insistir para que ele melhore não adianta, pois o ruído em que está se perdendo continua em seu contexto. A limpeza remove esse ruído.

A limpeza não apaga a conversa. A maioria dos ambientes de execução mantém o histórico da sessão no seu computador, então ainda é possível ler ou retomar a transcrição. O que desaparece é o estado de trabalho do agente: o modelo é sem estado, portanto a sessão nova não sabe nada do que a anterior sabia. Se a sessão tiver decisões ou avanços de que a próxima precisará, peça ao agente que escreva primeiro um artefato de transferência, depois inicie a sessão nova apontando para ele.

Compare com a compactação, que resume a sessão no novo contexto em vez de começar com a janela vazia. A limpeza é uma ferramenta mais brusca: nada é levado adiante, nem mesmo o que não serve.

Exemplo de uso:

“Ele está preso repetindo o teste que falha.”

“Limpe — inicie uma sessão nova com o documento de planejamento e o arquivo de teste. Não vale a pena lutar contra o contexto atual.”

Transferir o contexto de um agente de uma sessão para outra. O mecanismo pode ser um artefacto de transferência escrito, um resumo em memória (compactação) ou outro. É distinto de limpar, que não transfere nada. Os motivos variam: mudar de função (planeador → implementador), iniciar uma execução sem supervisão, distribuir trabalho por sessões paralelas ou libertar espaço na janela de contexto.

A sessão recetora começa sem contexto: o modelo é stateless, e nada da sessão anterior é visível para a nova. Tudo aquilo de que a sessão seguinte precisa tem de ser transportado explicitamente; o resto desaparece. A restrição que molda a transferência é não haver caminho de regresso: a sessão nova não pode perguntar à antiga o que queria dizer, por isso o material transferido tem de se sustentar por si.

A falha visível de uma má transferência é reabrir decisões: a nova sessão volta a discutir o que a anterior tinha decidido, porque o material registou o que foi decidido, mas não porquê. Avalia a transferência pelo que uma sessão sem contexto consegue fazer com ela.

Uso:

«A sessão de planeamento está a ficar pesada — continuo?»

«Faz uma transferência. Regista as decisões num documento, termina esta sessão e começa a implementação numa sessão nova que o leia.»

Uma fonte de verdade em sua forma original — o código, a transcrição da conversa, o registro bruto, a resposta real da API. Não é um relato da coisa; é a própria coisa. Contraponto à fonte secundária.

Se quiser saber o que sua base de código faz, o código é a fonte primária. A documentação, o diagrama de arquitetura e o README são descrições dela — precisas quando foram escritos, mas seguindo seu próprio cronograma desde então. Quando um agente afirma com segurança algo errado sobre seu projeto, pergunte de qual fonte ele se baseou: um agente que leu a documentação herda a desatualização dela; um agente que leu o código está consultando a verdade atual.

O custo é o que impede as fontes primárias de serem a opção padrão. Carregar uma delas na janela de contexto é caro — o arquivo inteiro, a transcrição completa, cada token cobrado como entrada e disputando o orçamento de atenção. O que você recebe por esse custo é completude: nada foi filtrado previamente pelo julgamento de outra pessoa sobre o que importava. Um resumo escrito no mês passado não pode conter um detalhe que só hoje se mostrou importante; a fonte primária ainda o contém.

Consulte a fonte primária quando a precisão for importante — a assinatura exata, o erro real, a linha que gera a exceção. Grande parte da gestão do contexto consiste em decidir quando pagar pela fonte primária e quando uma fonte secundária é suficiente.

Exemplo de uso:

“O agente diz que a lógica de novas tentativas espera cada vez mais, mas estou vendo que bombardeia o endpoint.”

“Ele tirou isso do documento de design. Aponte para o módulo real de novas tentativas — trabalhe a partir da fonte primária quando o comportamento importar.”

Um relato de uma fonte primária, um passo distante dela — documentação que descreve código, um resumo que descreve uma transcrição, um relatório que descreve resultados de busca. É mais barato carregá-lo na janela de contexto do que carregar a fonte que descreve, e é inerentemente sujeito a perdas: quem o escreveu decidiu o que importava, e tudo que foi descartado fica invisível para quem só lê o resumo.

Grande parte da engenharia de contexto consiste em produzir fontes secundárias. A compactação transforma o histórico da sessão em um resumo que inicia a sessão seguinte. Um subagente usa a própria janela de contexto em uma busca ruidosa e retorna um relatório curto. Um artefato de transferência condensa as decisões da sessão em um documento lido pela próxima. Sistemas de memória destilam o que a sessão aprendeu em anotações. Todos fazem a mesma troca: fidelidade por espaço livre.

Fontes secundárias falham de duas maneiras. Elas perdem informação — como o resumo de compactação que omitiu a decisão de esquema ou o relatório que não mencionou o caso-limite. E ficam desatualizadas — a fonte primária muda, mas o relato não, então a documentação descreve a arquitetura do trimestre passado com a confiança deste trimestre. Quando um agente age com base em uma fonte secundária que falhou de qualquer uma dessas formas, trabalha com segurança a partir de informações incorretas; a solução é encaminhá-lo de volta à fonte primária.

Nenhuma dessas falhas significa que fontes secundárias sejam um erro. A janela de contexto é finita e as fontes primárias são caras; sem resumos, relatórios e documentos de transferência, nada grande caberia nela. A habilidade está em saber quais detalhes podem sobreviver à perda — e verificar na fonte primária quando não podem. Uma fonte secundária bem elaborada contém um ponteiro de contexto para seu original — o resumo que identifica a transcrição de origem, o documento que identifica o arquivo descrito — para que, quando o relato não for suficiente, o leitor possa seguir o ponteiro em vez de trabalhar a partir da perda.

Exemplo de uso:

“O documento de transferência diz que a autenticação está pronta, mas a sessão nova continua encontrando falhas na atualização do token.”

“O documento é uma fonte secundária — a sessão anterior registrou aquilo em que acreditava, não necessariamente a verdade. Peça à sessão nova para executar os testes de autenticação e confiar na fonte primária.”

Um documento usado como mecanismo de transporte de uma transferência — escrito no ambiente por uma sessão para ser lido por outra. Especificações, tarefas e documentos de planejamento são todos artefatos de transferência.

O motivo para escrever um é que o modelo é sem estado, então nada de uma sessão sobrevive à limpeza de contexto. Decisões, restrições e planos pela metade — tudo desaparece junto com o contexto que os continha. O ambiente persiste. Registrar o estado importante em um arquivo o desloca para um lugar que a próxima sessão poderá consultar.

O artefato é uma fonte secundária — um relato do trabalho da sessão, não o próprio trabalho. Isso o torna pequeno o bastante para orientar uma sessão nova e também explica por que pode induzi-la ao erro: registra aquilo em que a sessão que o escreveu acreditava, e qualquer coisa omitida ou incorreta fica invisível para quem o lê. Quando uma afirmação for importante, a próxima sessão deve verificá-la na fonte primária — o código e os testes — em vez de simplesmente herdá-la.

Um bom artefato é escrito para ser lido em uma sessão sem nenhum contexto. Use caminhos concretos de arquivos, não “o arquivo que discutimos”. Registre o que foi decidido e por quê, para que a próxima sessão não reabra a discussão. O que já foi feito e o que falta. É útil dizer à sessão que está escrevendo para onde o artefato vai: “escreva um documento de transferência para uma sessão nova que não sabe nada deste trabalho”.

O mecanismo alternativo é a compactação, que resume o conteúdo em memória. O artefato tem duas vantagens: fica no disco, onde você pode ler e corrigir seu conteúdo antes de alguém depender dele, e pode ser reutilizado — a mesma especificação pode orientar cinco sessões paralelas.

Exemplo de uso:

“Como divido isso entre o agente que planeja e aquele que implementa?”

“Peça ao planejador que escreva um artefato de transferência — caminhos de arquivos, decisões e restrições. A sessão do implementador começa com um ponteiro para o artefato e usa-o como orientação.”

Um artefato de transferência que descreve um trabalho realizado ao longo de várias sessões — o que está sendo construído, não como cada sessão contribui. Ele muda à medida que o trabalho avança. É composto por tarefas.

A especificação existe porque as sessões são descartáveis, mas projetos grandes não. Tudo que exige mais de uma janela de contexto de trabalho precisa de um lugar fora do contexto — em algum ponto do ambiente do agente que sobreviva à limpeza de contexto, seja um arquivo no repositório, uma issue do GitHub ou um rastreador de issues acessível ao agente. A especificação é esse lugar: o objetivo, as restrições, as decisões já tomadas e a lista de tarefas com seus estados. Qualquer sessão nova pode consultá-la e entender em que ponto o trabalho está sem herdar todo o ruído acumulado pela sessão anterior.

As especificações têm estilos reconhecíveis, em geral herdados das formas como as equipes já registram informações. Um documento de requisitos do produto (PRD) tende a enfatizar o quê e o porquê para quem usa — funcionalidades, comportamento e critérios de aceitação. Um documento de design ou RFC tende ao aspecto técnico — a abordagem escolhida, as alternativas descartadas e as compensações. No caso mais simples, um arquivo `plan.md` com uma lista de tarefas cumpre a mesma função para uma funcionalidade desenvolvida em várias sessões. O estilo importa menos do que o papel: para o agente, todos esses documentos são a mesma coisa — um registro duradouro da intenção, lido no início de cada sessão.

Exemplo de uso:

“Devemos fazer tudo em uma sessão?”

“Não. Documente como uma especificação, divida em tarefas e execute cada uma em sua própria sessão. Tentar fazer tudo em um único contexto vai levar você à zona de baixa capacidade antes da metade.”

Um artefato de transferência que delimita o trabalho de uma sessão. Pode existir sozinho ou ser uma tarefa filha de uma especificação. Tarefas irmãs podem bloquear umas às outras ou depender umas das outras, então a ordem do trabalho decorre do grafo de dependências, em vez de seguir um plano linear.

A restrição que define uma tarefa é seu tamanho: uma sessão. Ela deve poder ser concluída antes de a sessão sair da zona inteligente — e isso pode ser verificado. Se o contexto das sessões costuma se degradar antes de o trabalho terminar, as tarefas são grandes demais; divida-as. Se cada sessão passa a maior parte do tempo preparando o ambiente para depois executar cinco minutos de trabalho, elas são pequenas demais; junte-as.

Uma boa tarefa é escrita para alguém sem contexto adicional. O objetivo, os critérios de aceitação e os ponteiros de contexto para os arquivos e decisões relevantes — o suficiente para a sessão começar a trabalhar sem precisar reconstruir o que a anterior sabia.

O grafo de dependências também permite trabalhar em paralelo. Tarefas independentes — as folhas do grafo — podem ser executadas em sessões próprias ao mesmo tempo. Essa é uma maneira eficaz de executar vários agentes em paralelo. Em uma fábrica de software, marcar uma tarefa como pronta é, por si só, o gatilho que inicia sua sessão.

Exemplo de uso:

“Por onde começo na especificação da migração?”

“Veja o grafo de tarefas: a alteração do esquema bloqueia o preenchimento retroativo, que bloqueia a mudança da API. Escolha uma folha e execute uma sessão para ela.”

Uma transferência feita em memória: o histórico da sessão anterior é resumido, e esse resumo dá início a uma sessão nova. É intencionalmente sujeita a perdas: a transcrição é uma fonte primária, enquanto o resumo é uma fonte secundária — troca-se detalhe por espaço livre. Pode ser iniciada manualmente pelo usuário ou automaticamente por meio da compactação automática.

O mecanismo funciona assim: a janela de contexto é finita e uma sessão longa a preenche — todo resultado de ferramenta, todo arquivo lido e cada tentativa frustrada permanecem no histórico. Quando ele fica pesado, o ambiente de execução do agente pede ao modelo que resuma a sessão, descarta o histórico original e inicia uma sessão nova com o resumo. Tudo que não entrou no resumo desaparece do contexto. Alguns ambientes atenuam isso mantendo a transcrição antiga em disco e deixando um ponteiro de contexto para ela no resumo — a fonte secundária aponta de volta à primária, permitindo recuperar um detalhe perdido ao reler o original.

O resumo é escrito pelo modelo, então pode ser orientado por instruções. “Preserve as decisões de esquema” torna o artefato gerado mais deliberado. O momento também importa: faça a compactação no limite entre fases, depois de definir o plano, e não no meio de uma tarefa.

Compare com a limpeza de contexto, que descarta tudo e começa do zero: a compactação tenta levar o essencial adiante; a limpeza presume que tudo já foi anotado em algum lugar melhor.

Exemplo de uso:

“O contexto está ficando pesado e ainda preciso executar os testes.”

“Faça a compactação antes de começar — escreva no prompt do resumo o que precisa sobreviver, para que a nova sessão mantenha as decisões de esquema e descarte a exploração.”

A compactação é acionada automaticamente pelo harness quando a janela de contexto está quase cheia.

O harness acompanha o preenchimento da janela de contexto. Quando ultrapassa um limite — muitas vezes perto de 80% —, faz uma pausa, pede ao modelo que resuma a sessão até ao momento e inicia uma sessão nova com esse resumo. O trabalho prossegue como se nada tivesse acontecido.

Mas aconteceu algo. A compactação perde informação, e a compactação automática perde informação num momento que não escolheste. Uma compactação manual acontece numa transição entre fases, quando podes dizer ao modelo o que deve preservar. A compactação automática dispara a meio da tarefa, sempre que o limite é atingido — talvez a meio de uma refatorização, deixando o resumo decidir por si que decisões tuas mereciam ser mantidas. O sintoma clássico: o agente continua com confiança, mas esqueceu discretamente uma restrição que estabeleceste há uma hora, e só notas quando o trabalho começa a contradizê-la.

A defesa é impedir que aconteça. Observa o indicador de contexto e compacta manualmente numa transição natural, ou regista as decisões num plano ou artefacto de transferência no disco, onde nenhum resumo as possa perder. A maioria dos harnesses também permite personalizar a margem — antecipar ou adiar o limite, ou desativar por completo a compactação automática — para ajustares quanto espaço livre manténs antes de ela disparar.

Uso:

«Parece que já não se lembra do que decidimos antes sobre o esquema.»

«A compactação automática disparou entre turnos — as decisões iniciais foram resumidas e devemos ter perdido alguma coisa. Recarrega o documento do plano ou compacta manualmente da próxima vez para controlares o que fica.»

Um sistema que tenta dar estado a um agente entre sessões. Ele persiste informações no ambiente durante uma sessão e as recarrega na janela de contexto no início das sessões futuras, para que o agente mantenha a continuidade mesmo depois que o usuário faz a limpeza de contexto.

Um sistema de memória tem duas partes. O caminho de escrita: durante uma sessão, o agente registra o que aprendeu — uma preferência que você declarou, um fato sobre o projeto — em arquivos no ambiente. O caminho de leitura: no início da sessão, o ambiente de execução carrega esses arquivos, ou um índice deles, de volta à janela de contexto. Muitos ambientes já vêm com seu próprio sistema de memória — `/memory` do Claude Code é um exemplo —, mas você também pode criar o seu: um diretório de anotações mais uma instrução em AGENTS.md para consultá-lo.

Valem as mesmas compensações de qualquer conteúdo sempre carregado. As memórias se acumulam, então a maioria dos sistemas carrega um índice de uma linha e deixa o conteúdo atrás de ponteiros de contexto, em vez de inserir tudo. Além disso, memórias são fontes secundárias e ficam desatualizadas: um fato registrado em março é carregado em junho com a mesma confiança, embora o projeto já tenha mudado. Um sistema de memória precisa de poda, assim como AGENTS.md.

Exemplo de uso:

“Tenho que repetir sempre que usamos Postgres, não MySQL.”

“Configure um sistema de memória — grave o que ele aprende no sistema de arquivos durante o primeiro turno e recarregue no início da sessão. O próprio modelo é sem estado; a camada de memória simula continuidade.”

Um arquivo no ambiente que o ambiente de execução carrega na janela de contexto no início de cada sessão — a orientação permanente do projeto para o agente. É uma convenção entre ambientes; alguns também têm sua própria variante (a do Claude Code é CLAUDE.md).

Como é carregado automaticamente, esse arquivo é uma maneira de evitar que você repita instruções entre sessões. O modelo é sem estado: uma correção feita em uma sessão desaparece na seguinte, e você acaba dizendo a toda sessão nova que o projeto usa pnpm, que os testes são executados com uma opção específica e que determinado diretório é gerado e não deve ser alterado. Depois de corrigir o agente duas vezes pela mesma coisa, essa correção pode merecer uma linha no AGENTS.md.

O conteúdo adequado é aquilo que o agente não consegue deduzir do código: comandos de compilação e teste, convenções que não são óbvias na base de código e restrições rígidas (“nunca edite o cliente gerado”). Seja breve e declarativo — é uma orientação, não documentação.

A compensação é que tudo nele é carregado sempre. As instruções se acumulam e, em sua maioria, são irrelevantes para cada tarefa específica; um AGENTS.md longo também consome tokens e dilui as próprias instruções — quanto mais instruções no contexto, menos confiavelmente o agente segue cada uma.

Evite: usar AGENTS.md para conteúdo que deveria ser revelado progressivamente — tudo o que está nele custa tokens em cada turno, em todas as sessões, mesmo quando não é necessário. Um guia de estilo pode ficar atrás de uma habilidade ou de um ponteiro de contexto; deixe no AGENTS.md apenas as regras que se aplicam a tudo.

Exemplo de uso:

“Por que toda sessão começa com 4 mil tokens já consumidos?”

“Confira o AGENTS.md — alguém colou nele o guia de estilo inteiro em vez de colocá-lo atrás de uma habilidade.”

Carregar apenas o contexto de que o agente precisa agora, com ponteiros de contexto para o restante. O conceito vem do design de interfaces, em que significa mostrar aos usuários apenas os controles relevantes para a tarefa atual e esconder os outros atrás de um clique.

A técnica existe porque o contexto tem um custo duplo. Cada token carregado de antemão é cobrado como token de entrada em cada turno, e consome atenção, seja ou não necessário para o agente. Um AGENTS.md abarrotado com todo o guia de estilo, manual de implantação e convenções de banco de dados deixa o agente pior em todas essas atividades — as instruções relevantes para a tarefa atual se diluem entre as irrelevantes. O sinal disso é um agente ignorando regras que você sabe que estão no contexto: elas estão lá, mas enterradas.

A revelação progressiva inverte esse padrão. Mantenha pequena a camada sempre carregada — uma frase por tópico e um ponteiro para onde estão os detalhes. O agente lê o guia de estilo quando está escrevendo um componente, o manual de implantação quando está implantando e nenhum dos dois quando está corrigindo um teste. Habilidades são o padrão integrado ao ambiente de execução: uma descrição curta carregada em cada sessão e as instruções completas carregadas apenas quando acionadas.

Exemplo de uso:

“Devo despejar o guia de estilo inteiro no AGENTS.md?”

“Não — use revelação progressiva. Referencie o guia de estilo como uma habilidade, que o agente carrega quando realmente precisa escrever um componente. O AGENTS.md cobra tokens a cada turno.”

Uma menção em um documento que aponta para outro, para que o agente possa trazê-lo para a janela de contexto apenas quando a tarefa exigir. É a unidade de que se compõe a revelação progressiva.

O motivo para usar um ponteiro em vez de inserir o conteúdo é o custo. Um ponteiro ocupa uma linha na janela de contexto. O documento indicado pode ter milhares de tokens, mas esses tokens não custam nada até que o agente siga o ponteiro. Insira um manual de operação de 2.000 tokens em AGENTS.md e todas as sessões pagarão por ele; substitua-o por “processo de implantação: consulte `internal/deploy.md`” e só as sessões que implantam algo o carregarão. O agente segue o ponteiro com uma chamada de ferramenta quando a tarefa corresponde ao conteúdo indicado.

Um ponteiro precisa de duas partes para funcionar: um caminho estável e uma descrição suficiente para o agente saber quando vale a pena segui-lo. Um caminho isolado não dá motivo para segui-lo; “consulte `internal/deploy.md`” sem nenhuma indicação do conteúdo pode ser ignorado por uma sessão que precisa dele. Escreva a linha de modo que corresponda à forma como as tarefas são apresentadas: “versão, implantação ou reversão — leia `internal/deploy.md` primeiro”.

Os ponteiros estão por toda parte quando você começa a procurá-los: linhas em AGENTS.md, descrições de habilidades (o ambiente carrega a descrição; o corpo da habilidade fica atrás dela), nomes de arquivos em uma listagem de diretório e links entre documentos.

Um ponteiro também pode vincular uma fonte secundária à fonte primária da qual ela foi derivada — o resumo de compactação que identifica a transcrição original, ou o documento que indica o arquivo-fonte que descreve. Isso permite recuperar as perdas da fonte secundária: quando o resumo não é suficiente, o agente segue o ponteiro e lê o original, em vez de trabalhar apenas com o que o resumo preservou.

Evite: “referência” — é seco demais; não transmite que seguir o ponteiro acrescenta mais contexto. “Portal” — é rebuscado demais.

Exemplo de uso:

“O AGENTS.md está ficando enorme.”

“A maior parte deveria ser ponteiros de contexto, não conteúdo. Mantenha as regras sempre ativas no próprio arquivo; transforme o manual de implantação e o guia de estilo em habilidades e deixe um ponteiro de contexto no lugar.”

Uma capacidade ensinável, agrupada como unidade — instruções e recursos para realizar bem uma tarefa, mantidos no ambiente até que um ponteiro de contexto os traga para a janela de contexto quando necessário. É a unidade de revelação progressiva em um ambiente de execução.

Habilidades são um padrão aberto, definido em agentskills.io — criado originalmente pela Anthropic e adotado desde então pela maioria dos principais ambientes, de modo que uma habilidade escrita uma vez funciona em todos eles. O formato consiste em uma pasta que contém:

• Um arquivo `SKILL.md` — metadados (no mínimo, nome e descrição) e as próprias instruções
• Opcionalmente, scripts que o agente pode executar
• Opcionalmente, modelos e material de referência indicados pelas instruções

Por padrão, apenas o nome e a descrição ficam no contexto. Quando a tarefa do agente corresponde à habilidade, ele carrega o restante. Até lá, ela ocupa pouquíssimo espaço — uma ou duas frases de tokens, por maior que seja o conjunto completo de instruções.

Isso diferencia as habilidades de AGENTS.md, que é carregado em todas as sessões, independentemente da tarefa. Uma habilidade é carregada quando surge um tipo específico de trabalho — publicar uma versão, estruturar um novo serviço, escrever uma migração — e ignorada no restante do tempo.

Evite: “ferramenta” — uma ferramenta é aquilo que o agente chama; uma habilidade contém as instruções que ele lê.

Exemplo de uso:

“Onde devo colocar o manual de implantação?”

“Como uma habilidade — o agente a carrega apenas quando a tarefa envolve implantações. No AGENTS.md, consumiria tokens em cada turno por algo que usamos semanalmente.”

Um agente iniciado por outro agente por meio de uma chamada de ferramenta. Executa em sua própria sessão, com sua própria janela de contexto, e retorna um único resultado de ferramenta. É diferente de uma transferência — o agente pai espera especificamente uma resposta; uma transferência não tem caminho de retorno. Não pode iniciar outros subagentes — a árvore tem apenas um nível. Subagentes existem para isolar o contexto, não para compor hierarquias.

A ideia é manter o trabalho ruidoso fora do contexto do agente pai. Se a busca ampla ou a longa exploração de arquivos for executada pelo pai, páginas de resultados de ferramentas ficarão no contexto dele pelo restante da sessão, embora a maioria só seja útil enquanto se encontra a resposta. Se forem executadas por um subagente, o ruído preenche uma janela descartável; apenas o relatório final chega ao contexto do pai. O relatório é uma fonte secundária: o pai recebe o relato do subagente sobre o que encontrou, não os resultados brutos, então qualquer detalhe omitido pelo relatório fica invisível para o agente pai.

Subagentes também são executados simultaneamente — um agente pai pode distribuir várias tarefas independentes de uma só vez.

Exemplo de uso:

“Os resultados do grep estão enchendo meu contexto.”

“Peça a um subagente que faça a busca — ele usará a própria janela de contexto para absorver o ruído e retornará os dois caminhos de arquivo de que você realmente precisa.”

Um padrão de trabalho em que uma ou mais pessoas atuam em conjunto com o agente durante uma sessão — revisando, redirecionando ou colaborando em tempo real. A pessoa está presente e envolvida, não apenas aprovando ações individuais.

O contraste é com o trabalho AFK, em que o agente funciona sem supervisão e você avalia o resultado depois. A participação humana no processo permite detectar problemas enquanto ainda são baratos: você vê o agente recorrer ao arquivo errado, interpretar mal o requisito ou seguir por um caminho sem saída e o redireciona em uma frase — em vez de descobrir vinte minutos de trabalho confiante baseado naquele erro. Agentes não sabem com segurança quando estão no caminho errado; quando deixados sozinhos, tendem a avançar em vez de parar e perguntar.

O padrão adequado depende da tarefa. Tarefas bem especificadas, de baixo risco e fáceis de verificar combinam com AFK. Tarefas ambíguas, irreversíveis ou cujo resultado seria difícil de revisar — uma migração de esquema, uma decisão de design complexa, qualquer coisa que afete a produção — combinam com a permanência de uma pessoa no processo. A decisão depende basicamente do custo de uma escolha errada e de quão tarde você a detectaria.

Alguns trabalhos exigem participação humana por natureza, pois as reações da pessoa são parte da entrada. Uma entrevista socrática só funciona se você estiver presente para responder às perguntas; a prototipagem só funciona se você estiver presente para reagir ao artefato.

Permanecer no processo consome sua atenção, que é o recurso escasso. Parte do desenvolvimento do trabalho com agentes consiste em transferir mais tarefas para fora do processo com segurança — usando planos, verificações automatizadas e revisão humana no final, em vez de supervisão contínua. Uma fábrica de software vai além e inicia sessões a partir de gatilhos, para que nem mesmo o início do trabalho dependa de você.

Exemplo de uso:

“Deixo isso rodando AFK durante a noite?”

“Não, é uma migração de esquema — mantenha uma pessoa no processo. Quero ver cada etapa e orientar se escolher a coluna errada para o preenchimento retroativo.”

Longe do teclado. Um padrão de trabalho em que o usuário inicia uma sessão e deixa o agente executar sem supervisão. É o multiplicador de produtividade da programação com IA — várias sessões AFK podem ser executadas em paralelo enquanto você dorme, come ou trabalha em outra coisa. Em geral, exige um modo de permissão permissivo e isolamento para ser seguro.

Quando você não está presente, o agente lida com ambiguidades de outra forma. Enquanto você observa, uma decisão ambígua aparece como pergunta e você responde; depois que vai embora, o agente escolhe um padrão e continua, e todas as decisões seguintes se apoiam nesse palpite. A falha característica é voltar horas depois e encontrar um trabalho concluído e confiante, baseado em uma escolha errada feita nos primeiros dez minutos. O trabalho não é descuidado — é coerente, mas coerente em torno da coisa errada.

Como não pode receber orientações durante a execução, forneça-as antes e depois. Antes: resolva as ambiguidades de antemão — em uma sessão de entrevista socrática ou com uma especificação escrita — para reduzir as lacunas que o agente terá de preencher sozinho. Durante: verificações automatizadas e revisão automatizada fazem as vezes da atenção que você não está oferecendo e detectam rapidamente aquilo que pode ser verificado mecanicamente. Depois: a execução termina em algo que permita revisão — um PR, não alterações que já foram integradas. O modo AFK não elimina a revisão humana; apenas a adia para o final, por isso o resultado precisa valer a revisão. Por essa mesma razão, a AX é mais importante em execuções AFK: sem ninguém observando, o ambiente é o único suporte do agente.

Evite: “agente em segundo plano” — põe a máquina em primeiro plano (“executando em segundo plano”) em vez do padrão humano (“o usuário se afastou”). AFK nomeia o fato relevante: o usuário não está acompanhando.

Exemplo de uso:

“Vou deixar isto rodando AFK durante a noite — três agentes isolados trabalham na refatoração e eu reviso os PRs de manhã.”

“Ignorar permissões?”

“Sim, com sistema de arquivos somente para leitura e sem rede.”

Uma verificação determinística executada no ambiente — testes, verificação de tipos, linters, compilação, hooks de pré-commit. Aprovação ou reprovação, sem julgamento. É o sinal a partir do qual um agente pode se corrigir sem envolver outra pessoa. Um teste instável é uma verificação quebrada, não algo que deixou de ser verificação; por definição, as verificações automatizadas são determinísticas.

A autocorreção funciona em ciclo. O agente faz uma alteração, executa a verificação como chamada de ferramenta e a saída da falha aparece na janela de contexto — um erro de tipos com arquivo e linha, uma asserção que falhou com valores esperados e reais. Isso basta para que o agente corrija o problema e execute a verificação novamente, repetindo o ciclo até passar, sem intervenção humana. O determinismo torna o ciclo confiável: o mesmo código sempre produz o mesmo resultado, então uma aprovação significa algo. Uma verificação instável contamina o processo: o agente “corrige” código que estava certo ou repete as tentativas até passar por cima de uma falha real.

É por isso que boas verificações são parte importante da AX de uma base de código. Em um repositório com tipos estritos, uma suíte de testes rápida e um linter, o agente detecta a maioria dos próprios erros antes que você os veja; em um repositório sem nada disso, entrega qualquer coisa que produzir. A diferença importa sobretudo nas execuções AFK, em que as verificações são a única validação durante a execução. Mas uma verificação só detecta o que afirma verificar: resultados verdes significam que as propriedades afirmadas são verdadeiras, não que o código está correto. As lacunas que exigem julgamento são o motivo de existir a revisão automatizada e a revisão humana.

Evite: “ciclo de feedback” / “contrapressão” — ambos confundem verificações com revisão. Evite: “teste” — testes são verificações automatizadas, mas nem toda verificação automatizada é um teste.

Exemplo de uso:

“O agente continua entregando código quebrado nas execuções AFK.”

“Quais verificações automatizadas estão configuradas no ambiente isolado?”

“Só os testes unitários.”

“Adicione verificação de tipos e lint — ele vai se corrigir com base nisso antes mesmo de o PR ser integrado.”

Um agente que revisa o trabalho de outro agente, muitas vezes com um modelo ou prompt de sistema diferente. É não determinístico: forma um julgamento. Pode ser executado em qualquer etapa — antes da integração de um PR, depois em um histórico de commits, no meio de uma sessão como subagente. Um modelo de linguagem que atua como juiz na CI é revisão automatizada, não uma verificação automatizada; a categoria depende do que a afirmação verifica, não do lugar em que ela é executada.

A separação do agente que está trabalhando é o que torna isso eficaz. Pedir ao agente que escreveu o código para revisar o próprio trabalho produz pouco resultado: a sessão que criou o bug também contém o raciocínio que levou a ele, e o agente lê as próprias conclusões como confirmação. Um revisor com uma janela de contexto nova não tem esse apego: vê o diff como uma pessoa de fora, que é justamente o que a revisão exige. Um modelo diferente ou um prompt de sistema específico para revisão reforça isso — pontos cegos distintos e um prompt restrito àquilo que realmente importa (segurança, contratos de API, desempenho), em vez de um vago “procure problemas”.

Ela ocupa o espaço entre as outras camadas de revisão. Verificações automatizadas são determinísticas e detectam o que pode ser afirmado mecanicamente; a revisão humana é cara e tem a pior escalabilidade. A revisão automatizada fica no meio: detecta problemas que exigem julgamento — um nome de função enganoso, um caso-limite ignorado — a custo de máquina. Como não é determinística, pode deixar passar problemas e apontar coisas que não são problemas; trate-a como um filtro que eleva o nível antes de uma pessoa avaliar, não como um controle que substitui a revisão humana.

Evite: “revisão por IA” / “revisão por agente” — são vagas demais para diferenciá-las do próprio agente que está trabalhando.

Exemplo de uso:

“Os PRs das execuções AFK estão vindo ruins demais.”

“Adicione uma etapa de revisão automatizada antes da integração — outro modelo, um prompt de sistema separado, voltado a alterações de segurança e contratos.”

O utilizador que lê o código produzido pelo agente e forma um juízo sobre ele. Ler o diff ou os ficheiros alterados conta; ler a descrição do agente sobre o que fez, não: a narração não é o artefacto. A descrição é uma fonte secundária, escrita por quem está a ser revisto; o diff é a fonte primária, e rever significa lê-lo.

Os agentes aumentam o volume de código produzido, por isso a revisão torna-se o estrangulamento. Uma ideia útil é combinar diferentes estratégias de revisão em camadas. As verificações automatizadas detetam falhas mecânicas, a revisão automatizada deteta as que podem ser descritas, e a revisão humana fica reservada ao que só tu podes avaliar: se a alteração é a certa, se a abordagem se adequa à base de código e se isto devia sequer existir.

A revisão também fica mais barata quanto mais cedo for feita. Ler um plano antes de o trabalho começar, ou um diff pequeno a meio do trabalho, demora minutos; escavar uma branch concluída depois de uma execução sem supervisão demora mais. O ponto em que colocas a revisão é uma decisão de intervenção humana, não algo a decidir à última hora.

Evita: usar apenas «revisão de código», que é ambíguo entre revisão humana e automatizada.

Uso:

«Revisei manualmente o resultado da execução sem supervisão.»

«Leste o diff ou apenas o resumo?»

«O diff. O resumo dizia que tinha eliminado código morto — afinal, a função era chamada a partir de um ficheiro gerado.»

Um padrão de trabalho em que o usuário aceita o código do agente sem revisão humana. O diff é tratado como uma caixa-preta — o que importa é o comportamento do programa, não seu conteúdo. Ainda pode haver revisão automatizada e verificações automatizadas; a programação por intuição não toma posição sobre nenhuma delas.

O termo vem de Andrej Karpathy, que o cunhou no início de 2025: você “se entrega completamente à intuição” e “esquece que o código sequer existe” — descreve o que quer, aceita o que recebe e avalia executando.

A programação por intuição troca inspeção por velocidade. Ler diffs costuma ser a etapa mais lenta do trabalho com agentes, então eliminá-la remove o principal gargalo. Para código cujas falhas têm baixo custo — protótipos, scripts de uso único, ferramentas internas — essa é uma troca razoável. O risco aumenta conforme a vida útil e a importância do código.

O custo aparece mais tarde. Alterações feitas por intuição se acumulam em uma base de código que ninguém leu, e apenas o comportamento foi verificado — assim, tudo o que não aparece no comportamento, como um segredo gravado nos registros, um caso-limite ausente ou um tratamento de dados discretamente incorreto, é entregue sem ser percebido. A primeira vez que alguém depura o sistema é também a primeira vez que alguém lê o código. Sem revisão humana, qualquer verificação automatizada que ainda exista — testes, tipos, revisão automatizada — é o único controle pelo qual o código passa. Aplicar a mesma postura a uma base de código inteira, ou a parte dela, cujas alterações vêm de uma fábrica de software transforma-a em uma fábrica obscura.

Evite: usar “programação por intuição” como sinônimo de “programação com IA de baixa qualidade” — o termo descreve a postura em relação à revisão, não a qualidade resultante do código.

Exemplo de uso:

“Você leu o que ele alterou no fluxo de autenticação?”

“Fiz programação por intuição — o login ainda funciona, foi só isso que verifiquei.”

“Leia o diff antes de enviar; deixar a autenticação por conta da intuição é como segredos acabam nos registros.”

A compreensão partilhada do que está a ser construído, mantida em comum pelo utilizador e pelo agente, mas distinta de qualquer recurso. Termo de Brooks (The Design of Design): a conversa, os artefactos de transferência e o código são recursos que tentam registar ou alcançar o conceito de design, mas nenhum deles é esse conceito. A qualidade do conceito de design percebe-se pela qualidade da conversa que o construiu.

O termo dá nome à lacuna por trás de uma frustração conhecida: o agente escreve exatamente o que pediste e, ainda assim, está errado. A causa habitual é não teres definido por completo o que querias. O conceito de design ainda não estava completo na tua própria cabeça: o teu pedido registava as partes que já tinhas pensado e omitia as partes que ainda não tinhas resolvido. O agente preencheu esses silêncios com as suas próprias suposições, porque não havia nada com que se pudesse alinhar. Nada avariou. Não existia um conceito de design partilhado, porque ainda não havia um conceito completo para partilhar.

Percebes que um conceito de design é partilhado da mesma forma que percebes isso com um colega: a outra parte começa a responder às perguntas que ainda não fizeste, da maneira como tu responderias. Até lá, o trabalho é conversa — interrogar a fundo é a versão deliberada —, e escrever uma especificação cedo demais apenas regista o desalinhamento num recurso mais duradouro. O conceito de design também evolui à medida que aprendes; os recursos ficam para trás, razão pela qual uma especificação fiel à compreensão da semana passada ainda pode induzir em erro na sessão desta semana.

Uso:

«Está a escrever exatamente o que pedi e, mesmo assim, está errado.»

«Ainda não partilham um conceito de design: está a preencher lacunas com suposições. Continuem a conversar até que cancelamentos, reembolsos e processamento parcial estejam alinhados entre vocês, antes de o deixares escrever uma especificação.

Uma técnica para desenvolver um conceito de design com um agente: o agente entrevista o usuário socraticamente, uma decisão por vez, propondo uma resposta recomendada para cada pergunta. Ela desacelera a corrida para chegar a um plano concluído — nenhum artefato de transferência é escrito antes de o conceito se estabilizar.

A técnica existe porque agentes preenchem lacunas silenciosamente. Se você pedir que escrevam uma especificação a partir de um prompt de duas linhas, eles não vão parar nas decisões que você ainda não tomou — escolherão padrões e os registrarão. O resultado parece completo, e os palpites são indistinguíveis das escolhas, então você só os descobre tarde: durante a revisão ou quando a funcionalidade implementada trata um caso-limite de um jeito que você nunca escolheu. A entrevista socrática inverte isso: em vez de adivinhar, o agente precisa perguntar.

É uma técnica com participação humana no processo: as respostas são a entrada. Quando não for possível responder a uma pergunta em conversa — porque você precisaria ver a coisa —, passe à prototipagem.

Exemplo de uso:

“Ele foi direto para a escrita da especificação e errou a lógica de cancelamento.”

“Faça uma entrevista socrática primeiro — peça que pergunte sobre cancelamentos parciais, reembolsos e prazos antes de registrar qualquer coisa no documento. É mais barato resolver em conversa do que no código.”

Fazer o agente construir rapidamente uma versão simples de algo, quando a conversa tem pouca fidelidade e você precisa de um artefato real para discutir.

A entrevista socrática resolve decisões de design por meio de conversa. Conversar é barato, mas tem pouca fidelidade: algumas perguntas não podem ser respondidas em palavras — como é a sensação de uma interação, se uma API é ergonômica no código real que a chama, ou se o layout funciona com volumes reais de dados. A entrevista chega a uma pergunta cuja resposta honesta é “não sei, precisaria ver”. Depois disso, a discussão fica girando em círculos. Em vez disso, peça ao agente que construa a coisa, examine-a e retome a conversa com uma resposta.

Agentes reduzem o custo de construção, e é isso que torna a técnica prática. Uma versão simples que antes levaria um dia para fazer como protótipo agora leva minutos, então vale a pena fazê-la com frequência. É uma técnica com participação humana no processo: o protótipo existe para que você reaja a ele.

Normalmente, você não se limita a olhar uma vez. Itere com o protótipo — reaja, peça uma alteração, reaja novamente —, de modo que cada rodada resolva outra decisão com base no artefato real, em uma fidelidade maior do que a conversa permite.

Um protótipo não precisa ser inteiramente improvisado. Você pode construir com qualidade de produção os componentes que está realmente avaliando, para que, depois de tomada a decisão, o componente ou a API que avaliou possa ser incorporado à base de código real. Por isso, protótipos são material essencial para a especificação usar como referência.

Exemplo de uso:

“Passamos meia hora discutindo se o assistente deveria ter uma página ou três etapas.”

“Palavras não vão resolver; peça ao agente que prototipe as duas opções. Vamos clicar nelas e saber em cinco minutos.”

Experiência do desenvolvedor — a facilidade com que uma base de código e suas ferramentas permitem que as pessoas façam um bom trabalho. Uma boa DX oferece feedback rápido, mensagens de erro claras, documentação que responde à dúvida real e uma configuração que funciona na primeira tentativa. O termo é muito anterior à programação com IA; neste dicionário, aparece sobretudo como contraponto a AX.

DX é a interação entre a pessoa e a base de código — nada além disso. A principal diferença entre os dois públicos é que pessoas mantêm estado, enquanto agentes não mantêm. Uma pessoa aprende a base de código uma vez e leva esse conhecimento para todos os dias seguintes, e é por isso que uma DX ruim é suportável: contorna uma CI lenta agrupando os envios, contorna a falta de documentação perguntando uma vez no Slack e contorna uma estrutura confusa lembrando onde cada coisa fica. As soluções alternativas se acumulam, e a equipe acaba sendo produtiva em uma base de código que a atrapalha.

Agentes encaram a mesma base de código sem nenhum desse conhecimento acumulado. Sem estado entre sessões, o agente reaprende a base do zero a cada vez — ele se beneficia de uma suíte de testes rápida e mensagens de erro claras, mas tudo que descobriu ontem desaparece, a menos que tenha sido registrado no ambiente, que o agente só percebe por meio dos resultados de ferramentas. Essa é a lacuna que AX nomeia: os aspectos da DX que sobrevivem quando quem desenvolve é um agente, além de preocupações que as pessoas não têm, como manter livre a janela de contexto.

A sobreposição significa que investimentos em DX muitas vezes melhoram AX sem custo adicional — tipos estritos, testes rápidos e estrutura previsível ajudam ambos. A divergência significa que isso nem sempre acontece: uma documentação de integração excelente ajuda uma pessoa por uma semana e não ajuda em nada o agente, a menos que possa ser encontrada a partir do AGENTS.md.

Exemplo de uso:

“Nossa DX está boa — quem entra na equipe se torna produtivo em uma semana.”

“Fica produtivo porque alguém passa a semana ao lado da pessoa. O agente não tem essa semana; avalie a AX separadamente.”

Experiência do agente — o quanto o ambiente está preparado para que um agente trabalhe bem em uma base de código. É a contraparte de DX voltada ao agente. Quando o mesmo agente tem bom desempenho em um repositório e ruim em outro — mesmo modelo, mesmo ambiente de execução —, a diferença geralmente é AX. O instinto é culpar o modelo ou reescrever o prompt; com mais frequência, a correção está no repositório.

Uma boa AX tem três dimensões principais:

AX e DX se sobrepõem — boas verificações e uma arquitetura limpa ajudam ambos os públicos —, mas também divergem. Pessoas toleram conhecimento tribal, CI lenta e “pergunte à Sarah sobre o módulo de faturamento”; agentes não. Dicas de ferramentas na IDE e painéis elegantes não ajudam os agentes; eles precisam receber as falhas em texto como resultado de ferramenta. Uma base de código pode ter uma boa DX e uma AX ruim.

Evite: tratar AX como sinônimo de DX — públicos diferentes exigem investimentos diferentes.

Exemplo de uso:

“O agente escreve um ótimo código no repositório de API e um péssimo código no frontend.”

“O repositório de API tem tipos estritos e uma suíte de testes rápida; o frontend não tem nenhum dos dois e possui quarenta habilidades carregadas o tempo todo. Essa é uma lacuna de AX, não um problema do modelo.”

Um sistema de trabalho em que sessões de agentes são iniciadas por gatilhos — criação de uma issue, um agendamento, uma falha de CI, o término de outra sessão — em vez de por uma pessoa, fazendo com que mais trabalho ocorra em modo AFK e a atenção humana fique reservada às decisões restantes com participação humana no processo.

Sem uma fábrica, cada sessão começa porque alguém a iniciou. Mesmo um trabalho totalmente AFK depende de uma pessoa para abrir a sessão, apontá-la para a tarefa e dar início. As equipes querem entregar mais do que isso permite. A fábrica tira a pessoa do início das sessões, mas não necessariamente de todo o resto.

Gatilhos comuns e as sessões que iniciam:

Uma fábrica não precisa abranger todo o processo de desenvolvimento. Um único cron que executa um tipo de sessão e abre um PR revisável já é uma fábrica. É útil começar pequeno: um ciclo restrito produz PRs pequenos e semelhantes, e analisá-los mostra até onde se pode confiar nesse ciclo antes de ampliá-lo.

As pessoas podem participar em qualquer ponto da fábrica — escrevendo e rotulando as issues que iniciam sessões, aprovando um plano antes da implementação, fazendo a revisão humana antes da integração. Decidir quais dessas decisões continuam humanas é a principal questão de design. Uma base de código, ou parte dela, em que ninguém revisa os resultados da fábrica é uma fábrica obscura.

Exemplo de uso:

“Quem corrigiu todas as violações de `no-floating-promises`?”

“A fábrica. O cron escolhe uma regra de lint por noite e abre um PR. Eu só faço a revisão de manhã.”

Uma base de código, ou parte dela, na qual uma fábrica de software escreve o código e nenhuma pessoa o lê. Não há revisão humana. As pessoas ainda podem escrever as issues que iniciam o trabalho, mas ninguém lê o código produzido. O nome vem das fábricas “apagadas”, que fabricam coisas sem pessoas no chão de fábrica.

Uma fábrica obscura é programação por intuição aplicada a uma área de código, não a uma única alteração. Quando você programa por intuição, escolhe não ler uma alteração que pediu. Mas sabe que ela existe. Em uma fábrica obscura, a equipe faz essa escolha uma vez para a área inteira. Depois disso, ninguém solicita ou vê cada alteração. Elas chegam tão rápido quanto os gatilhos iniciam novos trabalhos.

O problema aparece quando algo quebra. Você não sabe o que mudou, pois ninguém leu as alterações. Precisa depurar código que ninguém da equipe leu. A causa pode estar em qualquer uma das muitas alterações, e cada uma passou pelas verificações.

As verificações automatizadas e a revisão automatizada são os únicos controles. Se não detectarem um problema, ele entra no código.

Evite: chamar uma base de código de “obscura” só porque a fábrica funciona sem ninguém observando. Se agentes executam sessões em modo AFK e uma pessoa revisa seus PRs, trata-se de uma fábrica de software. Não é uma fábrica obscura.

Exemplo de uso:

“Quem alterou a lógica de novas tentativas no serviço de faturamento? Ninguém da equipe se lembra.”

“O serviço de faturamento é uma fábrica obscura. Os agentes integram todas as alterações aprovadas pela CI. Ninguém leu aquela alteração.”