A espinha dorsal é Modularizing React Applications with Established UI Patterns, publicado em partes por Juntao Qiu, da Thoughtworks, no martinfowler.com em fevereiro de 2023. Não traduzi o original. Reescrevi com as minhas palavras, e todas as figuras do texto vêm desse artigo. Por cima disso, baixei o repositório de exemplo do autor, rodei a checagem de tipos e os testes, e acrescentei os resultados junto com outros materiais que tratam do mesmo problema.

React é uma view library

Quando se aprende React, a ideia mais atraente é que a UI é uma função pura que transforma dados em DOM. Até certo ponto, é verdade. Mas no momento em que você manda uma requisição ao servidor ou navega para outra página, o component deixa de ser puro. Junte a isso o state global e o state local se entrelaçando, e o código fica complicado rapidinho.

A resposta do autor é mudar o ponto de vista. Não existe uma espécie à parte de software chamada "aplicação React". React é uma library que desenha a UI, e onde colocar cálculos ou regras de negócio nunca foi uma preocupação dela. O que fica por cima é um app JavaScript comum. Sendo assim, dá para usar como estão os designs que vêm desde a época das GUIs de desktop, em especial a divisão do código em três layers: presentation, domain e data.

Um app de frontend real tem, além da view, router, local storage, vários níveis de cache, requisições de rede, integração com serviços externos e login, segurança, logging e ajuste de performance. Se você empurra tudo isso para components e hooks, num mesmo arquivo a linha que pede o status do pedido é seguida por uma linha que tira os espaços do começo de uma string, e depois por uma linha que navega para outra tela. Quem lê precisa ficar indo e voltando enquanto troca de nível de abstração o tempo todo.

Os motivos para dividir se resumem a dois. A tela muda com mais frequência do que as regras de negócio. E, com as duas separadas, basta pensar em uma coisa de cada vez. O segundo motivo é o que Martin Fowler aponta em PresentationDomainDataLayering como a maior vantagem dessa separação. Como dá para pensar nos três temas de forma relativamente isolada, o escopo que exige atenção diminui.

Cinco estágios de crescimento de um app

Antes de entrar na refatoração, o autor mostra em cinco figuras como a estrutura muda conforme o app cresce. O que importa é o gatilho para passar ao estágio seguinte. Não é um momento predeterminado: o incômodo que surge em cada estágio é o que chama o próximo. As cores têm o mesmo significado nas cinco figuras. Verde-claro é o container component que tem state, verde-escuro é o presentational component que só desenha, roxo é hook, azul é domain object e laranja é infrastructure, como a rede.

No começo, um único component tem requisição de rede, state, cálculo e render. Para um app pequeno ou um projeto descartável isso basta, e como o código se parece com HTML, fica até mais fácil de ler. Quando o código que percorre uma lista para montar itens se mistura com o código que configura components externos e ler o que está acontecendo começa a tomar tempo, é hora do próximo estágio.

Quando a tela cresce, os components são divididos seguindo o formato do HTML resultante. Os components que só desenham se separam, mas no component do topo continuam a requisição de rede, o código que transforma a resposta no formato da tela e o código que junta os dados a mandar para o servidor. Nenhum dos três é UI, e mesmo assim estão dentro do component.

Em seguida, o state e suas mudanças vão para um custom hook. Aí sobra dentro do hook um cálculo puro, que não é side effect nem state.

Extraindo esse cálculo para um objeto que não tem nada a ver com React, nasce um domain object. Conversão de formato de dados, checagem de null e valores de fallback vêm para cá. Conforme os objetos se multiplicam, herança e polimorfismo começam a ser necessários.

Por fim, quando aparecem objetos que não pertencem à UI e nem se importam se os dados vêm do servidor, do local storage ou de um cache, eles são agrupados à parte em uma model layer.

Só pelas figuras, fica abstrato. Vamos percorrer esses cinco estágios uma vez com código de verdade. O exemplo escolhido pelo autor é a tela de pagamento de um pedido online.

Partindo de uma única tela de pagamento

Os meios de pagamento vêm da configuração do servidor e variam por país. Se o servidor devolve pelo menos um, o pagamento em dinheiro é acrescentado no fim e deixado selecionado como padrão. Se não devolve nenhum, nada é exibido.

O código inicial tem a cara que se vê em todo tutorial. Faz fetch dentro do useEffect, transforma a resposta no formato da tela, acrescenta o pagamento em dinheiro e desenha a lista de radios. Abaixo está a versão que eu resumi.

export const Payment = ({ amount }: { amount: number }) => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
 
  useEffect(() => {
    fetch(url)
      .then((res) => res.json())
      .then((methods: RemotePaymentMethod[]) => {
        if (methods.length === 0) return setPaymentMethods([]);
        const extended = methods.map((m) => ({ provider: m.name, label: `Pay with ${m.name}` }));
        extended.push({ provider: "cash", label: "Pay in cash" });
        setPaymentMethods(extended);
      });
  }, []);
 
  return (
    <div>
      {paymentMethods.map((method) => (
        <label key={method.provider}>
          <input type="radio" defaultChecked={method.provider === "cash"} />
          {method.label}
        </label>
      ))}
      <button>${amount}</button>
    </div>
  );
};

Nesse tamanho, não é problema. Mas para mexer nesse component é preciso entender quatro coisas ao mesmo tempo: como a requisição de rede começa, como os dados do servidor viram o formato que a tela conhece, como se desenha um meio de pagamento e como se desenha a área de pagamento inteira. Conforme o código cresce, quem lê precisa ficar indo e voltando entre essas quatro.

Hooks e pure components

A primeira coisa a extrair é o state e o fetch. O sinal é simples. Quando o código sem relação com render passa da metade do corpo do component, ele vai para um hook. O usePaymentMethods cuida do fetch e da conversão, e o component só recebe o array que o hook entrega e desenha.

A segunda é o JSX que desenha a lista. Quando aparece um bloco que dá para desenhar recebendo só props, ele vira um component. PaymentMethods é um pure component que recebe apenas um array de meios de pagamento, então é fácil de testar e reutilizar. Mesmo que depois ganhe um callback onSelect para avisar da seleção, continua pure, porque não toca em state externo.

const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
  useEffect(() => { /* 위의 fetch와 변환 */ }, []);
  return { paymentMethods };
};
 
export const Payment = ({ amount }: { amount: number }) => {
  const { paymentMethods } = usePaymentMethods();
  return (
    <div>
      <PaymentMethods paymentMethods={paymentMethods} />
      <button>${amount}</button>
    </div>
  );
};

O autor chama as duas operações de Extract Function, do catálogo de refatorações. É que em React o component também é uma função. O ponto importante é que nenhum conceito novo foi introduzido: apenas uma função foi dividida em duas.

Parece que acabou, mas ainda restam dois lugares. Dentro da view há a decisão "se for dinheiro, vem selecionado por padrão", e dentro do hook há uma função anônima que transforma a resposta no formato da tela. O autor chama esse vazamento de regras de negócio para a view e o hook de logic leak.

Regras reunidas em um domain object

O terceiro sinal é quando as decisões sobre os mesmos dados estão espalhadas entre a view e o hook. As decisões e conversões que vazaram são reunidas em uma única class PaymentMethod. É colocar a regra ao lado dos dados, como tratei em modelo de domínio aqui no blog.

class PaymentMethod {
  constructor(private remote: RemotePaymentMethod) {}
  get provider() { return this.remote.name; }
  get label() { return this.provider === "cash" ? "Pay in cash" : `Pay with ${this.provider}`; }
  get isDefaultMethod() { return this.provider === "cash"; }
}
 
const convertPaymentMethods = (methods: RemotePaymentMethod[]) =>
  methods.length === 0
    ? []
    : [...methods.map((m) => new PaymentMethod(m)), new PaymentMethod({ name: "cash" })];

O radio da view agora pergunta ao objeto com defaultChecked={method.isDefaultMethod}. O padrão de pagamento em dinheiro também é representado por uma instância da mesma class. Como o que veio do servidor e o que o app acrescentou passam a ter o mesmo formato, a view não precisa distinguir os dois.

O autor aponta como vantagem dessa estrutura que os testes ficam mais fáceis. O original para nessa frase, mas é mais rápido ver no código o quanto ficam mais fáceis. Abaixo estão testes que eu escrevi. Não há React, nem renderer, nem mock de fetch.

test("서버가 준 결제 수단 끝에 현금 결제를 기본값으로 붙인다", () => {
  const methods = convertPaymentMethods([{ name: "apple" }, { name: "google" }]);
 
  expect(methods.map((m) => m.label)).toEqual(["Pay with apple", "Pay with google", "Pay in cash"]);
  expect(methods.filter((m) => m.isDefaultMethod).map((m) => m.provider)).toEqual(["cash"]);
});
 
test("서버가 아무것도 주지 않으면 현금 결제도 보여 주지 않는다", () => {
  expect(convertPaymentMethods([])).toEqual([]);
});

Para verificar a mesma regra no código inicial, era preciso fazer render do component, interceptar o fetch e esperar os radios serem desenhados. No momento em que a regra sai para um objeto, o teste vira uma linha de chamada de função.

Outra vantagem é que, quando chega um requisito novo, já está definido para onde ele vai. A estrutura de arquivos neste ponto é esta.

src
├── components
│   ├── Payment.tsx
│   └── PaymentMethods.tsx
├── hooks
│   └── usePaymentMethods.ts
└── models
    └── PaymentMethod.ts

Só dá para saber se a estrutura aguenta de verdade quando chega um requisito novo. Aqui o autor acrescenta mais uma funcionalidade.

A funcionalidade de doação e o hook como state machine

O requisito novo é arredondar o valor do pedido para cima e permitir doar a diferença a uma instituição de caridade. Num pedido de 19,80 dólares, o app pergunta se o cliente quer doar 0,20 dólar e, se ele concordar, o botão mostra 20 dólares.

De propósito, o autor primeiro coloca o state de concordância e o cálculo dentro do component de pagamento. Com o markup da checkbox, a ramificação do texto e o cálculo do total entrando de uma vez, o component volta a ficar pesado. A ordem de limpeza é a mesma de antes. State e cálculo vão para o hook useRoundUp, a montagem do texto vai para uma função helper e o markup da checkbox vai para o component DonationCheckbox.

export const useRoundUp = (amount: number) => {
  const [agreeToDonate, setAgreeToDonate] = useState(false);
 
  const { total, tip } = useMemo(() => ({
    total: agreeToDonate ? Math.floor(amount + 1) : amount,
    tip: parseFloat((Math.floor(amount + 1) - amount).toPrecision(10)),
  }), [amount, agreeToDonate]);
 
  const updateAgreeToDonate = () => setAgreeToDonate((v) => !v);
  return { total, tip, agreeToDonate, updateAgreeToDonate };
};

O toPrecision(10) é um trecho cujo motivo o original não explica. Quando rodei no Node 24, 20 - 19.8 deu 0.1999999999999993. É um mecanismo para eliminar o erro de ponto flutuante.

O autor vê esse tipo de hook como "a state machine por trás da view". Quando chega um evento da UI, ele cria um state novo, e o state novo dispara outro render. Os hooks foram criados originalmente para vários components compartilharem logic, mas a posição do autor é que, mesmo com um único lugar usando, vale extrair, porque deixa o component focado no render. Acrescento uma coisa: como aponta Reusing Logic with Custom Hooks, da documentação oficial do React, o que um custom hook compartilha é a logic que lida com o state, não o state em si. Essa state machine nasce separadamente para cada component que chama o hook.

Terminada a limpeza, o component de pagamento chama dois hooks e enfileira dois subcomponents e um botão. Ganhou uma funcionalidade, e o papel do component de pagamento continua o mesmo.

Regras por país e shotgun surgery

O requisito seguinte é usar uma unidade de arredondamento diferente por país. No Japão, de 100 em 100 ienes. Na Dinamarca, de 10 em 10 coroas. O autor, dizendo que "parece uma correção fácil", mostra de propósito primeiro o caminho de receber o código do país como prop e enfiar ramificações.

// useRoundUp 안
total: agreeToDonate
  ? countryCode === "JP" ? Math.floor(amount / 100 + 1) * 100 : Math.floor(amount + 1)
  : amount,
 
// 체크박스 문구 helper 안
const currencySign = countryCode === "JP" ? "¥" : "$";
 
// 버튼 JSX 안
<button>{countryCode === "JP" ? "¥" : "$"}{total}</button>

A mesma decisão countryCode === "JP" entrou em três lugares: no hook, no helper e no botão. Acrescentando a Dinamarca, é preciso mexer de novo nos três, e quando o operador ternário não dá mais conta, surge uma tabela que busca o símbolo da moeda pelo código do país. Essa tabela, no fim, também acaba sendo consultada separadamente em vários lugares. Esse cheiro, em que uma única mudança obriga a mexer em vários módulos ao mesmo tempo, se chama shotgun surgery.

O que diferencia este estágio dos três anteriores é que o sinal não vem do código, e sim de um pedido de mudança. Olhando só o código atual, três ramificações não são difíceis de ler. O problema só aparece quando você conta quantos lugares precisa alterar para acrescentar mais um país. Então, para onde levar as ramificações espalhadas?

Diferenças por país reunidas em um Strategy

A resposta do autor é transformar a própria diferença entre países em um objeto. Primeiro, com Extract Class e Replace Conditional with Polymorphism, ele cria uma interface e uma implementação por país.

interface PaymentStrategy {
  getRoundUpAmount(amount: number): number;
  getTip(amount: number): number;
}
 
class PaymentStrategyAU implements PaymentStrategy { /* 1달러 단위 */ }
class PaymentStrategyJP implements PaymentStrategy { /* 100엔 단위 */ }

Depois de criadas, o que muda de uma implementação para outra são só duas coisas, o símbolo da moeda e a função de arredondamento, e o resto, como getTip, é idêntico. Por isso o autor junta as implementações em uma única class com Inline Class e recebe só as partes diferentes pelo construtor. Dá para receber o algoritmo de arredondamento como função, sem criar uma subclass por país, porque em JavaScript funções são valores. Abaixo está o resultado, que eu resumi.

class CountryPayment {
  constructor(readonly currencySign: string, private roundUp: (n: number) => number) {}
  getRoundUpAmount(n: number) { return this.roundUp(n); }
  getTip(n: number) { return parseFloat((this.getRoundUpAmount(n) - n).toPrecision(10)); }
}
 
const japan = new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100);
japan.getRoundUpAmount(3312); // 3400
japan.getTip(3312);           // 88

Hooks e components agora não sabem nada de país. Eles recebem esse único objeto e só usam strategy.getRoundUpAmount(amount) e strategy.currencySign. Para acrescentar um país, basta criar mais um objeto, e nenhum arquivo precisa ser alterado.

Passar por uma interface e depois juntar tudo de novo pode parecer um desvio desnecessário. Para mim, este é o trecho mais instrutivo do original. O polimorfismo não era o objetivo, e sim uma ferramenta para expor semelhanças e diferenças. Assim que ficou claro que a diferença se reduzia a uma função, a hierarquia de classes foi removida. Mais difícil do que introduzir um padrão é decidir quando removê-lo.

Tirando o fetch do hook

A última coisa a extrair é o fetch e a conversão dentro de usePaymentMethods. Hook é um conceito do React, então fica do lado da view. Colocando error handling e retry, o hook incha rápido, e se você migrar para outra view library, o hook não serve. Uma função comum, por outro lado, funciona em qualquer lugar.

const fetchPaymentMethods = async () => {
  const response = await fetch(`${API}/payment-methods?countryCode=AU`);
  return convertPaymentMethods(await response.json());
};
 
export const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<PaymentMethod[]>([]);
  useEffect(() => {
    fetchPaymentMethods().then(setPaymentMethods);
  }, []);
  return { paymentMethods };
};

O autor escreve que essa função funciona como uma Anti-Corruption Layer ou um Gateway. Ou seja, mesmo que a estrutura da resposta do servidor mude, o lugar a corrigir fica restrito a essa função. Só que os dois nomes não são a mesma coisa. O Gateway de Fowler é um objeto que encapsula num só lugar o acesso a um sistema externo, enquanto Anti-Corruption Layer é um termo do DDD de Eric Evans: uma fronteira que traduz um modelo externo, com outro sistema de significados, para que ele não contamine o seu modelo. A resposta do servidor neste exemplo é só { name }, então quase não há diferença de significado a traduzir, e por isso eu acho que Gateway é o nome mais preciso. Quando o servidor é um legado de outro time e o próprio significado de meio de pagamento é diferente, esse mesmo lugar vira uma Anti-Corruption Layer.

A estrutura final é esta. O render está no component, o state no hook, as regras no domain object e a requisição de rede em uma função.

O autor aponta cinco vantagens resultantes dessa divisão. Fica mais fácil achar onde está um defeito. Fica mais fácil reutilizar e combinar código. Fica mais fácil de ler. Acrescentar funcionalidades não abala o todo. E, como a domain logic não conhece a view, dá para trocar só a view layer. Sobre esta última, o próprio autor faz a ressalva de que, na maioria dos projetos, isso é muito raro. Também vale lembrar que nenhuma das cinco vem acompanhada de medições.

Até aqui é o enredo do original. Só que, rodando esse código de verdade, aparece o que não se via no texto.

O que aparece quando você roda o exemplo

Baixei o repositório de exemplo do autor (16 commits, último commit de186c5) e rodei tsc --noEmit e os 7 testes. Os dois passaram, e o helper cuja definição faltava no original também estava no src/utils.ts do repositório. Mas olhando a estrutura, havia três coisas que é preciso saber antes de copiá-la.

Um Strategy criado de novo a cada render

O component de pagamento recebe o Strategy como prop e, se ninguém passa, cria o valor padrão com new. E o useRoundUp coloca esse Strategy na dependency do useMemo.

export const Payment = ({
  amount,
  strategy = new PaymentStrategy("$", roundUpToNearestInteger),
}: { amount: number; strategy?: PaymentStrategy }) => {
  const { total, tip } = useRoundUp(amount, strategy); // 안에서 [agreeToDonate, amount, strategy]
  // ...
};

Os default parameters do JavaScript são avaliados a cada chamada. E o useMemo compara as dependencies com Object.is. Quando os dois se encontram, nasce uma instância nova a cada render e o memo recalcula toda vez. Fazendo render da mesma estrutura quatro vezes no React 18, o cálculo rodou 4 vezes usando o valor padrão e 1 vez passando a mesma instância. O App.tsx do repositório não passa Strategy (<Payment amount={19.9} />), então o caminho de execução do app é exatamente o do valor padrão.

O cálculo deste exemplo são algumas somas, então não há custo. O problema é a estrutura. Nem o texto nem o repositório definem quem cria o Strategy e onde, e só os testes criam instâncias do Japão e da Dinamarca. No meu lugar, eu deixaria as instâncias como constantes no nível do module e as passaria buscando pelo código do país.

const strategies = {
  AU: new CountryPayment("$", (n) => Math.floor(n + 1)),
  JP: new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100),
} as const;
 
<Payment amount={amount} strategy={strategies[countryCode]} />

O fetch do repositório não tem dependency array

O useEffect do código no original tem [], mas o usePaymentMethods do repositório não tem dependency array do primeiro ao último commit. Um effect sem array roda de novo a cada render. Quando a resposta chega, o state é trocado por um array novo, isso dispara um render e o effect faz fetch de novo. Como convertPaymentMethods devolve um array novo toda vez, isso não para.

Trocando o fetch por um mock que responde na hora e contando as chamadas por 300ms no Jest, medi quatro vezes e obtive 152, 225, 231 e 233 chamadas. Com [], é 1. Os testes do repositório só verificam se o texto aparece na tela, então não pegam essa repetição e passam todos. Quem digitou o código acompanhando o original não tem esse problema. Ele só aparece quando você baixa e usa o repositório como está.

A race que surge quando o código do país vira prop

O fetch effect do código original também não tem cleanup. Synchronizing with Effects, da documentação oficial do React, diz que, ao fazer fetch dentro de um effect, uma resposta anterior que chega atrasada pode sobrescrever a mais recente, então é preciso descartar a resposta anterior com uma flag ignore. O original faz fetch só uma vez, no mount, então por enquanto não há problema. Mas no momento em que o countryCode=AU da URL passa a vir de uma prop, surge uma dependency e a race se abre. Ao copiar essa estrutura, eu escreveria assim desde o começo.

useEffect(() => {
  let ignore = false;
  fetchPaymentMethods(countryCode).then((methods) => {
    if (!ignore) setPaymentMethods(methods);
  });
  return () => { ignore = true; };
}, [countryCode]);

Mais uma coisa: o arredondamento do original é Math.floor(amount + 1), então, se o valor já é inteiro, ele sobe mais 1. Um pedido de 20 dólares vira 21. O original só dá como exemplos 19,80 dólares e 3312 ienes, então não dá para saber se isso é intencional. Se for levar isso para um serviço real, a primeira coisa a decidir é em que isso difere de Math.ceil.

Quando usar essa estrutura

O próprio autor diz que dividir não é uma regra fixa. Components pequenos e coesos são mais fáceis de entender quando ficam em um único arquivo, e o que se deve evitar é um arquivo crescer a ponto de ficar incompreensível. Ele afirma que, num app de Todo ou num app de um único formulário, tudo bem colocar tudo no component, e que o exemplo foi complicado de propósito para mostrar muitos padrões. Outros materiais fazem ressalvas na mesma direção.

No mesmo texto sobre layering, Fowler diz para usar essa separação apenas em unidades relativamente pequenas. Ter view, model e data como pastas de nível superior tudo bem em sistemas pequenos, mas, se alguma delas crescer demais, o nível superior deve ser dividido por domínio e, dentro dele, por layer. Levar as pastas components/, hooks/ e models/ vistas acima como estão para a estrutura de nível superior de um app grande resulta justamente no formato que Fowler manda evitar.

Dan Abramov tem uma trajetória parecida. Em 2015, ele propôs dividir em presentational e container components e, em 2019, colocou no topo do texto uma atualização dizendo que não recomenda mais dividir assim. O motivo era que os Hooks fazem a mesma coisa sem uma divisão arbitrária, e ele acrescentou que tinha visto essa divisão ser imposta de forma dogmática, sem necessidade, vezes demais. A extração de hooks do original se aproxima do jeito que essa atualização descreve. Não existe um component separado chamado container: o Payment, que chama o hook, acumula esse papel.

Sobre fetch, a documentação oficial do React vai um passo além. You Might Not Need an Effect diz que extrair a fetch logic para um custom hook facilita migrar depois para uma estratégia melhor, mas recomenda em primeiro lugar o fetching embutido do framework ou um client cache como o TanStack Query. Se você extrai o fetch para uma função comum, como no último estágio do original, dá para passar essa função como está para o queryFn do TanStack Query, e a race e as chamadas repetidas da seção anterior ficam por conta da library. Para mim, esse é o ganho mais prático, que o original menciona em uma única frase. Como amarrar chaves e funções eu tratei à parte em queryKey.

Resumindo, minha avaliação é esta. A ordem do original (hook, pure component, domain object, Strategy, network client) vale ser seguida como está, porque em cada estágio o incômodo daquele estágio vira o motivo do seguinte. Mas não é preciso ir até o fim: basta ver de qual estágio é o incômodo que você sente agora e parar ali. Se há muito código sem relação com render, vá até o hook. Se a mesma decisão está espalhada, até o domain object. Se uma única mudança faz você mexer em vários arquivos, até o Strategy. E, se for usar Strategy, defina primeiro onde as instâncias são criadas. Se for deixar o fetch em um effect, escreva antes de tudo o cleanup e as dependencies. Essas duas coisas que o original omitiu foram os primeiros lugares a quebrar quando o código foi copiado de verdade.

Não existe resposta certa, mas espero que você, que está lendo, pare um momento para ver de qual estágio é o incômodo que o seu código está sentindo agora.

O primeiro uso que me chamou atenção foi a automação de navegador. A Browserbase abriu um PR que liga o Jev ao act() do Stagehand. A estrutura era mandar a árvore de acessibilidade da página como state e perguntar, com alternativas fechadas, "qual é o próximo elemento a clicar". Em 40 tarefas, a mediana do act() caiu de 1,97 segundo para 0,46, e de 147 ações só 4 voltaram para um LLM. O ponto onde um script de Playwright quebra assim que um selector muda foi preenchido por uma chamada que devolve uma única probabilidade. Enquanto escrevo, o PR ainda não foi mesclado.

A linha que esse PR traçou é a pergunta deste texto. Ele aceita a resposta do Jev a partir de uma probabilidade de 0,7 e, abaixo disso, repassa para um LLM. Dá para confiar na probabilidade que esse modelo devolve e traçar um limiar no código?

O benchmark dos outros não basta para decidir, então quero verificar com os meus próprios dados. Este blog tem um gate que barra estrangeirismos transliterados. A regra manda escrever 피커 como picker, mas a regex só pega a metade certa, e palavras que aparecem dentro de um composto ou já estão consolidadas em coreano, como 멀티스레드 ou 콜 스택, eu julgo à mão toda vez. Há só duas respostas, reverter ou manter, quem sabe decide em um segundo, e o passa ou falha precisa ser decidido dentro de um script de build sem ninguém conferindo. É o mesmo formato da decisão de selector do Stagehand.

Então a ordem é esta: o que o Jev devolve, de que treinamento sai essa probabilidade, que números aparecem quando entrego meu gate a ele e onde esses números podem ser usados.

Um modelo que não gera texto

A data de lançamento é 15 de setembro de 2026. A empresa não chama isso de LLM, mas de System One Model, uma categoria nova. Neste texto, chamo isso de modelos de decisão. O fundador, Diogo Almeida, foi o quarto autor do artigo do InstructGPT na OpenAI. Ele esteve no time que criou o método que se tornou o ancestral direto do ChatGPT e hoje está do lado que aponta os limites desse método.

O Jev não gera frases. Você define de antemão o formato da resposta, ele escolhe dentro dele e devolve a probabilidade junto. Só existem três tipos de pergunta.

O endpoint também é um só. Um POST /v1/systemone com state (o conteúdo a avaliar), model e questions (o mapa de perguntas) traz a resposta. Várias perguntas sobre o mesmo state cabem em uma requisição, e aumentar o número de perguntas quase não aumenta o tempo de resposta.

Por que é rápido se explica pela assimetria entre prefill e decode que organizei em o princípio dos tokens. O LLM é lento porque espreme a saída um token por vez, em sequência; o Jev não tem essa etapa de decode. Ele lê a entrada uma vez, em paralelo, e lê a probabilidade direto. Por isso não existe cobrança por token de saída: só a entrada, a $0.042 por milhão de tokens.

Há uma análise de um desenvolvedor chamado Archer Hume que chamou a API cerca de dez mil vezes e reconstruiu o comportamento de fora. Com 360 tokens de entrada, mediana de 57.5ms; com 29,835 tokens, 218ms; com 1,500 perguntas, 610ms. A evidência mais direta ali é a observação de que uma resposta com 200 alternativas voltou na mesma velocidade que uma com 2. Ou seja, escrever a resposta não custa tempo.

A decisão que ninguém vê

Velocidade e preço chamam atenção, mas a pergunta que Almeida lançou no texto de anúncio era outra: se os modelos são sobre-humanos em conversa há anos, para onde foi toda a automação?

A resposta dele é que são dois tipos de trabalho diferentes. Chatbots, copilots e agentes de código têm como objetivo satisfazer alguém que está olhando ao lado. A decisão que roda em silêncio no servidor, sem ninguém olhando, não. Se chamarmos a primeira de assistant e a segunda de automation, todos os modelos lançados até agora foram feitos para a primeira.

Fiz uma distinção parecida quando organizei o texto sobre design de harness. Dentro de um sistema de agentes há incontáveis decisões que ninguém observa. Passo esta requisição para uma pessoa? Posso executar este comando? Hoje perguntamos tudo isso a um LLM caro. A outra metade que a regex do meu gate não cobre também é uma decisão desse tipo.

O lugar que o RLHF deixou

Mas por que foi preciso um método de treino novo? Não dá para simplesmente pedir sim ou não a um modelo existente?

A pista está na calibração. Se acurácia é quantos por cento você acerta, calibração é saber quantos por cento você vai acertar, e o indicador que mede esse descompasso é o ECE (expected calibration error). É a média da diferença entre a probabilidade declarada e a taxa real de acerto em cada faixa de probabilidade, ponderada pela fração de amostras, então 0 é o valor perfeito. Só que há um caso em que essa escala saiu do lugar depois do RLHF (reinforcement learning from human feedback), que otimiza a preferência humana. Na Figure 8 do relatório técnico do GPT-4, o ECE do modelo pré-treinado era 0.007, e o do modelo pós-treinado, 0.074, mais de dez vezes pior. O relatório não aponta a causa, e eu também não encontrei uma fonte primária que a estabeleça. A definição e até onde a causa é conhecida estão explicadas à parte em Calibração e excesso de confiança em LLMs.

Só que o ECE sozinho não basta. Um preditor constante que estampa 0.6 em qualquer entrada também tem ECE 0 se a taxa real de acerto for 60%. Se a probabilidade é apenas honesta e não varia de caso para caso, não há onde traçar a linha. Por isso, além da calibração, é preciso olhar se a probabilidade de fato se separa, e a “fração que dá para tratar automaticamente dentro de um orçamento de erro”, que uso adiante, é o indicador que junta essas duas coisas num número só.

Do ponto de vista do software, o que importa é esta parte. Se a probabilidade é honesta e se separa, dá para traçar uma linha. Sai uma estrutura em que acima de 0.95 vai para o automático e abaixo disso vai para uma pessoa.

A TypeSafe diz ter aberto um terceiro caminho mirando esse lugar. O RLHF otimiza a preferência humana; o RLVR (reinforcement learning with verifiable rewards) otimiza respostas que a máquina consegue corrigir; e o RLCD, dizem, otimiza decisões calibradas.

Só que tudo o que foi divulgado sobre o RLCD são três linhas de contrato de saída. Até 23 de setembro de 2026, data em que escrevo este texto, não há artigo nem relatório técnico em lugar nenhum da documentação e do texto de anúncio da TypeSafe. Existe um artigo do ICLR 2024 que usa a mesma sigla, mas ali ela significa reinforcement learning from contrastive distillation, um método diferente. Cuidado para não misturar os dois na hora de pesquisar.

O que o confidence é de fato

Então o número que o Jev devolve é honesto? Antes de responder, há uma coisa a ver primeiro. Não é um número só.

As respostas de Choice e Score trazem probabilities e confidence juntos. O primeiro é a distribuição de probabilidade sobre todas as alternativas; o segundo é um único número entre 0 e 1. Na hora de pôr um limiar no código, a mão vai primeiro para o confidence.

Esse valor não foi feito pelo modelo. O arquivo _utils/confidence_metrics.py do system-one-adapter-python, publicado pela organização TypeSafe, tem 32 linhas ao todo, e a parte de Choice é esta.

def choice_confidence(probs: list[float]) -> float:
    """Scale peak choice probability from uniform to certainty."""
    if len(probs) == 1:
        return 1.0
 
    normalized_probs = _normalize(probs)
    uniform_probability = 1.0 / len(normalized_probs)
    return (max(normalized_probs) - uniform_probability) / (1.0 - uniform_probability)

Não há chamada de modelo nem parâmetro aprendido. Entra um vetor probabilities e sai um número real. Em fórmula, c = (p_max − 1/K) / (1 − 1/K); com três alternativas e probabilidade máxima de 0.8, dá 0.7.

Esse repositório não é o servidor Jev de produção, e sim uma implementação alternativa que imita a mesma API com um LLM. Então não dá para cravar nada só com isso. Mas há outras duas evidências apontando para a mesma fórmula. A página sobre confidence da documentação oficial da TypeSafe descreve o valor como "a statistic computed from the probability distribution" e, no código de demonstração, traz (3 × largest probability − 1) / 2 como aproximação para três alternativas. Com K igual a 3, é a mesma fórmula acima. E o registro de auditoria de afirmações anotou que, na API real, numa resposta em que só foram dadas duas alternativas, ambas erradas, quando o vencedor era 0.52 o confidence veio 0.04. Com K igual a 2, (0.52 − 0.5) / (1 − 0.5) = 0.04. Bate com a fórmula.

No mesmo repositório, Score usa uma fórmula completamente diferente: a distância absoluta média a partir do nível de moda, dividida pela mesma quantidade sob distribuição uniforme, e então subtraída de 1. A documentação não publica a fórmula do Score. Ou seja, sob o mesmo nome confidence existem duas fórmulas, e em tipos diferentes o mesmo número quer dizer coisas diferentes. Noul não ter confidence é pela mesma razão: não há distribuição para dobrar.

A documentação também não esconde isso. Chega a orientar que, se você quiser outro cálculo, ela entrega o probabilities inteiro para você fazer como preferir. É conteúdo que está escrito; o problema é quem usa sem ler.

Mas a tabela comparativa do texto de anúncio cola as duas coisas. Lá está escrito "Calibrated: higher confidence means higher accuracy". Quem lê entende que o confidence é o valor calibrado, mas o lado em que a afirmação de calibração de fato se apoia é o probabilities.

Quanto essa distinção abre em números, existe medição. Um desenvolvedor chamado scienthoon publicou uma medição independente de calibração que calculou à parte o ECE obtido ao ler o confidence como “probabilidade de estar certo”. Deu 0.035 no OpenBookQA, 0.078 no HellaSwag e 0.18 no conjunto sintético. As probabilidades originais dos mesmos conjuntos foram, respectivamente, 0.024, 0.029 e 0.107. Nos três conjuntos, o lado do confidence é pior.

Por que piora está na fórmula. Se K é fixo, c é uma transformação monotonicamente crescente de p_max, então a ordem é preservada. O poder discriminativo continua o mesmo; basta reescrever o limiar. O que quebra não é a informação, é a escala. Se K varia de pergunta para pergunta, surge mais um problema: o fator de esticamento também varia. O mesmo p_max de 0.8 vira 0.6 com duas alternativas e 0.75 com cinco. No momento em que você usa um único limiar numa carga de trabalho com número de alternativas misturado, isso vira problema.

A calibração muda conforme a distribuição

Então dá para confiar no lado do probabilities?

Existe um registro público de chamadas reais ao Jev. O repositório do Kev, implementação open source de reprodução feita por Jared Palmer, tem o diretório runs/jev-*, e o usage.json registra "model": "typesafe-ai/jev", atestando que foram chamadas reais passando pelo Vercel AI Gateway. Somando, nos seis diretórios jev-*, os arquivos usage.json, foram 5,364 chamadas entre 18 e 20 de setembro de 2026 e 2,418,260 tokens de entrada. Dos sete conjuntos abaixo, o scienthoon foi importado convertendo o arquivo de resultados daquele desenvolvedor, então não entra nessa soma.

Que a cobrança é de fato só pela entrada se confirma em outro lugar. O autor do benchmark de phishing anotou isso olhando o dashboard da TypeSafe. Dos 4.56 milhões de tokens de duas rodadas, 3.66 milhões foram de entrada e 0.9 milhão de saída, e a cobrança foi de $0.15, valor que bate com o cálculo feito só sobre a entrada.

Tirando do report.json do mesmo diretório os indicadores dos sete conjuntos de avaliação, fica assim. Abaixo, a certeza não é o campo confidence, e sim o valor máximo de probabilities. O excesso de certeza é 평균 확신도 − 정확도, isto é, a certeza média menos a acurácia, e são 5,743 casos no total. Os valores são os do bloco clean, que deixa fora da pontuação de acurácia os itens “desconhecidos”, cuja base de julgamento foi apagada.

Duas coisas se leem aqui.

Primeira, o ECE varia quase dez vezes. De 0.011 a 0.105. Mesmo corretor, mesmo modelo. “Ser calibrado” não é uma propriedade do modelo, mas da relação entre o modelo e a distribuição. Que a calibração desmorone quando a distribuição muda já é um resultado conhecido. O que há de novo aqui é que o mesmo padrão aparece num modelo que ergueu a calibração como objetivo de treino.

Os 0.105 do conjunto com maior ECE são até maiores que os 0.074 do GPT-4 pós-RLHF que vimos antes. Mas esses dois não devem ser lidos como um ranking. As tarefas são diferentes, e o ECE é um estimador cujo valor se move conforme o número de faixas em que você divide e conforme a faixa em que as amostras se concentram, de modo que confrontar números vindos de corretores diferentes não constitui comparação.

Segunda, o ECE medido é explicado quase inteiramente pelo excesso de certeza. A diferença entre as duas colunas fica entre 0.002 e 0.011 nos sete conjuntos. Como o ECE é a média ponderada das defasagens por faixa, ele não pode ser menor que o excesso global; essa diferença ser quase 0 significa que o sinal do desvio de cada faixa está todo inclinado para o mesmo lado. Não é ruído que se alterna entre faixas e se cancela.

Por que é assim se vê lendo na vertical. A certeza média, tirando o semif, tem seis valores grudados entre 0.851 e 0.906. No mesmo intervalo, a acurácia se move duas vezes mais largo, de 0.753 a 0.857. A certeza quase não se move quando a distribuição muda; só a acurácia se move. A diferença que sobra é o próprio ECE.

Como essa propriedade aparece na prática, outro benchmark mostra. Numa medição com 2,000 e-mails de phishing e o Claude Haiku 4.5 como grupo de controle, a acurácia do Jev foi 62.6% e a do Haiku, 81.3%. Mas o que mais chama atenção é o ECE. O ECE reportado pelo repositório é 0.154 para o Jev e 0.097 para o Haiku, e quando o registro de auditoria de afirmações remede o P(phishing) do Jev em 10 faixas de 0 a 1, dá 0.170. Lido de qualquer dos dois jeitos, o modelo que ergueu a calibração como objetivo de treino perdeu em calibração para um LLM feito com RLHF. O mesmo autor tirou 91.6% só com a regra da lista de hosts dos links.

Olhando o mesmo indicador em vários conjuntos, a amplitude fica ainda mais clara. A fração que dá para tratar automaticamente com orçamento de erro de 5% é 0.486 no conjunto scienthoon, 0.695 no transfer-v9 e 1.000 no semif. O corretor do Kev anota que esse valor é o máximo obtido escolhendo o limiar dentro da amostra, e não uma garantia de erro depois do deploy. Nenhum desses deve ser citado como se fosse a especificação do modelo.

O gate de detecção de transliteração

Ler o benchmark dos outros é diferente de medir nos meus dados. Então passei de verdade pelo gate da abertura.

Eu ainda não tenho uma chave de API do Jev. Em vez disso, rodei localmente o Kev-9B mencionado antes. É uma implementação de reprodução que põe um LoRA rank-16 e uma pointer head sobre o Qwen3.5-9B-Base, sob Apache-2.0. Os números abaixo não são números do Jev. Os dados de treino do Kev são tarefas de decisão em inglês, e na medição do próprio autor o Kev-9B fica atrás do Jev até em tarefas em inglês. A taxa de automação com orçamento de erro de 5% vai de 0.45 a 0.57, contra 0.70 do Jev, e no MMLU-Pro é 0.52 contra 0.84. Além disso, a documentação da TypeSafe também declara, sobre o Jev, que o inglês é a língua principal de treino e o CJK não está no mesmo nível.

O conjunto de avaliação saiu de 18 posts em coreano deste repositório. O critério de verdade dos rótulos é qual grafia este repositório usa de forma consistente para aquela palavra. Ou seja, não é o consenso da comunidade de documentação técnica em coreano, e sim o costume deste blog; nas palavras em que os dois divergem, o modelo pode estar certo pelo critério da comunidade e errado por este.

• Conjunto do gate, 102 frases: São palavras que o gate já conhece. Há 23 positivos, que são frases contrafactuais em que palavras escritas em inglês no texto original, como calendar, picker e adapter, foram revertidas para a transliteração coreana, e 79 negativos, que são frases em que de fato aparecem palavras marcadas como exceção pelo write-post.md, como 리렌더링 ou 콜 스택. Aqui o gate de regex atual acerta 100% por definição.
• Conjunto pendente, 60 frases: São palavras que o gate nunca viu. É o que em machine learning se chama conjunto held-out. Há 30 positivos, em que loader, mutation e prefill, que o texto só escreve em inglês, foram revertidos para transliteração, e 30 negativos com 리듀서, 스냅샷 e 런타임, que o texto só escreve em coreano. Aqui a regex não pega um único positivo.

Deixo claro desde já a assimetria de que os positivos são frases contrafactuais que eu mesmo construí e os negativos são frases reais. E a amostra efetiva não é o número de frases, e sim o número de palavras. Como o rótulo é definido por palavra, as frases que contêm a mesma palavra não são observações independentes. O conjunto do gate tem 24 tipos e o conjunto pendente, 13.

A tabela abaixo agrega apenas uma pergunta noul, a que pergunta “esta palavra deve ser revertida para o inglês?”. Coloquei quatro perguntas na mesma requisição, mas as outras três eram a forma negativa, uma variante em Choice e um julgamento sobre compostos cujos rótulos eu não consegui definir direito, então não as misturei aqui. A fração de automação com orçamento de 5% é a maior fração tal que, cortando de cima para baixo pela certeza, o erro da faixa acima do corte não passa de 5%.

O baseline da classe majoritária é a nota de quem não lê a frase e chuta sempre o rótulo mais frequente. O modelo está abaixo disso.

A última linha é a resposta deste experimento. No conjunto pendente, por mais alto que eu colocasse o limiar, não houve uma única decisão que desse para tratar automaticamente dentro de 5% de erro.

Olhando a distribuição das predições, aparece o que aconteceu. O modelo respondeu “deve ser revertida” a todas as 162 frases. A todos os 37 tipos de palavra. Todos os positivos certos, todos os negativos errados. Por isso o 0.500 do conjunto pendente não é competência: é o número que sai porque o conjunto está balanceado.

E, ainda assim, a certeza média foi 0.876. No conjunto do gate, 49% passaram de 0.9 de certeza, e o acerto real dessa faixa é 0.240.

A identidade estrutural também não se sustentou. Somando as probabilidades de “deve ser revertida” e “deve ficar como está”, a média no conjunto do gate deu 1.655, e todas as 102 frases se afastaram de 1 por mais de 0.1.

É assim por design. As duas perguntas são avaliações separadas que não leem uma à outra, e a própria TypeSafe publicou na página sobre jaggedness um exemplo em que refund 0.72 e not_refund 0.47 somam 1.19.

O ponto que pega na prática é este. Um limiar calibrado para Noul não deve ser transferido para Choice. As frases em que o julgamento é o mesmo mas a conclusão diverge foram de 14% a 17%.

Se fosse um modelo que diz sim a qualquer coisa, este resultado seria sem sentido. Comecei checando isso.

Ele lê coreano, diz “não” e separa 0.02 de 0.98. Não é um viés global de concordância. O que isso descarta vai só até aí. Continua de pé a possibilidade de que o enunciado da própria pergunta do gate seja ruim.

O resultado de pôr as regras no state

E se eu der diretamente o conhecimento necessário para distinguir? O método de adaptação de domínio que a documentação da TypeSafe recomenda é esse: sem tocar nos pesos, você manda material de referência dentro do state.

Peguei o parágrafo de regras que já está escrito no write-post.md, coloquei junto no state e rodei de novo. A entrada subiu de 100 tokens por frase para 450. O conjunto do gate é vazamento, porque esse material de referência lista pelo nome as palavras do gate e as palavras de exceção. Então aquele lado é um grupo de controle para ver “ele ao menos lê o material de referência?”, e o teste de verdade é o conjunto pendente.

A latência é inferência local rodada num M2 Max, então não está no mesmo eixo da latência de API do Jev vista antes. O que interessa aqui não é o valor absoluto, e sim o fator de 2.4 vezes ao incluir o material de referência.

No conjunto pendente, que é balanceado, a acurácia por frase foi de 0.500 para 0.500: não se moveu em nada. Por palavra, chegou a cair de 7/13 para 5/13.

O salto de 0.225 para 0.676 no conjunto do gate não é ganho de competência. Antes, ele dizia “reverter” para todas as 102 frases; com o material de referência, passou a responder isso em apenas 12. Os negativos subiram de 0/79 para 68/79, mas os positivos desabaram de 23/23 para 1/23. Como naquele conjunto os negativos são 79 contra 23, uma constante do tipo “em geral, deixe como está” recebe automaticamente uma nota mais alta. Não aprendeu a distinguir; mudou a inclinação.

Isso não quer dizer que o modelo não leia a frase. São as mesmas frases das mesmas palavras, e ao receber o material de referência as predições se espalharam frase a frase. O desvio padrão de 로더 foi de 0.096 para 0.217, e o de 뮤테이션, de 0.042 para 0.236. Ele lê, mas não consegue distinguir.

E este resultado também abala a interpretação da seção anterior. Se um único texto no state vira a saída inteira do avesso, o “reverte tudo” da primeira execução também pode não ser limite do modelo, e sim insuficiência do enunciado da pergunta. Este texto não conseguiu descartar essa possibilidade.

Uma coisa melhorou visivelmente. A soma das probabilidades de “reverter” e “deixar” no conjunto pendente se aproximou, de 1.508 para 0.963, e as frases muito afastadas de 1 caíram de 59 para 18. Só que a acurácia não se moveu. Uma coisa é as probabilidades das duas perguntas baterem entre si; outra é essas probabilidades estarem certas.

O lugar dos modelos de decisão

Chegando até aqui é fácil pender para a conclusão de que essa categoria inteira de modelo é inútil, mas pôr os benchmarks públicos lado a lado mostra que não é bem assim.

Só a linha de rerank é um indicador de qualidade de ranking de busca, então está num eixo diferente da acurácia das outras linhas.

Dentro da distribuição, a regex ou um classificador ajustado ganham ou empatam. É o mesmo lugar em que a regex ganhou por 1.000 a 0.225 no meu conjunto do gate. Se dá para juntar rótulos, treinar um modelo pequeno sai mais barato, mais rápido e mais preciso. Isso é o que já se faz há muito tempo.

A distância se abre quando a distribuição é nova e não há rótulos. No spam fora da distribuição, 98.6% contra 73.0%. O classificador ajustado desmorona diante de um formato que nunca viu, e este lado aguenta. O lugar dos modelos de decisão é a decisão para a qual não dá para juntar dados, rotular e treinar. É onde a situação é nova toda vez, os rótulos não se acumulam e mesmo assim a decisão precisa sair em segundos.

Por que a minha detecção de transliteração falhou também se explica por esse quadro. O que aquele julgamento exige não é raciocínio geral, e sim um conhecimento de domínio específico: que palavras se consolidaram na documentação técnica em coreano. Para uma implementação de reprodução de 9B treinada em tarefas de decisão em inglês, isso não está fora da distribuição: simplesmente não existe ali. É aí que está a razão de dar as regras por escrito também não ter funcionado.

Numa matéria do TechCrunch, Armin Ronacher, CTO da Earendil, que faz o harness Pi, disse o seguinte.

At the end of the day, it delegates the hallucination problem a little bit to the user.

Não é que a alucinação tenha sido eliminada: o julgamento foi passado para quem desenvolve. A documentação da TypeSafe também escreve que calibração é uma propriedade que vale para um conjunto de predições, e não uma garantia de que uma resposta individual está certa, e no item Nuance, abaixo da barra de 0% de alucinação do texto de anúncio, está escrito "Our number is not empirical". A forma é garantida; o conteúdo, não.

Os 194 projetos do jevable

Como nos meus dados o Jev falhou, fui ver onde as outras pessoas o estão usando. O jevable.com é uma curadoria independente montada por um desenvolvedor chamado Nikunj, que examina os projetos com Jev publicados no X e os reúne. Em 23 de setembro de 2026 eram 194, e as datas de registro se concentram entre 16 e 20 de setembro de 2026. 152 entraram num único dia, 18 de setembro. Três dias depois do lançamento.

Se, em vez de por categoria, reagrupamos por “o que se pergunta”, saem três formas. Os números abaixo são todos os que cada autor escreveu na própria publicação.

Primeira, classificação e roteamento. Classificar 1,500 e-mails, classificar documentos fiscais, classificar 1,891 anúncios de concorrentes em 19 segundos por $0.12, 14 typed checks num único diff de PR, detectar propaganda em notificações do Android, classificar 26 plantas de construção em 2.9 segundos. É a mesma forma do gate de transliteração do início. Como a tabela da seção anterior mostrou, é um lugar onde rótulos se acumulam todo dia, então, com o tempo, um classificador pequeno treinado nos próprios rótulos vence ou empata. A vantagem do Jev está no primeiro dia, quando ainda não há rótulos.

Segunda, loops de escolha de ação. Um browser agent acoplado ao Browser Use que terminou uma busca de passagens aéreas em 7 segundos por $0.0039, um computer use que controla o Mac por voz, um jogo que, cada vez que o Mario morre, faz fork da VM em quatro ramos e escolhe o que sobrevive, um motor de expressões faciais que decide dez coisas a cada mensagem, como boca, sobrancelhas e olhar de um personagem 3D. Como o action space muda a cada passo, não dá para juntar rótulos, e o julgamento precisa descer para abaixo de um segundo. É o mesmo lugar em que a diferença se abriu no spam fora da distribuição. Acho que é também por isso que Games, com 39, é a maior categoria. Jogo é um loop de escolha de ação em que errar pode ser desfeito.

Terceira, UIs que mostram a probabilidade ao usuário. O Ask Jev, que devolve só o veredito em vez de uma resposta; o JevForm, formulário ramificado que escolhe a próxima pergunta por probabilidade; o Upweight, que reordena a primeira página do Hacker News com seis sliders como profundidade técnica e drama. Como o limiar não fica cravado no código e é uma pessoa que lê a probabilidade, é onde a exigência de calibração que este texto questionou é mais baixa.

Uma coisa salta aos olhos. Das 194 descrições, 30 mencionam custo e 53 mencionam velocidade, mas só 7 mencionam acurácia ou uma linha de base. Como os resumos só trazem o começo de cada post, isso é um piso, mas a direção é clara. Que é rápido e barato dá para saber no primeiro dia; se está certo, só dá para saber medindo, e quem mede é raro. Um desses 7 é o jevcal. Partindo de que todo mundo escolhe o limiar no chute, é uma ferramenta que recebe os seus dados e a acurácia alvo e devolve o limiar e a fração de processamento automático. É exatamente o procedimento que a próxima seção recomenda, transformado em ferramenta.

Como traçar a linha

A conclusão deste texto é esta. Não leia a probabilidade que o modelo devolveu como se fosse especificação: meça você mesmo nos seus dados e trace a linha ali.

O procedimento para medir é este. Junte uns 100 casos rotulados, monte a tabela de taxa real de acerto por faixa de probabilidade e vá baixando o limiar de cima para baixo, olhando a taxa de erro da faixa acima dele. Se você definiu um orçamento de erro, a cobertura máxima que respeita esse orçamento é a fração que dá para automatizar. No meu experimento, que o acerto real da faixa acima de 0.9 de certeza fosse 0.240 apareceu com 102 frases.

Uma escala desalinhada quase sempre dá para consertar. Se o excesso de certeza está espalhado de forma uniforme por todas as faixas, uma única temperatura acerta a maior parte. Foi assim que o Kev baixou o ECE de 0.106 para 0.042. O problema é que ajustar essa temperatura exige os rótulos daquela distribuição, e é exatamente isso que não existe em produção. Além do mais, a temperatura não muda a ordem das probabilidades, então a fração automatizável não sobe na mesma medida. Por isso a ordem vale mais que a escala, e a cobertura dentro do orçamento de erro é um indicador mais prático que o ECE.

Se eu tivesse cravado no código o 0.9 que a documentação usa no exemplo, este gate teria corrigido 38 casos errados em silêncio. É uma falha difícil de perceber, porque não dá erro. A documentação da TypeSafe também escreve, logo abaixo daquele exemplo, que você deve testar nos seus próprios dados. O que acaba cravado no código costuma ser o número de cima, não a frase de baixo.

Mesmo sem a chave, medir já dá para começar hoje. O Kev está publicado sob Apache-2.0 e roda em um notebook.

Seria bom contar quantas chamadas, no serviço que você opera hoje, só perguntam sim ou não a um modelo grande. Antes de mover essas chamadas para um modelo de decisão, recomendo medir primeiro onde deve ficar a linha depois da mudança. Foi por ter seguido essa ordem que eu pude decidir não mexer no gate. Quando eu conseguir uma chave do Jev penso em rodar o mesmo conjunto de novo, e se a conclusão mudar eu escrevo isso também.

Eu gosto de código declarativo. Abrir um overlay, fechá-lo e fazer trabalho assíncrono dentro dele é uma sequência que, na minha opinião, o próprio overlay deveria gerenciar. Quando quem chama guarda isOpen e fica ligando e desligando esse valor, o código que lida com o estado acaba em um lugar diferente do componente que o desenha.

Só que os modais das telas pelas quais eu era responsável na empresa eram exatamente o contrário. Se um modal estava aberto ficava em uma store global, quem chamava abria e quem chamava fechava. Quem chamava também escrevia o código que fechava o modal e os callbacks que recebiam o resultado. Por isso passei bastante tempo pensando em como levar isso para uma direção declarativa e, no fim, reescrevi tudo.

Enquanto fazia esse trabalho, olhei o overlay-kit. Era próximo da interface que eu buscava. Este post registra a interface declarativa do overlay-kit e como projetei o sistema de modais interno.

O modal que eu guardava em estado

No meu post sobre gerenciamento de estado, usei a flag de abertura de um modal como o exemplo mais simples de estado local. Escrevi que é um estado usado dentro de um único componente, que o mundo externo não precisa nem tem o direito de conhecer. Continuo achando isso verdade. Mas assim que você tem dezenas de tipos de modal, eles se empilham uns sobre os outros e precisam devolver um valor para quem os chamou, esse estado não fica mais dentro do componente.

O código que herdei mantinha a lista de modais abertos em uma store global. Como é código da empresa, o exemplo abaixo preserva a estrutura e troca os identificadores.

const [openPopup, closePopup] = useModalStore(
  useShallow((state) => [state.openPopup, state.closePopup]),
);
 
const handleAddNote = useCallback(() => {
  openPopup(PopupType.ADD_NOTE, {
    itemId,
    onClose: () => closePopup(PopupType.ADD_NOTE),
    onSubmit: (note) => {
      closePopup(PopupType.ADD_NOTE);
      saveNote(note);
    },
  });
}, [closePopup, openPopup, itemId]);

Três coisas nesse código me incomodavam.

Primeira: a função que abre precisa sair de um hook. openPopup e closePopup são valores selecionados da store, então só é possível obtê-los dentro de um componente. Isso significa que o código que abre um modal não consegue sair do componente. Para abrir um modal em algum lugar onde não dá para usar hooks, como um interceptador de respostas da API ou um guard de rota, você precisa repassar essa função como argumento.

Segunda: o resultado volta por callbacks. Se a nota foi salva ou se a pessoa simplesmente fechou o diálogo chega por dois ramos distintos, onSubmit e onClose. Tudo o que você quiser fazer depois de abrir o modal vai para dentro de um callback. E se precisar abrir dois modais em sequência, surge um callback dentro de outro callback.

Terceira: fechar é responsabilidade de quem chama. É quem chama que invoca closePopup(PopupType.ADD_NOTE). O modal não se fecha sozinho: o lado que o abriu lembra de que tipo de modal se trata e o fecha. É por isso que a mesma constante aparece três vezes em uma só função.

O que as três têm em comum é que abrir um único modal obriga quem chama a escrever três tipos de código: o que abre, o callback que recebe o resultado e o que fecha.

Se decidir o que mostrar é tarefa de quem chama, aqui quem chamava carregava também tudo o que vinha depois. Em especial, closePopup(PopupType.ADD_NOTE) aponta o alvo com uma constante de texto. Escrever a constante de outro modal ainda passa na checagem de tipos porque pertence ao mesmo enum, e o modal errado é fechado.

Uma interface que espera um resultado

Então, qual dessas três dá para eliminar? A resposta a que cheguei foi transformar a abertura de um modal em uma chamada de função e fazer essa função devolver uma Promise com o resultado.

const result = await openModalAsync('ADD_NOTE', { itemId });
if (result.reason !== 'confirmed') return;
 
await saveNote(result.value);

Três coisas mudaram. A função que abre virou uma função de módulo em vez de um hook, então pode ser chamada fora de um componente. O resultado virou um valor de retorno em vez de um argumento de callback, então o trabalho seguinte permaneceu dentro do fluxo da função que chama. E fechar passou a ser tarefa do próprio componente do modal.

Como o tipo de retorno é Promise<ModalResult<V>>, o fim do modal se concentrou em um único valor.

Uma Promise termina apenas uma vez. Resolver uma Promise já resolvida não faz nada, então todos os motivos pelos quais um modal pode terminar precisam caber nesse único valor. Por isso dividi reason em cinco casos: a pessoa confirmou, a pessoa cancelou explicitamente, fechou sem valor, foi substituído por um modal novo do mesmo tipo, ou foi encerrado à força em uma limpeza geral. Com um único booleano, "cancelado" e "a tela inteira foi desmontada" viram o mesmo valor, e nos fluxos que precisam de limpeza é necessário distinguir esses dois casos.

Na direção oposta, se você nunca a encerra, quem chama espera para sempre. Nada acontece quando um callback não é chamado, mas um await simplesmente não retorna. Por isso, cada vez que surgia um novo caminho para remover um modal da tela, eu precisava verificar se aquele caminho também encerrava a Promise. A substituição e o encerramento forçado têm cada um o seu reason justamente por causa disso.

O ponto de chamada do overlay-kit

O ponto de chamada do overlay-kit, da toss, é assim.

const confirmed = await overlay.openAsync<boolean>(({ isOpen, close }) => (
  <ConfirmDialog
    open={isOpen}
    onConfirm={() => close(true)}
    onCancel={() => close(false)}
  />
));

Três pontos me pareceram uma boa interface.

O que abre está no ponto de chamada. A minha versão passa uma chave de texto, 'ADD_NOTE'. Qual componente essa chave representa é o arquivo de registry que sabe: um arquivo com um único objeto que associa cada chave de texto à função import() que carrega aquele modal.

export const modalImporters = {
  ADD_NOTE: () => import('.../add-note-modal'),
  CONFIRM: () => import('.../confirm-modal'),
  // 모달 종류만큼 이어진다
} as const;

O overlay-kit escreve o JSX ali mesmo. Quem lê o código sabe o que vai aparecer sem precisar ir até aquele arquivo.

O tipo do resultado é decidido no ponto de chamada. O argumento de tipo de openAsync<boolean> é ao mesmo tempo o tipo do argumento de close e o tipo do resultado do await. Não é preciso declarar um tipo de resultado por modal e registrá-lo em uma tabela.

Fechar e remover são coisas separadas. O controller recebe quatro props: overlayId, isOpen, close e unmount. close coloca isOpen em false e deixa o componente onde está. unmount é o que de fato o remove. O guia oficial sobre abrir e fechar overlays explica assim.

Essa diferença acontece porque, ao usar close, o overlay é mantido na memória para que a animação de fechamento possa ser exibida.

A minha versão não tem essa distinção. Ao fechar, sai da lista imediatamente. Isso significa que eu estava deixando as animações de fechamento a cargo da biblioteca de componentes e que só lidava com telas em que isso era possível.

De overlay.open até a renderização

Quando você gosta de uma interface, a pergunta seguinte é o que há dentro. Para uma única função de módulo desenhar um componente dentro da árvore do React, algo precisa ligar os dois lados.

Eventos e reducer

overlay.open não muda o estado. Ele emite um evento.

// packages/src/event.ts
const open = (controller: OverlayControllerComponent, options?: OpenOverlayOptions) => {
  const overlayId = options?.overlayId ?? randomId();
  const componentKey = randomId();
  const dispatchOpenEvent = createEvent('open');
 
  dispatchOpenEvent({ controller, overlayId, componentKey });
  return overlayId;
};

Quem recebe é o OverlayProvider. O provider guarda um useReducer, assina o evento e coloca ADD no reducer. O que merece atenção aqui é que isOpen entra como false.

// packages/src/context/provider/index.tsx
const [overlayState, overlayDispatch] = useReducer(overlayReducer, {
  current: null,
  overlayOrderList: [],
  overlayData: {},
});
 
const open: OverlayEvent['open'] = useCallback(({ controller, overlayId, componentKey }) => {
  overlayDispatch({
    type: 'ADD',
    overlay: { id: overlayId, componentKey, isOpen: false, isMounted: false, controller },
  });
}, []);

E, no frame seguinte à montagem do controller, ele despacha OPEN para colocar isOpen em true.

// packages/src/context/provider/content-overlay-controller.tsx
useEffect(() => {
  requestAnimationFrame(() => {
    overlayDispatch({ type: 'OPEN', overlayId });
  });
}, [overlayDispatch, overlayId]);

Aqui houve uma parte que não bateu com a minha expectativa.

O estado não fica fora do React. Como é uma API que abre por meio de uma função de módulo, imaginei que a store também estivesse no nível de módulo, mas na verdade é um useReducer dentro do provider. A única coisa fora do React é o barramento de eventos, e ele não guarda estado. Os overlays são renderizados como irmãos ao lado dos children do provider. Ele não usa createPortal nem importa react-dom.

Há mais uma coisa que chama atenção. Do ponto de chamada é uma linha só, overlay.open(), mas por dentro existe um procedimento de ordem fixa: emitir um evento, colocar ADD no reducer, esperar um frame e colocar OPEN de novo. Uma interface declarativa não elimina o código imperativo: ela o move para o outro lado de uma fronteira.

O lado que abre e o lado que fecha

O requestAnimationFrame que acabamos de ver e a separação entre close e unmount da seção anterior parecem coisas distintas à primeira vista. Na prática são dois mecanismos que tapam as duas pontas da mesma restrição.

Essa restrição é que uma transição CSS só roda quando tanto o estado inicial quanto o final são de fato renderizados. O guia de transições CSS da MDN alerta sobre elementos recém-adicionados ao DOM.

This is treated as if the initial state had never occurred and the element was always in its final state.

A falha aparece de duas formas. Ao abrir não existe estado inicial, então nada roda; ao fechar o elemento some antes de o estado final ser pintado, então também não roda.

A última linha explica por que o lado que fecha fica a cargo de quem usa. No lado que abre, a biblioteca conhece a constante: um frame basta. No lado que fecha, a biblioteca não tem como saber se a animação dura 200 ou 400 milissegundos.

O fechamento entregue como unmount

O que sustenta o lado que fecha está no reducer. CLOSE apenas inverte, dentro de overlayData, o valor isOpen, e não toca em overlayOrderList. O provider renderiza percorrendo essa lista, então o componente continua vivo enquanto permanecer nela. Ele só é desmontado quando REMOVE o tira de lá.

Dito isso, o rAF nem sempre é necessário. O react-transition-group não executa a transição de entrada na primeira montagem por padrão. Ele a pula mesmo quando in já é true, e é preciso ativar appear. O rAF do overlay-kit muda isOpen de false para true depois da montagem, o que cobre esse caso.

Vinte linhas embrulhadas em uma Promise

openAsync não é uma implementação à parte, e sim uma camada fina em volta de open.

// packages/src/event.ts
const openAsync = async <T>(controller: OverlayAsyncControllerComponent<T>, options?: OpenOverlayOptions) => {
  return new Promise<T>((_resolve, _reject) => {
    open((overlayProps, ...deprecatedLegacyContext) => {
      const close = (param: T) => {
        _resolve(param);
        overlayProps.close();
      };
      const reject = (reason?: unknown) => {
        _reject(reason);
        overlayProps.close();
      };
      const props: OverlayAsyncControllerProps<T> = { ...overlayProps, close, reject };
      return controller(props, ...deprecatedLegacyContext);
    }, options);
  });
};

Tudo o que ele faz é trocar o close que chega ao controller. O close original não recebe argumentos; este recebe um, resolve a Promise com ele e depois chama o close original. É também por isso que o tipo do resultado é decidido no ponto de chamada. T é ao mesmo tempo o tipo do argumento de close e o tipo da Promise.

Ainda assim, essa estrutura tem um buraco. A resolução só acontece quando close é chamado. Por isso, se você remover um overlay apenas com unmount, a Promise fica pendente para sempre. Está registrado na issue #169 e acho que precisa ser corrigido, mas a issue continua aberta.

O fato de a resolução acontecer em close tem outra implicação. É o momento em que o fechamento começa, não o momento em que a animação de fechamento termina. Isso não é problema em um fluxo que pede confirmação e depois chama uma API, mas em um fluxo que pede confirmação e depois abre o próximo modal, o segundo sobe enquanto o primeiro ainda está desaparecendo.

Onde o design deu uma volta completa

Segui o histórico de commits para explorar como o design chegou até aqui e descobri que a estrutura não foi assim desde o começo. A 1.0 usava a mesma combinação de eventos e reducer de hoje. A 1.2.0 moveu o estado para uma store externa no nível de módulo, lida com useSyncExternalStore, e a 1.8.0 devolveu tudo para um reducer.

O motivo da volta atrás está escrito na issue #148.

useSyncExternalStore resolves tearing issues, but it doesn't work well with suspense.

Quando buscar dados dentro de um overlay o fazia suspender, o React avisava que um componente havia suspendido enquanto respondia a uma entrada síncrona. O objetivo original de migrar para uma store externa era permitir ler o estado do overlay sem um hook, e o PR da época diz claramente que o objetivo não foi alcançado da forma pretendida. No fim o objetivo foi resolvido com um hook e apenas o mecanismo de armazenamento voltou ao lugar de origem.

O que levo desse registro não é uma conclusão, e sim um critério. Colocar o estado fora do React libera de onde você pode chamar as coisas, ao custo de abrir espaço para sair de compasso com o agendamento do React. O overlay-kit deixou de fora apenas o ponto de chamada e manteve o estado dentro.

Ao reabrir com o mesmo id

Algo me chamou atenção ao ler o reducer. Logo no começo de ADD existe este ramo.

// packages/src/context/reducer.ts
case 'ADD': {
  if (state.overlayData[action.overlay.id] != null && state.overlayData[action.overlay.id].isOpen === false) {
    const overlay = state.overlayData[action.overlay.id];
    if (overlay == null || overlay.isOpen) {
      return state;
    }
    return {
      ...state,
      current: action.overlay.id,
      overlayData: { ...state.overlayData, [action.overlay.id]: { ...overlay, isOpen: true } },
    };
  }
  // ...

Se você abre um overlay informando um overlayId, faz close e depois o abre de novo com o mesmo id, cai nesse ramo. Só que o valor de retorno reaproveita o objeto overlay existente.

Nada usa o action.overlay que acabou de chegar nem o controller dele.

Ler não foi suficiente para me convencer, então clonei o repositório da biblioteca e escrevi um teste. Preparei dois componentes que desenham conteúdos diferentes e os abri em ordem com o mesmo id.

const ControllerA = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">AAA</div> : null);
const ControllerB = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">BBB</div> : null);
 
overlay.open(ControllerA, { overlayId: 'id-close' });
overlay.close('id-close');
overlay.open(ControllerB, { overlayId: 'id-close' });

Estes foram os resultados, executados com vitest na branch main na versão 1.9.0 do overlay-kit.

A terceira linha é um comportamento que a documentação descreve como recurso, então saiu como o esperado. O problema é a primeira linha.

O JSX novo é ignorado

Aqui verifiquei mais uma coisa. Mais adiante, no mesmo reducer, há este comentário.

/**
 * @description Brings the overlay to the front when reopened after closing without unmounting.
 */
overlayOrderList: [...state.overlayOrderList.filter((item) => item !== action.overlay.id), action.overlay.id],

Ele diz que reabrir depois de fechar traz o overlay para a frente. Mas, como o ramo anterior chega antes ao return, essa linha não é executada nessa situação. Empilhei dois overlays, fiz close no de baixo, reabri, e a ordem do DOM não mudou.

Um comportamento que contradiz o comentário

Só que não verifiquei se isso aparece como um problema visível na tela. O teste olhou apenas a ordem do DOM e, como a maioria das bibliotecas de diálogo usa z-index próprio ou portais, a ordem do DOM não equivale à ordem visual.

A minha versão expõe essa mesma situação como uma opção. Ao reabrir um modal do mesmo tipo, quem chama escolhe entre manter o existente ou substituí-lo com props novas. Se escolher a substituição, a Promise existente termina como replaced. Essa é uma das razões pelas quais dividi antes o tipo do resultado em cinco ramos.

É aqui que os dois designs divergem. A minha abordagem trata modais como dados. Como a chave de texto e as props ficam em uma store, dá para substituí-los ou atualizá-los depois. O overlay-kit trata modais como funções. O controller é um closure, então, uma vez guardado, não há como mudar o conteúdo dele de fora.

O preço do JSX no ponto de chamada

Então, escrever JSX no ponto de chamada é sempre melhor do que usar uma chave de texto? Eu acho que não. Há três preços a pagar.

A divisão de código deixa de ser o padrão. Escrever JSX no ponto de chamada significa que quem chama importa aquele componente. Se o modal é uma tela de edição pesada e poucas pessoas apertam aquele botão, esse peso entra no bundle da tela de listagem.

React.lazy funciona dentro de um controller. Medi do mesmo jeito que no teste anterior: o módulo não era carregado antes do open e, ao abrir, o fallback do Suspense aparecia primeiro e depois o conteúdo era renderizado.

const Heavy = React.lazy(() => import('./HeavyModal'));
 
overlay.open(({ isOpen, close }) => isOpen ? (
  <Suspense fallback={<Spinner />}><Heavy onClose={close} /></Suspense>
) : null);

Ou seja, a diferença não está na possibilidade, e sim no padrão.

Na minha versão todos os valores do arquivo de registry são funções import(), então a divisão de código é imposta pela estrutura. Com o overlay-kit é preciso escrevê-la à mão em cada ponto de chamada.

Quem usa precisa decidir onde chamar unmount. Se você só chama close e para por aí, as informações do overlay ficam na memória. A documentação oficial alerta sobre isso e dá orientações separadas sobre onde prender unmount em cada design system. MUI e Mantine têm um callback para quando a transição termina, então basta prendê-lo ali, mas para bibliotecas sem esse callback a documentação manda colocar um timer com a duração da animação. O fato de essas orientações estarem divididas por biblioteca já é, em si, o custo dessa decisão.

Os overlays são renderizados onde está o provider. Como ele não usa portais, o mesmo código roda no React Native, o que é uma vantagem. Em contrapartida, o contexto fornecido abaixo do OverlayProvider não é visível dentro de um overlay. Ao abrir um modal que depende do contexto de rota ou de formulário, convém verificar esse ponto primeiro.

Até onde vai a palavra declarativo

Depois de escrever até aqui, uma coisa me incomoda. Comecei este post chamando essa interface de declarativa, e no entanto overlay.openAsync(...) é uma chamada de função por qualquer ângulo que se olhe.

Comecemos pela definição. A documentação do React traça a linha assim.

In React, you don't directly manipulate the UI--meaning you don't enable, disable, show, or hide components directly. Instead, you declare what you want to show, and React figures out how to update the UI.

A analogia do mesmo documento é mais nítida. O imperativo é ir cantando cada curva para quem dirige o carro; o declarativo é entrar em um táxi e dizer o destino.

Uma interface declarativa não elimina o procedimento imperativo: ela o move para o outro lado de uma fronteira e dá um nome a essa fronteira. O interior do overlay-kit que vimos é exatamente isso. O ponto de chamada tem uma linha, enquanto lá dentro roda um procedimento que emite um evento e faz dois dispatch.

Vejamos, então, onde cada projeto aplica a palavra. A documentação do overlay-kit chama a abordagem anterior de imperativa. O que ela aponta é o código que guarda a flag de abertura com useState e a inverte em um manipulador de eventos. O que ela chama de declarativo é o lado que trata o overlay como uma ação, e não como estado. O artigo sobre código declarativo do blog técnico da toss define a palavra de forma mais ampla: código declarativo é código com um nível de abstração mais alto, e um hook que abstrai a ação de exibir um overlay é um exemplo disso.

Por isso decidi estreitar a palavra assim: quem chama não escreve o código que fecha. Quando fechar, e o que permanece na tela enquanto fecha, quem decide é o overlay; quem chama escreve apenas o que mostrar e o que espera receber de volta.

Por esse critério, o código escrito com useState que guarda isOpen e o código que mantém uma lista de modais abertos em uma store global enquanto quem chama os fecha estão do mesmo lado. Muda só onde se guarda; nos dois, quem chama escreve a instrução de fechamento.

Para encerrar

O que eu corrigi no código da empresa não foi, no fim das contas, onde o estado ficava guardado. Foi quem escreve o código que fecha.

Mesmo quando usávamos uma store global, o estado já estava fora do componente, mas as instruções que abriam e fechavam continuavam no ponto de chamada. Só depois de trocar por um único await é que essas instruções entraram no modal.

O overlay-kit chegou ao mesmo lugar e deu mais um passo: ele coloca também no ponto de chamada o que será exibido. Acho que essa interface se lê bem. E, enquanto escrevia isto, descobri quanto custa esse passo.

Era a diferença entre tratar um modal como função e tratá-lo como dados. Escrever JSX no ponto de chamada transforma o controller em um closure, e o conteúdo de um closure não pode ser alterado de fora depois de guardado. É dessa estrutura que nasce o JSX ignorado ao reabrir com o mesmo id. Tratá-lo com uma chave de texto transforma o modal em um valor guardado em uma store que você pode substituir, atualizar e dividir em chunks, mas quem chama só chega a conhecer um nome.

Acho que a sensação de gostar da interface de uma biblioteca é um sinal bastante confiável. Ainda assim, vale a pena colocar em palavras pelo menos uma vez para o que exatamente essa sensação aponta. Sem fazer isso, você não consegue distinguir se o que agradou foi a interface ou a reputação de quem usa a biblioteca. Recomendo a quem estiver lendo fazer esse exercício uma vez com alguma biblioteca que esteja usando agora.

Precisei organizar esses conceitos primeiro enquanto testava as afirmações do Jev, um modelo de decisão lançado pela TypeSafe AI. Em vez de frases, o Jev devolve uma probabilidade para cada opção e apresenta a calibração como objetivo de treino. Para avaliar essa afirmação, eu precisava saber antes o que é calibração e por que ela sai do lugar nos modelos existentes.

Acurácia e calibração

Primeiro é preciso separar acurácia de calibração. Acurácia é quantos por cento você acerta; calibração é saber quantos por cento você vai acertar. Se, juntando só os dias em que a previsão disse 70% de chance de chuva, choveu de fato em sete de cada dez, aquela previsão está bem calibrada. Isso não quer dizer que a acurácia seja alta. Quer dizer que ela conhece o próprio limite. Um modelo que acerta só 60%, se disser de si mesmo que acerta 60%, tira nota máxima em calibração.

A escala pode sair do lugar em duas direções. Quando a probabilidade que o modelo declara é maior que a taxa real de acerto, isso se chama overconfidence; quando é menor, underconfidence. Pondo a probabilidade declarada no eixo horizontal e a taxa real de acerto de cada faixa de probabilidade no eixo vertical, dá para ver de relance onde as duas se separam. Um gráfico desenhado assim se chama reliability diagram.

Se a curva fica sobre a diagonal, o modelo acertou tanto quanto disse. Quanto mais ela cai abaixo da diagonal, menos ele acerta em relação à probabilidade que declara.

O indicador que mede esse descompasso é o ECE (expected calibration error). Pela definição de Guo et al. 2017, é a média, ponderada pela fração de amostras de cada faixa, da diferença entre “a probabilidade declarada” e “a taxa real de acerto” em cada faixa de probabilidade, e 0 é o valor perfeito. O código abaixo transcreve essa fórmula. Ele compara um modelo que acerta 6 de 10 questões quando diz 0.6 toda vez e quando diz 0.95 toda vez.

// Guo et al. 2017 의 식 (3). 구간은 등간격 10개(논문 실험은 15개), 경계는 왼쪽 닫힘
function ece(preds, M = 10) {
  const bins = Array.from({ length: M }, () => ({ n: 0, hit: 0, conf: 0 }))
  for (const { p, correct } of preds) {
    const b = bins[Math.min(M - 1, Math.floor(p * M))]
    b.n++
    b.hit += correct ? 1 : 0
    b.conf += p
  }
  return bins.reduce(
    (sum, b) => (b.n ? sum + (b.n / preds.length) * Math.abs(b.hit / b.n - b.conf / b.n) : sum),
    0,
  )
}
 
// 10문제 중 6문제를 맞힌다
const answers = Array.from({ length: 10 }, (_, i) => ({ correct: i < 6 }))
console.log(ece(answers.map((a) => ({ ...a, p: 0.6 }))).toFixed(3)) // 매번 0.6 이라고 말할 때
console.log(ece(answers.map((a) => ({ ...a, p: 0.95 }))).toFixed(3)) // 매번 0.95 라고 말할 때

Este é o resultado de rodá-lo com Node v24.16.0 em 2026-10-08.

0.000
0.350

A acurácia é 0.6 nos dois casos. Só a probabilidade declarada mudou, e mesmo assim o ECE sobe de 0 para 0.35. Mas como a fórmula usa valor absoluto, o ECE mede só o tamanho do descompasso, não a direção. Um modelo que diz 0.25 toda vez e ainda acerta 6 questões também fica com ECE de exatamente 0.35. Para saber se é overconfidence ou underconfidence, é preciso olhar o reliability diagram ou a confiança média menos a acurácia.

A função objetivo do RLHF

Então por que essa escala sai do lugar num modelo lapidado com feedback humano? Primeiro precisamos ver o que o RLHF (reinforcement learning from human feedback) otimiza. O esqueleto de construir um modelo de recompensa a partir de comparações de preferência humana veio de Christiano et al. 2017; um dos primeiros trabalhos a levá-lo para modelos de linguagem foi Ziegler et al. 2019, e o InstructGPT o aplicou ao seguimento de instruções. O que é empurrado para cima é a nota de um modelo de recompensa que imita a preferência humana. Os trabalhos com modelos de linguagem somam à recompensa uma KL penalty que impede o modelo de se afastar demais de como estava antes do aprendizado por reforço, e o InstructGPT ainda misturou gradientes dos dados de pré-treino (PPO-ptx), mas o que ele empurra para cima continua sendo essa nota.

Para um chatbot, a preferência humana é o objetivo certo. O problema é que essa preferência pende para evitar o tom que revela incerteza. Zhou et al. 2024 mostraram, em quatro conjuntos públicos de dados de preferência, que os anotadores escolhem menos as respostas com atenuadores como "I'm not sure, maybe". A diferença era pequena, mas significativa. Por outro lado, eles não escolheram mais as respostas com expressões que reforçam a certeza. Leng et al. 2025 mostraram que modelos de recompensa dão nota maior a respostas que declaram um número de confiança alto, independentemente da qualidade real. Os dois resultados tratam de expressões de confiança dentro do texto (verbalized confidence), não de probabilidades de tokens. A TypeSafe, que propõe um método de treino para substituir o RLHF, também observa no seu próprio guia introdutório que o RLHF pode recompensar alucinações que soam confiantes (confident-sounding hallucinations). É a posição de quem vende a alternativa.

As curvas de calibração do GPT-4

Nas probabilidades dos tokens também se observou um descompasso na mesma direção. A Figure 8 do corpo do relatório técnico do GPT-4 coloca lado a lado os reliability diagrams do modelo pré-treinado e do modelo post-training, e a legenda diz:

Right: Calibration plot of the post-trained GPT-4 model on the same subset of MMLU. The post-training hurts calibration significantly.

O eixo horizontal é a probabilidade (logprob) que o modelo atribuiu a cada uma das alternativas A, B, C e D em questões de múltipla escolha do MMLU, e o eixo vertical é a taxa real de acerto naquela faixa. Pelos números impressos na Figure 8, o ECE do modelo pré-treinado é 0.007 e o do modelo que passou por PPO (o algoritmo de aprendizado por reforço usado no RLHF para atualizar o modelo na direção de notas mais altas do modelo de recompensa) é 0.074. Piorou mais de dez vezes.

No painel direito (PPO) da Figure 8, as barras de 0.4 para cima ficam abaixo da diagonal, mas as faixas entre 0.1 e 0.3 ficam, ao contrário, acima dela. As barras entre 0.1 e 0.9 se amontoam planas numa taxa real de acerto de cerca de 0.3 a 0.5, então, mesmo que a probabilidade que o modelo declara suba, a taxa de acerto quase não acompanha. No 0.074 também estão misturadas essas faixas de underconfidence. E, como Guo et al. apontam, um reliability diagram não mostra quantas amostras caem em cada faixa, de modo que não dá para supor que a distância de uma barra até a diagonal seja proporcional ao quanto aquela faixa contribui para o ECE.

Este painel difere do diagrama conceitual acima em dois pontos. Primeiro, não apenas cai abaixo da diagonal como a curva do diagrama conceitual, mas a cruza uma vez. Segundo, coloca nas faixas as probabilidades das quatro alternativas, então também difere da definição do código acima, que mede a probabilidade da única resposta escolhida. Por isso não comparo o 0.074 com o 0.35 do código acima na mesma escala.

Então por que piorou? O corpo do relatório diz apenas que o modelo pré-treinado estava bem calibrado e que a calibração diminuiu depois do post-training; não aponta uma causa. Uma pista está em Kadavath et al. 2022, da Anthropic. As políticas RLHF que eles treinaram a partir dos próprios modelos de linguagem pareciam, à primeira vista, muito mal calibradas. O artigo disse que isso não surpreendia, porque o RL fine-tuning tende a concentrar as previsões nos comportamentos que recebem mais recompensa. Foi um experimento curto acrescentado à margem, não o tema central. Ainda assim, ao aplicar uma única temperatura, T=2.5, a todas as avaliações, os problemas de calibração foram em grande parte resolvidos em três avaliações. A temperatura é um valor que divide os logits; quando é maior que 1, mantém a ordem das respostas e só achata a distribuição de probabilidade. Eu leio o fato de um único valor ter resolvido em grande parte o problema como sinal de que o descompasso não estava concentrado em poucas faixas, e sim era a distribuição inteira estreitada para um lado. O artigo também acrescentou a ressalva de que um treino de RL mais intenso poderia distorcer a calibração de formas que não se corrigem assim.

Esse é um resultado sobre modelos da Anthropic, então não dá para transportá-lo diretamente como causa da Figure 8. Os estudos da seção anterior também tratavam de expressões de confiança dentro do texto. Não encontrei uma fonte primária que ligue diretamente o resultado de que as pessoas evitam o tom incerto ao descompasso nas probabilidades dos tokens.

A probabilidade que seu código recebe

A probabilidade da Figure 8 é a log-probabilidade de um token. Para receber um valor do mesmo tipo, conforme a especificação da API da OpenAI, você define logprobs como true numa requisição de Chat Completions e usa top_logprobs para escolher, entre 0 e 20, quantos candidatos receber em cada posição de token. O valor que você obtém pedindo ao modelo que diga um número de confiança junto com a resposta é confiança expressa em palavras, e é um valor diferente da probabilidade do token.

Os estudos sobre esses dois valores comparam pares diferentes. Tian et al. 2023 relataram que, dentro de modelos RLHF como ChatGPT, GPT-4 e Claude, a confiança expressa em palavras costumava ser mais bem calibrada que as probabilidades condicionais, muitas vezes reduzindo o ECE em cerca de 50% relativo em três benchmarks. Mas, nessa comparação, a probabilidade condicional dos modelos cujos pesos não são públicos não era a probabilidade de tokens da API, e sim uma estimativa: a fração de vezes que a resposta saiu ao amostrar a mesma pergunta 10 vezes. Leng et al., vistos acima, relataram que, comparados a modelos anteriores ao RLHF, os modelos RLHF mostram mais overconfidence na confiança que expressam em palavras. Os dois resultados podem valer ao mesmo tempo. E 0.074 é o valor que o modelo post-training do GPT-4 de 2023 obteve num subconjunto do MMLU, então não dá para transportá-lo como está para os modelos que você chama hoje pela API.

Para fechar

Resumindo, calibração não é sobre quantos por cento você acerta, e sim sobre saber quantos por cento vai acertar, e o ECE é o número que mede o tamanho desse descompasso. Para ver a direção, é preciso olhar o reliability diagram ou a confiança média menos a acurácia. O RLHF empurra para cima a nota de um modelo de recompensa que imita a preferência humana. Kadavath et al. entendem que essa otimização tende a estreitar as previsões na direção do que recebe mais recompensa. Há pesquisas mostrando que as pessoas escolhem menos as respostas que revelam incerteza e que modelos de recompensa dão nota maior a respostas que declaram um número de confiança alto, independentemente da qualidade. No GPT-4, o ECE ficou registrado indo de 0.007 para 0.074 depois do post-training, mas a OpenAI não chegou a escrever a causa. Como a calibração também sai diferente conforme a probabilidade que o seu código recebe seja uma probabilidade de tokens ou uma confiança dita em palavras, seja qual for, você precisa medi-la de novo nos seus próprios dados.

Se as probabilidades do Jev, um modelo de decisão que apresenta a calibração como objetivo de treino, são de fato honestas é o tema de Modelos de decisão, Jev e Kev.

Espero que você também, antes de cravar no código como limiar a probabilidade que um modelo devolve, verifique ao menos uma vez com que objetivo esse modelo foi treinado e se a escala dele se sustenta nos seus próprios dados.

Enquanto desenvolvo, dedico tanto tempo a descobrir o que precisa ser construído quanto a escrever código. Troco requisitos com o product manager, alinho telas com o designer e pergunto a quem conhece o domínio o que cada termo significa. E já vivi algumas vezes que o custo de esse processo sair do lugar é muito maior do que o custo de escrever o código errado.

Recentemente li As atividades cotidianas de um líder de engenharia, escrito por James Samuel. O autor divide o trabalho de um líder em seis frentes, e a primeira que ele trata é a coleta de informação. A razão é que toda decisão, toda direção e toda ação dependem de um entendimento preciso do que está acontecendo agora.

Eu quero assumir um papel de liderança algum dia, mas o que me ocorreu ao ler essa passagem foi um pouco diferente. Se a primeira coisa que um líder trata é coletar informação, o correspondente disso para quem está na execução é entender requisitos. O jeito como lido com requisitos hoje será o jeito como vou lidar com a informação de uma organização depois.

Não é minha intenção falar de liderança neste texto. Falo do que eu vinha fazendo errado ao me comunicar com outras áreas na posição em que estou e do que posso usar como ferramenta. Começando pela conclusão: passei a achar que esse problema não é só uma questão de atitude. Existe uma formulação alternativa disponível, chamada ubiquitous language, e vale a pena ver do que se trata.

A mesma palavra, significados diferentes

No artigo sobre Bounded Context, Martin Fowler dá o exemplo de uma companhia elétrica. Boa parte dos desalinhamentos que vivi tinha esse formato.

Aqui a palavra “meter” significava coisas sutilmente diferentes em partes distintas da organização: era a conexão entre a rede e um local, entre a rede e um cliente, ou o medidor físico em si?

here the word 'meter' meant subtly different things to different parts of the organization: was it the connection between the grid and a location, the grid and a customer, the physical meter itself

A mesma palavra, “meter”, significava coisas sutilmente diferentes conforme a área da organização. E Fowler acrescenta que essa confusão não é um acaso daquele caso específico: diz ter visto a mesma confusão se repetir com palavras polissêmicas como Customer e Product.

Isso não aconteceu porque os participantes eram ruins de reunião. Quando uma organização contém contextos diferentes, é natural que a mesma palavra se divida, e deixar isso correr acaba dividindo também o código.

O pano de fundo técnico dessa história eu tratei uma vez em Modelo de domínio. Naquele texto falei de como expressar o modelo dentro do código. Neste, trato da etapa anterior à existência desse modelo, a da conversa entre pessoas.

Uma palavra com dois significados

Mas por que isso se repete de forma estrutural? Há duas linhas de explicação.

Uma vem da estrutura organizacional. O artigo How Do Committees Invent?, que Mel Conway publicou na Datamation em 1968, afirma que, na medida em que uma organização não consegue mudar com flexibilidade sua estrutura de comunicação, essa organização carimba a própria imagem em todos os artefatos de design que produz. A frase única normalmente citada como lei de Conway é, na verdade, uma formulação que o próprio autor elaborou mais tarde, e essa descrição do texto de 1968 me parece mais direta.

O que li em chave prática nessa frase é a expressão “carimba”. Significa que a divisão dos termos não termina na conversa, mas permanece nos artefatos. O “meter” acima é exatamente isso. Se cada um constrói mantendo um entendimento diferente do escopo de “meter”, essa diferença não fica na ata da reunião, e sim nos nomes de tabela, nos campos da resposta da API e nos textos da tela. E a partir daí o custo de corrigir não tem comparação com o custo de ter mais uma conversa.

É aqui que se separa o que quem está na execução pode e não pode fazer. Mudar a estrutura de comunicação da organização foge ao alcance de quem executa. Mas tornar visíveis as fronteiras dos termos é possível a partir do lugar em que você está hoje. Consiste em anotar qual é o escopo de uma palavra neste documento e explicitar quando ela difere da palavra usada por outro time. Todas as ferramentas que veremos adiante são dispositivos que facilitam esse trabalho.

A outra explicação é um pouco mais fundamental. Do ponto de vista da ciência cognitiva, a colaboração só se sustenta sobre um pano de fundo compartilhado. Grounding in Communication, escrito por Herbert Clark e Susan Brennan em 1991, começa com o exemplo de um dueto de piano. Os dois instrumentistas não conseguem nem começar a se coordenar sem pressupor uma quantidade enorme de informação compartilhada, ou seja, common ground. Aqui common ground significa conhecimento mútuo, crenças mútuas e pressupostos mútuos. E os autores afirmam com firmeza que toda ação coletiva é construída sobre o common ground e sobre seu acúmulo.

A perspectiva a que cheguei depois de colocar essas duas linhas lado a lado é esta. Os termos divergirem não é acidente, é o estado padrão. Estar alinhado é a exceção, o estado que precisa ser mantido a um custo. Então a pergunta prática passa a ser quem paga esse custo e como.

Vigilância ativa

Em Domain-Driven Design, publicado em 2003, Evans apresenta um padrão chamado ubiquitous language, ou linguagem compartilhada. Costuma ser resumido como pouco mais que “developers e especialistas de domínio devem usar os mesmos termos”, mas, lendo o livro original, a prescrição é bem mais concreta. Ele pede que o time tome o modelo como espinha dorsal da linguagem e se comprometa a usar essa linguagem de forma persistente em toda a comunicação do time e no código. E a frase que vem em seguida foi a mais importante para mim.

Os especialistas de domínio contestam termos ou estruturas que sejam desajeitados ou inadequados para transmitir o entendimento do domínio, enquanto os developers ficam atentos a ambiguidades ou inconsistências que vão derrubar o design.

Domain experts object to terms or structures that are awkward or inadequate to convey domain understanding, while developers watch for ambiguity or inconsistency that will trip up design.

Os especialistas de domínio contestam termos e estruturas desajeitados ou insuficientes para transmitir o entendimento do domínio, e os developers vigiam a ambiguidade ou inconsistência que vai derrubar o design.

Ao ler essa frase, corrigi meu entendimento do próprio papel. Até então eu me via como receptor nas reuniões de requisitos. Achava que meu trabalho era receber com exatidão o que o produto decidisse e implementar. Mas a parte que Evans atribui ao developer não era a recepção. É encontrar a ambiguidade e devolvê-la. Isso não é cooperação passiva, é vigilância ativa.

(A propósito, Fowler traduziu essa frase no próprio artigo como “Domain experts should object ... developers should watch”. O livro original não tem verbo modal. É uma diferença pequena, mas o original se lê de forma mais categórica: o tom não é que seria bom fazer assim, e sim que fazer assim é a definição do padrão.)

Então como se encontra a ambiguidade? Evans também responde: usar os termos repetidamente na conversa é o que revela as diferenças de interpretação. Eu li essa frase assim. A ambiguidade não é algo que se acha lendo documentos com lupa. Por mais cuidadosa que seja a leitura de uma especificação, o fato de “meter” ter vários significados não aparece. Essa palavra precisa ser usada repetidamente contra casos concretos para se dividir. O momento em que surge uma pergunta como “o que as outras pessoas entendem por meter?” é exatamente esse ponto.

O princípio do mínimo esforço colaborativo

Podemos conhecer esse método e ainda assim não praticá-lo. Então por que não perguntamos repetidamente?

Voltemos ao artigo de Clark e Brennan. Os autores dão o nome de grounding ao processo de transformar o que foi dito em parte do common ground. E propõem um princípio sobre como as pessoas se comportam nesse processo: o princípio do mínimo esforço colaborativo (the principle of least collaborative effort). Ele nasce da observação de que as pessoas não gostam de trabalhar mais do que o necessário.

Aqui vem a passagem importante.

Pelo princípio do mínimo esforço colaborativo, as pessoas deveriam tentar fazer grounding com o menor esforço conjunto necessário. Mas o que exige esforço muda dramaticamente conforme o meio de comunicação.

By the principle of least collaborative effort, people should try to ground with as little combined effort as needed. But what takes effort changes dramatically with the communication medium.

O ponto em que o esforço recai muda dramaticamente conforme o meio. Uma técnica de confirmação disponível em um meio pode ser simplesmente impossível em outro ou, sendo possível, muito mais cara. Os autores apontam em especial que, em meios nos quais o interlocutor não recebe o que foi dito de imediato, o custo de contar que outra pessoa corrija o mal-entendido fica muito alto, então quem fala tende a evitá-lo.

Vale registrar uma coisa aqui. Esse artigo foi escrito em 1991, e os meios comparados pelos autores são a conversa presencial, o telefone, cartas e secretária eletrônica. Ele não trata de Slack nem de Notion. O arcabouço de que o custo de grounding varia conforme o meio é dos autores; aplicá-lo aos canais de trabalho assíncronos de hoje é interpretação minha.

Aplicando assim, fica explicado por que eu não perguntava repetidamente. Num ambiente em que você recebe a especificação como texto e confirma como texto, mandar uma mensagem de confirmação a cada ponto ambíguo é caro. Você não sabe quando virá a resposta e teme que perguntar várias vezes faça você parecer alguém que não entendeu. Então a pessoa naturalmente escorrega para a própria interpretação.

Convém separar duas forças aqui. Uma é que o meio encarece a confirmação, e isso é o que dizem Clark e Brennan. A outra é o receio de parecer incompetente por perguntar várias vezes, e isso não é o que o princípio deles prevê, mas pertence à discussão sobre segurança psicológica que vem adiante. Com precisão: o que o princípio do mínimo esforço colaborativo prevê é que você escolherá um jeito mais barato de confirmar, não que deixará de confirmar. Abandonar a confirmação e partir para o palpite não é o princípio operando, é o grounding falhando. E o fato de que aquela interpretação estava errada aparece só depois que a implementação termina.

Chegar a um nível suficiente

Então é preciso perguntar sobre cada ambiguidade? Não é realista, e nunca vi ninguém fazer isso. O artigo também oferece um critério para essa pergunta: o grounding criterion. Ele designa o estado em que ambas as partes acreditam mutuamente que o ouvinte entendeu o que o falante quis dizer num nível suficiente para o propósito atual. Os autores o antecedem com a observação de que a compreensão perfeita é impossível desde o início.

O motivo de esse critério ter me parecido prático é que ele baixa a meta. Não é preciso entender os requisitos perfeitamente. Basta poder confiar mutuamente que vocês se entendem o suficiente para o que estão prestes a fazer. E os autores dizem que, se o propósito muda, o critério precisa mudar junto.

Na prática, isso vira o critério para calibrar a intensidade da confirmação. Se numa sessão que ainda explora direção você fica preso em “o que meter significa aqui?”, a conversa não anda. O que se precisa nessa etapa é acordo sobre o que se quer fazer e por quê, não a definição dos valores de fronteira. Ao contrário, pouco antes de entrar na implementação essa pergunta tem obrigatoriamente que surgir. Aí é preciso poder confiar que os dois lados estão imaginando o mesmo escopo para “meter”; se não, o código se acumula sobre uma premissa errada.

Por isso, diante da mesma ambiguidade, eu a trato de forma diferente conforme a etapa em que estou. Na etapa de exploração eu anoto numa lista e sigo; pouco antes de implementar eu abro essa lista e fecho os itens um a um. Adiar a confirmação e abandonar a confirmação são coisas distintas.

Há uma ferramenta que combina bem neste ponto. Team Topologies, de Matthew Skelton e Manuel Pais, distingue três modos de interação entre times: collaboration, quando por um período definido se descobre algo novo em conjunto; X-as-a-Service, quando um lado provê e o outro consome; e facilitation, quando um lado ajuda e mentora o outro.

Na origem é uma discussão sobre design organizacional, mas achei prático reduzi-la à escala de uma reunião. Se cada um acredita que esta conversa está num modo diferente, a reunião sai dos trilhos. Se o product manager acha que é uma sessão para comunicar o que já foi decidido enquanto o developer acha que é uma sessão para descobrir junto, as perguntas do developer soam como implicância, não como colaboração. O contrário também acontece. Se o developer veio receber uma especificação fechada e o product manager ainda estava explorando, o developer se frustra porque não há especificação.

Por isso, ultimamente eu confirmo isso logo no começo da reunião: “isto ainda está aberto ou é uma sessão para confirmar o que já foi decidido?”. Essa única pergunta muda o caráter de tudo o que vem depois. É a mesma coisa que ajustar o grounding criterion ao propósito.

Quando a resolução não bate, a conversa gira em falso

Mesmo com o modo alinhado, um problema permanece. Outro desalinhamento que vivi com frequência foi falar em resoluções diferentes.

Requisitos entregues em prosa pelo product manager costumam ser abstratos demais. De uma frase como “para que o usuário consiga conferir com facilidade o histórico de reservas” não se extrai quantas telas existem nem o que leva a onde. Ao contrário, o layout do designer é concreto demais. Cor de botão e espaçamento já estão definidos, o que torna difícil discutir justamente se este fluxo está certo.

Shape Up, escrito por Ryan Singer na Basecamp, aponta esse problema com precisão: começar por wireframes ou layouts visuais concretos prende você em detalhes desnecessários e impede explorar tão amplamente quanto é preciso. Por isso o que Shape Up propõe é uma representação intermediária. Chama-se breadboarding e toma o conceito emprestado da engenharia elétrica. Um breadboard é um protótipo que tem todas as peças e a fiação do aparelho real, mas nenhum design industrial. Por isso se desenham exatamente três coisas: os lugares para onde se pode navegar (places), aquilo que o usuário pode acionar (affordances) e as linhas de conexão que mostram para onde essa ação leva o usuário (connection lines).

O motivo de eu ter gostado dessa técnica é que ela é um artefato que o developer consegue produzir. Em vez de pedir ao product manager que escreva com mais detalhe ou de esperar o layout do designer, você desenha ali mesmo o fluxo como o entendeu e devolve com um “entendi assim, está certo?”. É um jeito concreto de executar a vigilância de que Evans falava, a de devolver a ambiguidade. E, pela lente da seção anterior, é um dispositivo que barateia o grounding. Um desenho substitui várias rodadas de confirmação por texto.

Mas essa resolução é mais difícil de sustentar do que parece. Ao desenhar o fluxo, você desce naturalmente para coisas como “não seria melhor colocar este botão embaixo à direita?”. Comigo aconteceu algumas vezes. Uma vez que você desce assim, a pergunta que estava em discussão, ou seja, se este fluxo está certo, some em silêncio. Se você define a posição dos botões enquanto o fluxo ainda não está fechado, toda aquela discussão é jogada fora por inteiro quando o fluxo mudar depois.

Por isso, nesta etapa, tento manter um desenho deliberadamente ruim. Se há apenas retângulos, setas e nomes, a outra pessoa nem cogita apontar detalhes e responde só ao fluxo. O baixo acabamento do desenho é, nesta ferramenta, uma funcionalidade. (Segurar a vontade de desenhar bonito é mais difícil do que parece)

Que o próprio nível de abstração possa ser uma ferramenta de colaboração se conecta ao que tratei em Abstração. Lá eu falava do nível de abstração do código; na conversa existe a mesma coisa.

Separar regras, exemplos e perguntas

Outra maneira de alinhar a resolução é estruturar a própria discussão.

Vejamos o Example Mapping, apresentado em 2015 por Matt Wynne, que liderou o projeto Cucumber. Ele diagnostica que a razão de muitos times terem dificuldade com discussões de requisitos é a falta de estrutura, que as torna longas e entediantes. E por isso os times deixam de fazê-las com regularidade e com consistência. Comigo era exatamente assim: quando uma reunião de requisitos se alonga, na próxima você tenta terminar rápido, e terminando rápido as ambiguidades ficam como estavam.

O Example Mapping divide a discussão em cartões de quatro cores. O amarelo é a história em pauta, o azul é a regra ou critério de aceitação, o verde é o exemplo concreto que ilustra essa regra e o vermelho é a pergunta cuja resposta ninguém sabe.

Entre eles, acho que o cartão vermelho é o essencial. Os outros três são técnicas de organização, mas o vermelho é o dispositivo que transforma o “não sei” em um produto oficial da reunião. Dizer que não sabe deixa de ser um ato que atrasa a reunião e passa a ser um resultado que a reunião deve produzir.

Por que isso importa fica claro ao imaginar o caso oposto. Numa reunião sem cartões vermelhos, esbarrar num ponto ambíguo deixa duas opções: insistir agora e esticar a reunião, ou seguir em frente e interpretar sozinho depois. Como vimos na seção anterior, as pessoas em geral escolhem a segunda. Mas com um cartão à mão surge uma terceira opção. Anotar e seguir, sem deixar que aquilo desapareça. A reunião continua andando, e a ambiguidade fica numa lista em vez de sumir.

O cartão verde cumpre papel parecido. Quando só a regra é escrita, todo mundo concorda; no momento em que alguém tenta escrever um exemplo concreto que a ilustre, as interpretações se separam. É o “usar os termos repetidamente na conversa revela as diferenças”, de Evans, transposto para o formato de reunião. Se você pede três exemplos por regra, em um deles costuma aparecer um “peraí, e neste caso, como fica?”. (Pela minha experiência, a reunião em que essa pergunta não aparece não é uma reunião em que todos entenderam, e sim uma em que cada um entendeu de um jeito)

Com uma ideia parecida existe também o Three Amigos, usado há tempos no meio de BDD. A proposta é que as três perspectivas de negócio, desenvolvimento e teste façam cada uma uma pergunta diferente, e o glossário da Agile Alliance organiza essas perguntas como qual problema se está tentando resolver, como construir uma solução para resolvê-lo e, quanto a isto, o que poderia acontecer. O que acontece com uma reunião em que a terceira pergunta nunca aparece provavelmente não precisa de explicação.

Crie um processo para verificar o que não se sabe

Mas por que temos tanta dificuldade de puxar o cartão vermelho? Aqui não dá para desviar do assunto da segurança psicológica.

O artigo que Amy Edmondson publicou na Administrative Science Quarterly em 1999 é o estudo que estabeleceu formalmente o conceito de segurança psicológica de time. (O próprio artigo aponta como raiz o trabalho de Schein e Bennis de 1965.) Ele define segurança psicológica de time como a crença compartilhada de que o time é um lugar seguro para assumir riscos interpessoais. Dizer que não sabe, discordar e admitir um erro entram aí. O artigo pesquisou 51 times de uma empresa industrial e mostrou que a segurança psicológica se associa ao comportamento de aprendizado e que esse comportamento medeia a relação entre segurança psicológica e desempenho do time.

Mas a frase que achei mais prática nesse artigo não foi a definição, e sim a que vem logo depois.

Na maior parte das vezes, essa crença tende a ser tácita: é tomada como dada e não recebe atenção direta nem dos indivíduos nem do time como um todo.

For the most part, this belief tends to be tacit—taken for granted and not given direct attention either by individuals or by the team as a whole.

Essa crença costuma ser tácita, e nem os indivíduos nem o time lhe dão atenção direta.

Daqui em diante é conjectura minha. O que o artigo diz vai até a crença ser tácita; a prescrição de que, portanto, basta criar um formulário não está no artigo. Dito isso, já vi várias vezes que o tácito não muda por declaração. Dizer “nosso time é um time em que dá para perguntar o que você não sabe” não muda grande coisa sozinho. Por isso acho que o cartão vermelho da seção anterior importa. Se você transforma o “não sei” em um campo dentro de um formulário, preenchê-lo vira procedimento em vez de coragem.

Cabe uma objeção, claro. Num time que não é seguro, o campo do cartão vermelho vai simplesmente ficar vazio. É uma crítica justa, e não pretendo afirmar que esta ferramenta cria segurança. Mas, se o campo existe, ao menos o fato de estar vazio se torna visível. Cria-se um lugar para perguntar se está vazio porque ninguém tem dúvida ou porque é difícil falar.

A mesma ideia está incorporada em formatos de documento reais. Olhando o Bounded Context Canvas criado pela comunidade de DDD, é uma ferramenta colaborativa para projetar e documentar um contexto, e a composição dos campos é interessante. Nome e propósito, classificação estratégica, papel no domínio, comunicação de entrada e de saída, e então Ubiquitous Language, decisões de negócio, Assumptions, métricas de verificação e Open Questions.

Há um campo separado para escrever a linguagem compartilhada, outro para os pressupostos e outro para as perguntas em aberto. A descrição do canvas diz que o próprio ato de escrever o propósito força um pensamento nebuloso a ser dito com clareza e coloca o time inteiro na mesma página.

Acho que essa é a abordagem mais realista para problemas de comunicação. Em vez de tentar mudar a atitude das pessoas, criar um campo para aquilo que é difícil de dizer. Uma boa estrutura não exige que as pessoas façam bem, ela torna fácil fazer bem.

Por que isso não é questão de gosto

Chegando aqui, cabe uma reação: bonito, mas no fim das contas é “vamos nos comunicar com empenho”, não? E isso não é traço de personalidade?

Também pensei assim por um tempo. Mas sobre essa parte existem dados.

Quando a DORA trata de cultura organizacional, ela toma emprestada a classificação do sociólogo Ron Westrum: pathological, orientada a poder; bureaucratic, orientada a regras; e generative, orientada a resultado. E a documentação oficial da DORA resume assim os próprios achados.

Uma cultura organizacional de alta confiança que enfatiza o fluxo de informação é preditiva do desempenho de entrega de software.

organizational culture that is high-trust and emphasizes information flow is predictive of software delivery performance

Uma cultura organizacional de alta confiança que enfatiza o fluxo de informação prediz o desempenho de entrega de software. Não é dizer que times que se comunicam bem ficam de bom humor, e sim que essa é uma variável que se move junto com o desempenho.

Dito isso, “predizer” não deve ser lido aqui como causalidade. Os dados da DORA vêm de uma pesquisa em que os mesmos respondentes responderam sobre cultura e sobre desempenho, e é uma correlação em nível organizacional. Permanece a possibilidade de quem está satisfeito com a organização ter avaliado bem os dois lados, e de uma relação em nível organizacional não decorre imediatamente uma prescrição de como um indivíduo deve agir. Então o material permite dizer até aqui: o fluxo de informação não mora só no terreno do gosto, ele está num lugar em que se move junto com o desempenho.

O mesmo documento também organiza as três propriedades da boa informação segundo Westrum: ela responde à pergunta de que quem recebe precisa, chega no momento adequado e é apresentada de um jeito que quem recebe consegue usar com eficácia. Vale reparar que as três colocam o critério em quem recebe. Compartilhar muito não é o que faz um fluxo de informação ser bom.

O Project Aristotle do Google é outra fonte citada com frequência. Segundo o que foi publicado no reWork, foram estudados 180 times, rodados mais de 35 modelos estatísticos sobre centenas de variáveis, e apresentados cinco fatores que influenciam a efetividade do time: segurança psicológica, confiabilidade, estrutura e clareza, significado e impacto. E a conclusão foi que importou mais como aquele time trabalhou junto do que quem estava nele.

Ainda assim, quero registrar uma coisa. A página oficial declara que lista os cinco fatores em ordem de importância e coloca a segurança psicológica em primeiro. Mas expressões de magnitude do tipo “primeiro de forma esmagadora”, que aparecem com frequência em textos que citam essa pesquisa, não estão naquela página. Haver uma ordem e um fator dominar os demais são coisas diferentes. Por isso este texto não afirma nada sobre magnitude. Para defender a importância da segurança psicológica, o preciso é se apoiar no artigo original de Edmondson, da seção anterior.

De volta ao assunto da liderança

Voltemos ao artigo citado no começo.

Ao tratar da coleta de informação em primeiro lugar, James Samuel diz que os métodos da fase de execução deixam de funcionar. Como contribuidor individual você tem o quadro completo do próprio trabalho, mas, ao assumir responsabilidade sobre pessoas, não dá mais para usar o método anterior. Por isso ele aponta como capacidade necessária a de filtrar o ruído e sintetizar a informação num quadro coerente da realidade, porque nenhum gestor consegue processar tudo.

Senti que isso é o mesmo que as três propriedades da boa informação de Westrum que vimos antes. Não se trata de coletar muito, e sim de transformar em algo utilizável. E isso não é diferente do que estou fazendo agora ao lidar com requisitos. Separar as partes ambíguas das frases de uma especificação, redesenhá-las como breadboard para confirmar e deixar o que não se sabe como cartão vermelho é exatamente o exercício de filtrar ruído e montar um quadro coerente.

O que o autor deixou sobre tomada de decisão também ficou comigo: esperar por certeza é, em si, uma decisão e carrega um custo. Esperar até que os requisitos fiquem completamente claros é a mesma coisa. Por isso o grounding criterion, suficiente para o propósito atual em vez de compreensão perfeita, se torna o critério prático.

Conclusão

Resumindo.

A falha de comunicação com outras áreas em geral não é só uma questão de atitude. Quando uma organização contém contextos diferentes, a mesma palavra se dividir é o estado padrão, e estar alinhado é a exceção que precisa ser mantida a um custo. A forma de pagar esse custo é a linguagem compartilhada, e dentro dela o papel do developer não é transcrever requisitos, e sim vigiar a ambiguidade e devolvê-la.

Mas devolver dá trabalho, e as pessoas tentam minimizar esse trabalho. Então, em vez de me apoiar na força de vontade, decidi usar três coisas: confirmar primeiro em que modo está esta conversa, desenhar o fluxo na resolução entre a prosa e o layout e devolvê-lo, e criar dentro do formato de reunião um campo para anotar o que não se sabe. Nenhuma das três exige corrigir a atitude; as três tornam a coisa certa mais fácil de fazer.

Ainda não sou líder, e nada do que escrevi aqui foi verificado a partir daquele lugar. Com outro tamanho de time ou outra cultura organizacional, algumas coisas não vão funcionar. Mas há uma de que acho que posso ter certeza agora. O jeito como vou lidar com informação depois não será algo aprendido do zero, e sim o hábito com que hoje lido com requisitos, crescido em escala. Por isso ultimamente tento ter menos vergonha do que antes de perguntar numa reunião “o que você quer dizer com isso?”.

Se para quem lê este texto vier à cabeça alguma palavra de uma reunião recente com a qual você concordou balançando a cabeça sem estar realmente certo, recomendo usar essa palavra mais uma vez na próxima. Usando repetidamente, ela aparece.

Enquanto concluía o artigo anterior sobre como economizar tokens, uma pergunta não saía da minha cabeça. Acredito que o centro de gravidade está deixando o trabalho com prompts individuais e passando para a técnica de esvaziar e selecionar informações — context engineering. Quando terminei o texto, a pergunta seguinte surgiu naturalmente: então, o que vem depois do contexto?

É preciso cautela ao falar sobre “a direção do futuro”. Há inúmeras possibilidades pela frente; por isso, o foco aqui é organizar a mudança de ênfase que pode ser lida em fontes primárias já publicadas. Embora haja inevitavelmente alguma inferência, espero que o texto seja considerado sob perspectivas diversas.

Do prompt ao contexto

Comecemos esclarecendo os termos. Por algum tempo, o principal assunto do setor foi prompt engineering. A questão era como escrever bem uma única instrução enviada ao model, ou seja, como projetar orientações claras, bons exemplos e o formato de saída.

Depois, a unidade de trabalho cresceu. À medida que agentes que operam por dezenas de turnos se tornaram comuns, o mais importante deixou de ser um único prompt e passou a ser como compor todo o contexto que o modelo vê em cada turno (system prompt + definições de ferramentas + histórico da conversa + resultados de busca + memória). Isso é chamado de context engineering. A Anthropic organizou esse enquadramento no artigo “Effective context engineering for AI agents”, de setembro de 2025, e o estudo sobre context rot publicado no mesmo ano pela equipe da Chroma (Hong et al.) acrescentou evidências quantitativas. Com 18 modelos, incluindo GPT-4.1, Claude 4, Gemini 2.5 e Qwen3, eles mostraram que o desempenho se degrada de maneira desigual conforme a entrada aumenta, até em tarefas tão simples quanto copiar palavras literalmente. A suposição comum de que um modelo trata da mesma forma o 100º token e o 10,000º token não se sustenta na prática. A conclusão não foi “quanto maior o contexto, melhor”, mas “a forma como a informação é posicionada importa tanto quanto o que ela contém”. Isso reforçou a transição de preencher para selecionar e ajudou o termo a se firmar rapidamente.

Vale apontar um mal-entendido comum. Prompt engineering não foi substituído por context engineering. Escrever bons prompts continua sendo fundamental; context engineering se aproxima mais de um conceito superior construído sobre essa base. (O fato de o interesse passar de escrever bom código para projetar bons sistemas não torna coding desnecessário.) A descrição exata, portanto, não é “trocamos um pelo outro”, mas “o escopo se ampliou incluindo o anterior”.

Voltemos à pergunta: essa ampliação terminou no contexto? Não parece.

O blog de engenharia da Anthropic

Acredito que a forma mais honesta de estimar a direção seja ler, em ordem cronológica, o que escrevem as organizações que de fato impulsionam a área. Ao acompanhar o blog de engenharia da Anthropic depois de “Effective context engineering” (setembro de 2025), os próprios títulos começam a desenhar para onde o centro de gravidade seguiu.

• Outubro de 2025, Equipando agentes com Agent Skills
• Novembro de 2025, Code execution with MCP: agentes mais eficientes
• Novembro de 2025, Effective harnesses for long-running agents
• Janeiro de 2026, Demystifying evals for AI agents
• Janeiro de 2026, Projetando avaliações técnicas AI-resistant
• Fevereiro de 2026, Quantificando o ruído de infraestrutura em avaliações de agentic coding
• Março de 2026, Harness design for long-running application development
• Abril de 2026, Scaling Managed Agents: separando cérebro e mãos
• Maio de 2026, Como conter Claude em todos os produtos

Olhando a lista com certa distância, as palavras-chave se agrupam em três ramos: harness, eval e containment. Minha leitura é que a discussão subiu um nível: de como preencher e esvaziar o contexto para como projetar, medir e controlar todo o sistema de agentes. (Naturalmente, há a limitação de serem as prioridades de uma única empresa. Ainda assim, considerando o peso dela no ecossistema de coding agents, é difícil tratá-las apenas como interesses de um vendor.)

Vamos examinar cada ramo.

harness

A palavra harness talvez seja pouco familiar. Literalmente, é o arreio colocado em um cavalo para dirigir sua força. Em um agente de IA, harness é toda a estrutura externa que envolve o model e o coloca para trabalhar: quais tools ele pode usar e em que ordem, como se recupera de uma falha, até onde vão suas permissões e quando o loop termina.

Se context engineering pergunta “o que mostrar ao model?”, o design de harness pergunta “como fazer o model se mover dentro desse ambiente?”. Ele está uma camada mais para fora. Se o model fosse uma pessoa recém-contratada e muito capaz, o contexto seriam os materiais de trabalho entregues a ela, enquanto o harness seria o ambiente e o manual de procedimentos. A mesma pessoa pode apresentar resultados instáveis em um ambiente caótico e ir muito mais longe, com as mesmas habilidades, sobre um processo bem projetado.

A importância disso aparece claramente em uma falha enfrentada diretamente pela equipe de engenharia da Anthropic. Eles colocaram seu principal coding model, Opus 4.5, sobre o Claude Agent SDK, forneceram apenas instruções de alto nível, como “crie um clone do claude.ai”, e o executaram em várias sessões. Embora o model fosse inteligente, não produziu um app de nível production. As falhas se repetiam de duas formas. Em uma, a sessão tentava concluir tudo de uma vez, esgotava o contexto no meio da implementação e deixava para a próxima uma funcionalidade inacabada. Na outra, uma sessão posterior percebia que “já houve bastante progresso” e declarava o trabalho concluído apesar das tarefas restantes. (Imagine um trabalho longo passado entre pessoas em turnos, em que cada substituto não tem memória alguma do anterior.)

A solução não foi tornar o model mais inteligente, mas mudar a estrutura. A primeira sessão recebeu um prompt específico para preparar o ambiente (initializer agent), desdobrou mais de 200 especificações funcionais em feature_list.json e criou init.sh para iniciar o servidor de desenvolvimento, além de um log de progresso (claude-progress.txt). Cada sessão seguinte (coding agent) tratava exatamente de uma funcionalidade, deixava um estado limpo por meio de um git commit e notas de progresso, e então terminava. A próxima lia primeiro esse progress file e o git log para entender “até onde chegou o turno anterior” antes de continuar. Era o mesmo model, mas o resultado mudou sobre essa estrutura. O harness, e não o model, decidiu o sucesso. (Curiosamente, as soluções da Anthropic não são novas. Listas de funcionalidades, commits pequenos, notas de progresso e smoke tests executados sempre são exatamente o que uma pessoa experiente em desenvolvimento faz todos os dias. Uma boa estrutura para um agente é, no fim, semelhante a incorporar bons hábitos de engineering ao ambiente.)

A conexão com a economia de tokens também é clara. O isolamento de subagentes, a redução das definições de tools e o model routing abordados no artigo anterior parecem técnicas independentes quando vistos separadamente. Juntos, porém, são partes de como se projeta um único harness. Decidir qual model lane recebe cada tarefa, quais tools continuam ativas e onde a exploração verbose é isolada compõe o design de harness. A economia se parece mais com um efeito colateral desse design.

No entanto, o design de harness tem uma armadilha peculiar: quanto melhor a estrutura, mais provável é que ela envelheça quando o model melhora. Um harness é, em essência, um conjunto de suposições sobre “o que o model não consegue fazer sozinho”. No momento em que o model passa a fazer essas coisas, as suposições viram excesso de bagagem. Um caso da Anthropic ilustra isso exatamente. O Sonnet 4.5 tinha o hábito de se apressar para terminar ao se aproximar do limite de contexto — context anxiety —, então a estrutura incorporou um mecanismo de context reset. Quando a mesma estrutura foi usada com o Opus 4.5, esse hábito havia desaparecido, e o reset cuidadosamente adicionado virou peso morto. Cada vez que o model fica um pouco mais capaz, alguma parte da estrutura pode vencer.

Daí surge uma ideia adicional: em vez de aperfeiçoar uma estrutura específica, projetar interfaces que permaneçam estáveis mesmo quando a estrutura muda. Managed Agents, da Anthropic, segue essa direção, cujas raízes estão, surpreendentemente, nos sistemas operacionais. O OS sobreviveu por décadas porque virtualizou o hardware em abstrações como processos e arquivos, criando antecipadamente um recipiente para programas que ainda nem existiam. Uma linha de read() funciona da mesma maneira com um disco dos anos 1970 ou um SSD atual. Aplicando o mesmo raciocínio, o agente é dividido em três partes: o cérebro que decide (Claude e o harness), as mãos que agem (sandbox de execução de código e tools) e o session log que registra tudo por append. Com as três partes separadas, se o container morrer, o cérebro pode tratar o evento como um erro de tool call; se o harness morrer, pode despertar novamente a partir do último ponto no session log. Como efeito colateral, custo e latência também caíram. Ao iniciar containers apenas quando realmente necessários, a Anthropic relata que o time to first token (TTFT) caiu cerca de 60% na mediana e, no p95, mais de 90%. (Aqui voltamos ao artigo sobre economia de tokens. Ele recomendava colocar as partes estáticas primeiro para aproveitar prompt caching; decidir “como organizar o contexto para elevar o cache hit rate” é justamente o trabalho do harness ao lado desse cérebro.)

eval

O segundo ramo foi o mais interessante para mim. Como se houvesse um acordo, os artigos do início de 2026 convergem para a avaliação (eval).

O motivo é intuitivo. Como verificamos se o contexto foi bem composto, o harness bem projetado ou o custo realmente reduzido? Quanto mais longas e complexas são as tarefas que um agente executa de forma autônoma, mais difícil se torna inspecionar cada uma e decidir “isso realmente funcionou bem?”. A base da confiança acaba migrando para a medição. Por isso, questões como “como projetar avaliações de agentes?”, “como remover o ruído da própria avaliação?” e “como lidar com eval awareness, quando o model percebe a avaliação e muda o comportamento?” foram para o primeiro plano.

Avaliar agentes é difícil porque isso difere de uma pergunta e resposta pontual. Um agente chama tools e altera estados ao longo de vários turnos; assim, um erro se propaga e se acumula. Além disso, os resultados variam entre execuções mesmo com a mesma entrada. A Anthropic divide essa não determinação em duas métricas. pass@k é a probabilidade de sucesso pelo menos uma vez em k tentativas, por isso aumenta com mais tentativas. pass^k é a probabilidade de sucesso em todas as k tentativas, por isso diminui. Para geração de código que só precisa acertar uma vez, pass@1 importa; para um agente de atendimento que precisa funcionar sempre de modo confiável, pass^k é essencial. (Com taxa de sucesso per-trial de 75%, a probabilidade de três sucessos consecutivos é 0.75³, cerca de 42%. A distância entre “geralmente funciona” e “funciona sempre” é tão grande assim.)

Então, como pontuar uma tentativa? O mesmo artigo divide os graders em três tipos. Os code-based (resultado de tests, static analysis e validação de tool calls) são rápidos, baratos e objetivos, mas fracos em tarefas abertas com várias respostas válidas. Os model-based (LLM-as-judge e pontuação por rubric) capturam nuances de qualidade, mas não são determinísticos e precisam de calibração periódica com avaliações humanas. Os human-based são os mais precisos, porém lentos e caros. Na prática, os três são combinados, de preferência com avaliação determinística como base e avaliação do model como apoio. Há outra distinção. Um capability eval pergunta “o que este agente consegue realizar?”, portanto começa com uma pontuação baixa e oferece uma subida. Um regression eval pergunta “ele ainda faz o que fazia antes?”, por isso deve permanecer perto de 100%; uma queda indica que algo quebrou.

Aqui há uma armadilha surpreendentemente ignorada: a pontuação baixa pode ser culpa da avaliação, não do agente. A Anthropic relata que o Opus 4.5 obteve inicialmente 42% no CORE-Bench. A investigação encontrou pontuação rígida que esperava “96.124991…” e marcava “96.12” como errado, especificações ambíguas e tarefas estocásticas impossíveis de reproduzir. Depois de corrigir bugs e repetir com um scaffold de restrições mais flexíveis, a pontuação saltou para 95%. Por isso, eles enfatizam um princípio: não aceite a pontuação pelo valor de face; leia você mesmo o transcript (registro de execução). Se um frontier model fizer 100 tentativas e obtiver 0%, geralmente o problema está quebrado, e não o model incapaz.

Também é interessante que, conforme a medição avança, a própria linha de base se move depressa. No SWE-bench Verified — benchmark de referência para coding agents que fornece issues reais do GitHub e pontua se os tests passam —, os frontier models subiram da faixa de 30% para mais de 80% em 1 ano. Nesse ponto, todos os problemas fáceis estão resolvidos, a pontuação toca o teto (saturation) e surge um paradoxo: grandes avanços de capacidade aparecem apenas como pequenas diferenças. Segundo relatos, uma startup de code review inicialmente desprezou um model novo olhando apenas para avaliações one-shot; só percebeu corretamente a melhoria depois de migrar para avaliações de agentes com tarefas mais longas e complexas. Um eval, portanto, não é criado uma vez e encerrado: torna-se um ativo vivo que precisa ser continuamente substituído por versões mais difíceis. (A Anthropic compara isso ao “Swiss cheese model” da engenharia de segurança. Uma fatia cheia de buracos não basta, mas, ao sobrepor avaliação automática, production monitoring e revisão humana de transcripts, uma falha que atravessa uma camada fica presa na próxima.)

containment

O terceiro ramo tem um caráter um pouco diferente. Não trata de custo ou desempenho, mas de segurança e controle.

Quanto mais ferramentas um agente recebe e quanto mais autonomia tem, maior é o alcance de um único erro — o blast radius. Para um agente que pode apagar arquivos, enviar solicitações externas e executar ações privilegiadas em nome de alguém, “onde interromper o dano quando algo dá errado?” importa tanto quanto “quão bem ele executa?”. Nesse contexto pode ser lido o destaque dado pela Anthropic, em maio de 2026, ao artigo sobre containment em todos os seus produtos. Ele divide o risco dos agentes em três ramos: user misuse, quando o usuário pede algo nocivo por malícia ou descuido; model misbehavior, quando o modelo age sozinho sem solicitação; e external attacks que chegam por ferramentas, arquivos ou redes. Uma observação interessante é que tornar o modelo mais inteligente não reduz apenas o risco. Modelos menos capazes interpretam mal situações e cometem erros óbvios; os mais capazes erram menos, mas encontram melhor caminhos inesperados para contornar restrições que ninguém escreveu explicitamente.

O ponto central enfatizado é o limite de “ter uma pessoa supervisionando cada ação”. Claude Code inicialmente buscava segurança pedindo aprovação para cada escrita, execução e acesso à rede, mas a telemetria mostrou que os usuários simplesmente aprovavam cerca de 93% das solicitações. Quanto mais janelas aparecem, menos atenção cada uma recebe: surge a approval fatigue. Uma defesa probabilística dependente de cliques humanos sempre conserva brechas. O centro de gravidade passa de “monitorar o que o agente está fazendo” para “limitar o que ele pode fazer desde o início”. As defesas são empilhadas em três camadas: a camada de ambiente, com sandbox, VM e controle de egress; a camada do model, com system prompts e classifiers; e a camada de conteúdo externo, com MCP, plugins e resultados de busca. O princípio central é instalar primeiro a camada de ambiente, que bloqueia de forma determinística. Não porque as defesas do model sejam fracas. De fato, no benchmark da Gray Swan para prompt injection, a taxa de sucesso de um ataque único é de cerca de 0.1%, um resultado de primeira linha. Porém, com 100 tentativas adaptativas, ela sobe para 5–6%, e uma defesa probabilística não consegue, por natureza, atingir 100% de acerto. Por isso, coloca-se no fim uma fronteira rígida. (A introdução de sandbox no nível do OS reduziu as solicitações de aprovação em 84%. O mecanismo de segurança diminuiu a fricção.)

Embora pareça distante da economia de tokens, ambos compartilham a mesma raiz. Os dois perguntam: “o que dar ao agente e até onde?” A Anthropic mostra bem essa conexão com dois casos. Em um, o red team interno fez phishing com um funcionário para que ele executasse Claude Code com um prompt malicioso. Uma instrução discretamente inserida fez o sistema ler ~/.aws/credentials e enviar o conteúdo para fora via POST; de 25 tentativas, funcionou 24 vezes. Como o usuário digitou diretamente a instrução, o classifier do model não viu nada suspeito. O que impediu o ataque não foi um model inteligente, mas a fronteira ambiental que mantinha as credenciais fora do sandbox e o controle de egress. O segundo caso é mais sutil. Uma allowlist de egress permitiu corretamente api.anthropic.com, mas um arquivo plantado pelo invasor usou a própria API key dele para chamar a API de upload de arquivos da Anthropic, e os dados saíram para a conta do invasor. O sandbox funcionou perfeitamente, mas os dados ainda vazaram. A lição foi entender a allowlist não como “filtro de destinos”, mas como “permissão para todas as capacidades disponíveis naquele domínio”. (A Anthropic repete este princípio: hypervisors, filtros de syscall e runtimes de containers já verificados resistiram; o que realmente quebrou foram os componentes construídos por eles sobre essa base.) Remover tools de MCP não utilizadas pertence ao mesmo contexto: economiza custo e reduz a attack surface. Manter um design leve o torna não apenas mais barato e preciso, mas também mais seguro.

Em resumo

Os três ramos podem ser condensados em uma frase. A unidade de atenção se expande um nível de cada vez: do prompt (uma instrução), para o contexto (o que mostrar em cada turno), e então para todo o sistema de agentes (como operá-lo, medi-lo e contê-lo). Harness responde a “como fazê-lo funcionar?”, eval a “como saber se funcionou bem?” e containment a “como detê-lo quando funciona mal?”.

Vale reforçar: esses três ramos são uma mudança de ênfase que o autor infere de materiais já publicados, não uma previsão como “isso será o padrão no segundo semestre de 2026”. Algumas correntes crescerão, enquanto outras serão absorvidas sob nomes diferentes. O que está claro é que nem o prompt nem o contexto desaparecerão: continuarão como partes de uma estrutura maior. A área avançou acrescentando uma camada sobre as anteriores, e não apagando palavras antigas com novas, e provavelmente continuará assim.

Começamos falando de custos e chegamos até aqui. O artigo anterior recomendava abrir o livro de contas de tokens; este sugere ir um passo além. Vale examinar em conjunto como verificar a economia (eval), sobre qual estrutura ela pode ser repetida (harness) e até onde essa estrutura é segura (containment). No fim, o que deve durar mais não é uma técnica específica de economia, mas o hábito de medir e controlar o próprio sistema.

Este texto é uma reescrita de uma retrospectiva que publiquei em junho de 2026. A frase que abria o post original, "sete pickers em uma única API, menores que um único calendário de uma biblioteca concorrente", ao ser verificada de novo, se mostrou metade errada e metade irrelevante como diferencial. Por isso reorganizo tudo nesta ordem: por que criei, em que difere das opções existentes e qual é a definição técnica.

Adiantando a conclusão: o que diferencia o Kalyx não é a quantidade de componentes, e sim o modelo de valor. As versões de referência são @kalyx/react 1.4.7 e @kalyx/core 1.4.8 (MIT, apenas React 19), e os trechos de código vêm do repositório no GitHub na main de 2026-09-16 (0bb302e).

Eu queria usar seletores de datas de forma declarativa

Tive dois motivos para criá-lo. Eu queria usar bibliotecas de datas complexas e difíceis de usar de um jeito mais declarativo e simples, e queria aprender como uma biblioteca dessas é construída por dentro. "Difícil de usar" é vago, então voltei às definições de tipos de cada biblioteca para conferir se os lugares onde travei ainda existem nas versões mais recentes.

Uma API que liga modos com props

O react-datepicker liga a seleção de horário com showTimeSelect, a de mês com showMonthYearPicker, a de ano com showYearPicker e a de intervalo com selectsRange. É uma estrutura em que um mesmo componente vira outra coisa conforme a combinação de props. O custo aparece nos tipos. Nas definições de tipos da 9.1.0, conforme o valor de selectsRange, a assinatura de onChange se ramifica.

// react-datepicker/dist/index.d.ts (발췌)
    selectsRange?: true;
    selectsMultiple?: false | undefined;
    formatMultipleDates?: never;
    onChange?: (date: [Date | null, Date | null], event?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void;

É uma union bem feita, mas os ramos se multiplicam à medida que os modos aumentam, e quem usa precisa deduzir qual combinação está ativa só pelos nomes das props. (Tem o mesmo formato de "uma abstração que agrupa as coisas erradas aumenta o acoplamento", tema do meu post sobre abstração.) Eu queria que "um campo de entrada, um popover e um calendário" pudessem ser lidos na própria estrutura do JSX.

Onde tipos de valor e fuso horário vazam

O react-datepicker e o react-day-picker trocam objetos Date nativos. Os dois têm, sim, uma prop timeZone que aceita fusos IANA. O react-datepicker exige a peer opcional date-fns-tz e a do react-day-picker é experimental, mas, em qualquer um dos dois, o tipo do valor continua sendo Date. Como um Date é interpretado no fuso horário local do ambiente de execução, em Seul new Date(2026, 3, 15) passado por toISOString() resulta em 2026-04-14T15:00:00.000Z. Você escolhe 15 de abril e o servidor enxerga dia 14. A issue "Date Selected is One Day Off" do react-datepicker foi aberta em setembro de 2017 e fechada em dezembro de 2025.

Do outro lado, Ark UI e React Aria usam objetos @internationalized/date como CalendarDate e ZonedDateTime. A semântica é precisa, mas em um app em que o estado dos formulários e as respostas do servidor são todos strings, surge código de conversão em cada fronteira.

O suporte a fusos horários também pode ficar preso à escolha da biblioteca de datas. No código dos adapters do MUI X Date Pickers 9.13.0, os adapters de dayjs, Luxon e Moment têm isTimezoneCompatible = true, e a família date-fns tem false. Um app que usa date-fns precisa trazer mais uma biblioteca de datas para usar a prop timezone.

Os modos estavam espalhados em combinações de props, os valores em objetos Date cuja interpretação depende do ambiente e o suporte a fusos horários na escolha da biblioteca de datas. Era difícil expressar a intenção em uma única declaração.

Aprender construindo

Um seletor de datas parece pequeno, mas contém aritmética de calendário, locales, fusos horários e horário de verão (DST), navegação por teclado e SSR. Por isso defini como objetivo que, do lado de quem usa, desse para entender o que está sendo construído só olhando o JSX, e que, do lado de quem constrói, o código fosse enxuto o bastante para eu conseguir explicar onde os valores são convertidos.

Então, será que não existia mesmo nenhuma biblioteca que já resolvesse essas necessidades?

Em que ele difere das opções existentes

A resposta curta é que existia. Comecei acreditando que não havia nenhuma biblioteca headless com vários pickers, mas ao pesquisar de novo essa premissa se mostrou errada.

O modelo de valor que cada opção escolheu

O conteúdo abaixo foi verificado em 2026-09-16, instalando a versão mais recente do npm e conferindo as definições de tipos e a documentação oficial. A coluna de tamanho foi medida com o mesmo método explicado mais adiante.

O react-day-picker afirma no guia oficial que "DayPicker does not include a built-in time picker". O tamanho do MUI inclui @mui/material e emotion, então, se o seu app já usa MUI, o aumento é bem menor.

Opções headless completas já existem

As linhas que importam na tabela são Ark UI e React Aria. O Ark UI oferece seleção única, múltipla e de intervalo, além de seleção por mês e ano, com uma API de composição em dot notation como DatePicker.Root. O React Aria é a implementação da Adobe focada em acessibilidade. Então o espaço do Kalyx é mais estreito do que eu pensava no início.

Opções headless completas já existem. Porém, Ark UI e React Aria trocam valores como objetos @internationalized/date e oferecem a entrada de horário como campos segmentados. O Kalyx fixa os valores como strings de instante UTC que vão direto para o JSON, e coloca na mesma API de composição um TimePicker baseado em listas e pickers de mês, ano e semana.

Ainda assim, "os valores são strings, e isso é bom" é um argumento fraco. Um CalendarDate também vira string com um único toString(). O diferencial não é o formato, e sim o contrato de que essa string é sempre um momento real (um instante) e nunca se mistura com uma célula do calendário (uma coordenada), e os testes que garantem esse contrato.

Medi o tamanho do bundle de novo com um mesmo método

O tamanho do bundle no badge do README não era uma quantidade comparável à de outras bibliotecas. Os cerca de 19.5KB do badge são um único arquivo de @kalyx/react em dist, e esse arquivo deixa @kalyx/core, @kalyx/adapter-date-fns e @floating-ui/react como imports externos. Eu tinha colocado esse número ao lado dos números de outras bibliotecas que incluíam suas dependências.

Então medi tudo de novo com esta pergunta: "quanto o bundle cresce quando um app consumidor adiciona uma linha de import?"

echo "import { DatePicker } from '@kalyx/react'; export default DatePicker;" > entry.jsx
npx esbuild entry.jsx --bundle --minify --format=esm --platform=browser \
  --external:react --external:react-dom --external:react/jsx-runtime | gzip -6 | wc -c

Medição de 2026-09-16 com esbuild 0.28.2; KB são bytes divididos por 1024. No react-datepicker excluí o CSS. O React Aria Components medi duas vezes: com os 12 exports necessários para montar um único DatePicker (DatePicker, DateInput, Calendar, Popover, Dialog etc.) e com 14 exports que acrescentam intervalo e hora (incluindo DateRangePicker, RangeCalendar e TimeField).

Nas mesmas condições, só uma afirmação é verdadeira. Um DatePicker (18.9KB) tem tamanho parecido com o de DayPicker (20.0KB), e os sete juntos (25.6KB) são maiores. (E mesmo assim, o DayPicker é só o calendário, enquanto o Kalyx DatePicker inclui também o campo de entrada e o popover.) O tamanho é sensível à combinação de imports e ao nível de gzip, então é melhor lê-lo como ordem de grandeza, e tamanho não é o motivo central para escolher o Kalyx.

Uma definição técnica do Kalyx

O Kalyx é um seletor de datas headless para React que fixa todas as entradas e saídas como strings de instante UTC, confina a conversão entre coordenadas de calendário e instantes a duas funções e verifica essa ida e volta com testes de propriedades em todos os fusos horários que o runtime conhece.

A API do lado de quem usa é esta. value e onChange usam string | null, e displayTimezone decide o calendário de qual fuso é exibido.

<DatePicker value={iso} onChange={setIso} displayTimezone="America/New_York">
  <DatePicker.Input />
  <DatePicker.Popover>
    <DatePicker.Calendar />
  </DatePicker.Popover>
</DatePicker>

Valores são instantes, células do calendário são coordenadas

Dentro do Kalyx circulam dois tipos de strings ISO com o mesmo formato. Uma coordenada é uma célula da grade do calendário; é escrita como YYYY-MM-DDT00:00:00.000Z, mas não tem noção de fuso horário. O cálculo da grade roda só em UTC, então não depende do ambiente de execução. Um instante é o valor que sai por onChange: o momento real que corresponde à meia-noite daquele dia em displayTimezone. O mesmo 15 de janeiro é 2026-01-15T05:00:00.000Z em Nova York e 2026-01-14T15:00:00.000Z em Seul.

Só duas funções de @kalyx/core ligam os dois: civilMidnightFromUtcDay, que transforma coordenada em instante, e sua inversa, calendarDayFromInstant. Esta última lê "que dia é esse instante neste fuso" e escreve de novo como coordenada de meia-noite UTC.

// packages/core/src/utils/timezone.ts:187-190
export function calendarDayFromInstant(iso: ISODateString, timeZone: string): ISODateString {
  const p = partsInTimezone(new Date(iso), timeZone);
  return new Date(Date.UTC(p.year, p.month - 1, p.day)).toISOString();
}

A regra é de direção. Ao escolher uma célula e confirmar o valor, a coordenada vira instante; ao decidir, a partir do valor salvo, qual mês exibir e onde colocar o foco, o instante vira coordenada. O selectDate do Root do DatePicker converte, verifica as restrições com o instante convertido e, se passar, confirma.

// packages/react/src/components/DatePicker/Root.tsx:182-194
const normalized =
  coordinate && displayTimezone
    ? civilMidnightFromUtcDay(coordinate, displayTimezone)
    : coordinate;
 
if (normalized && isDateDisabled(normalized, disabledRules, adapter, displayTimezone)) {
  return;
}
 
if (!isControlled) {
  setUncontrolledValue(normalized);
}
onChange?.(normalized);

Esse não é o único ponto de chamada. Buscando em packages/react/src, as duas funções aparecem espalhadas pelo Root e pelo Calendar de DatePicker, RangePicker e DateTimePicker, pelos Presets, pelos utilitários de navegação por teclado e por seis hooks headless. Mesmo assim, todo caminho que confirma uma célula de data ou decide a visualização passa por uma das duas. Confirmar um horário fica com setTimeInTimezone, que por dentro converte com a mesma função interna, resolveCivilDateTime.

Esse contrato é protegido por testes baseados em propriedades (property-based tests). Para toda coordenada c e todo fuso z, calendarDayFromInstant(civilMidnightFromUtcDay(c, z), z) === c precisa valer.

// packages/core/src/__tests__/timezone.property.test.ts:86-94
it('round-trips every UTC calendar coordinate through civil midnight', () => {
  fc.assert(
    fc.property(utcCalendarCoordinate(), zone(), (coordinate, timeZone) => {
      const instant = civilMidnightFromUtcDay(coordinate, timeZone);
      expect(calendarDayFromInstant(instant, timeZone)).toBe(coordinate);
    }),
    RUNS,
  );
});

O fast-check gera datas aleatórias entre 2020 e 2045 e as combina com 14 fusos representativos, como Kathmandu (+5:45), Kiritimati (+14) e Niue (-11), em 300 execuções. O teste logo em seguida verifica a mesma ida e volta 12 vezes por fuso para todos os fusos retornados por Intl.supportedValuesOf('timeZone'). No meu Node 24.16 local, essa lista tem 418 fusos. A 1.4.8 acrescentou um teste exaustivo que compara, em cada transição de horário de verão, a conversão dos horários-limite com uma implementação do Temporal.

Então por que a biblioteca não normaliza sozinha para instante um "2026-01-15T00:00:00.000Z" passado pelo usuário? Esse caminho está fechado, porque só pela string não dá para saber se é coordenada ou instante. Se o valor de Seul 2026-01-14T15:00:00.000Z, que já é um instante, passar de novo por civilMidnightFromUtcDay, vira 2026-01-13T15:00:00.000Z; em fusos com offset positivo como Seul, a data continua voltando um dia a cada render. (O valor de Nova York não muda se passar de novo.) Trocar por startOfDayInTimezone, que dá o mesmo resultado não importa quantas vezes seja aplicado, elimina o deslocamento, mas deixa de fazer o trabalho original de transformar coordenada em instante.

Por isso desisti da normalização e fixei o contrato na documentação. Quem usa precisa repassar exatamente o valor que o picker emitiu. Sendo sincero, é um custo empurrado para quem consome a biblioteca, e como ISODateString é um alias de string, o compilador também não impede o erro.

Resolvendo DST só com Intl

Para transformar uma coordenada em instante, é preciso saber quando é, em UTC, "00:00 daquele dia naquele fuso", mas o offset só pode ser obtido quando já se conhece o instante. Além disso, nos dias de transição do horário de verão, o horário local pode não existir (spring forward) ou existir duas vezes (fall back).

O Kalyx resolve isso sem uma biblioteca como date-fns-tz. Ele pergunta ao Intl.DateTimeFormat(...).formatToParts "que horas são neste fuso neste momento UTC" para medir o offset, e lê esse offset em dois pontos: um dia antes e um dia depois do horário pedido.

// packages/core/src/utils/timezone.ts:251-254, 259
const candidate = (probeEpoch: number) =>
  civilEpoch - getTimezoneOffsetMinutes(new Date(probeEpoch).toISOString(), timeZone) * 60_000;
const epochBefore = candidate(civilEpoch - 86_400_000);
const epochAfter = candidate(civilEpoch + 86_400_000);
 
if (epochBefore === epochAfter) return new Date(epochBefore).toISOString();

civilEpoch é o horário local desejado lido como se fosse UTC. Os offsets ficam dentro de ±14 horas, então um dia antes e um dia depois dão o offset de cada lado de qualquer transição próxima. Se os dois coincidem não há transição e bastam duas chamadas a formatToParts; como a grade chama isso uma vez para cada uma das suas 42 células, é esse caminho rápido que determina o custo. (A premissa de no máximo uma transição em 48 horas vale em todos os fusos de 2020 a 2045.)

Se forem diferentes, ele relê os dois candidatos naquele fuso e confere qual coincide com o horário pedido (timezone.ts:261-279). Na sobreposição do fall back os dois coincidem, então ele escolhe o mais cedo, montado com o offset anterior à transição; no buraco do spring forward nenhum coincide, então escolhe esse mesmo lado e avança o horário pela duração do buraco. Este é o resultado de rodar de verdade.

"Buracos vão para frente, ambiguidade fica com o mais cedo" coincide com o padrão de disambiguation, "compatible", descrito na documentação do Temporal.ZonedDateTime no MDN. Por que a linha de Londres erra na 1.4.7 fica para mais adiante.

A fronteira do adapter são 21 métodos de strings

Se o core calcula fusos horários, do que date-fns ou dayjs cuidam? Da aritmética de datas e do parsing. Essa fronteira, DateAdapter, tem 21 métodos, e todos os argumentos de data e valores de retorno são strings ISO.

// packages/core/src/types.ts:71-102 (발췌)
export interface DateAdapter {
  parse(value: string, format?: string): string;
  format(iso: string, formatStr: string, timezone?: string): string;
  addDays(iso: string, n: number): string;
  isSameDay(a: string, b: string, timezone?: string): boolean;
  startOfDay(iso: string, timezone?: string): string;
  today(timezone?: string): string;
  // addMonths, isBefore, startOfMonth, getYear 등 15개
}

Os métodos que recebem fuso horário são quatro, format, isSameDay, startOfDay e today, e até esses quatro delegam o cálculo ao core. O format do adapter de date-fns, quando recebe timezone, chama diretamente o formatInTimezone do core (packages/adapter-date-fns/src/index.ts:112-115). Por isso, seja qual for o adapter, as respostas sobre fuso horário saem do mesmo código, e os três adapters (date-fns, dayjs, luxon) pegam em @kalyx/core/test-helpers a função runAdapterConformanceTests e a rodam cada um para confirmar que dão as mesmas respostas.

Os dois entry points também se separam sobre essa fronteira. O entry padrão, @kalyx/react, chama setDefaultAdapter(DateFnsAdapter) ao carregar o módulo, então funciona logo após a instalação (packages/react/src/index.ts:9-11). @kalyx/react/headless não faz essa chamada e é empacotado à parte, então nenhum código de date-fns entra.

O formato dessa fronteira teve um preço. Em junho de 2026, desisti de um adapter de Temporal. O valor do Temporal está em os tipos carregarem o significado, como PlainDate e ZonedDateTime, mas se a fronteira é uma string, esse significado não consegue atravessá-la. Envolver o Temporal só achataria tudo em string, então concluí que não havia ganho de exatidão. Olhando para trás, o problema da seção anterior, "coordenadas e instantes são o mesmo string", é exatamente o que o Temporal resolve no sistema de tipos com PlainDate e Instant. A fronteira de strings facilitou a troca de adapters, mas em troca fechou o caminho de resolver isso com tipos.

Sete pickers são combinações de três contextos

O Kalyx tem sete pickers: DatePicker, RangePicker, TimePicker, DateTimePicker, MonthPicker, YearPicker e WeekPicker. O que importa não é a quantidade, e sim o fato de os sete não serem implementações independentes. Existem só três contextos: DatePickerContext, RangePickerContext e TimePickerContext.

O Root do MonthPicker apenas muda o formato de exibição padrão para yyyy-MM e passa selectionGranularity="month" para a implementação do Root do DatePicker (MonthPicker/Root.tsx:11-20). O selectDate do DatePicker, quando a granularity é month, dobra a coordenada para o dia 1 daquele mês e depois passa pela mesma conversão e verificação de restrições vistas antes. O DateTimePicker fornece os dois contextos sobrepostos.

// packages/react/src/components/DateTimePicker/Root.tsx:401-402
<DatePickerContext.Provider value={dateContext}>
  <TimePickerContext.Provider value={timeContext}>{children}</TimePickerContext.Provider>

Por isso DateTimePicker.Calendar é o mesmo componente que DatePicker.Calendar e não sabe dentro de qual picker está. Uma correção em um lugar chega a todos os pickers que usam esse componente, e um defeito em um lugar também. Essa base compartilhada também explica por que um único DatePicker representava 74% do total no gráfico anterior.

O que custou manter o contrato

Os três meses desde a 1.0 foram mais para verificar esse contrato do que para criar funcionalidades, e surgiram três defeitos que testes baseados em exemplos teriam deixado passar. O primeiro foi encontrado por um teste de propriedades, o segundo por uma revisão cruzada do código e o terceiro pela checagem deste post.

Uma hora em 1º de outubro em Sydney

O primeiro foi a propriedade "ler no fuso o resultado de startOfDayInTimezone dá 00:00:00" quebrar em Australia/Sydney. A implementação da época media o offset só uma vez. Sydney passa de +10 para +11 às 02:00 de 1º de outubro de 2034, e 00:00 desse dia ainda é +10, então a resposta certa é 2034-09-30T14:00:00.000Z. Mas "o ponto em que 00:00 de 1º de outubro é lido como UTC" fica depois da transição, então retornava +11, e o resultado era 23:00 do dia anterior. Esse contraexemplo continua como teste de regressão (timezone.property.test.ts:276).

Um teste que só passava em Seul

O segundo apareceu em uma revisão cruzada em 3 de agosto de 2026. O código que decide qual célula do calendário marcar como selecionada convertia duas vezes. A célula já era uma coordenada, mas tanto a célula quanto o valor salvo eram convertidos para a data daquele fuso. Veja o resultado de escolher "15 de janeiro".

Em fusos com offset positivo, os dois deslocamentos se anulavam e por acaso dava certo, e os testes existentes só cobriam Seul. A mesma revisão encontrou também uma violação na direção oposta. Ao decidir qual mês exibir, startOfMonth era aplicado direto a um instante, então, em Seul, passar 1º de janeiro como valor abria o calendário de dezembro.

Os mecanismos são diferentes, mas a regra violada é uma só: converter uma única vez por direção, com a função definida para aquela direção.

Esse incidente ampliou os testes de propriedades de ida e volta do core de "alguns fusos representativos" para "todos os fusos que o runtime conhece". (Os testes de componentes do lado React ainda usam fusos representativos como America/New_York.) Defeitos que só aparecem onde o sinal muda não são pegos por amostragem.

O 01:30 de Londres que resolvia tarde

O terceiro apareceu quando estendi a tabela de DST deste post para outros fusos. A 1.4.7 começava a medir o offset no ponto em que o horário pedido é lido como UTC, e nos fusos cujo offset após a transição é 0 ou mais, esse ponto já fica depois da transição, então convergia para o offset mais tarde. Comparando com o temporal-polyfill todas as transições de 2020 a 2045 em 418 fusos, em 1.908 das 3.395 transições com sobreposição o resultado era o mais tarde, espalhadas por 84 fusos. (As 3.394 transições com buraco estavam todas certas, e Nova York, com offset negativo, acertava por acaso.)

Em #226 mudei para ler um dia antes e um dia depois, publiquei como @kalyx/core 1.4.8 e deixei a mesma comparação como timezone.dst-oracle.test.ts. (O temporal-polyfill é usado só nos testes.) O comentário no código que dizia erroneamente 'earlier' agora diz 'compatible'. De novo, as amostras estavam concentradas em um só sinal.

Os 3KB gastos com exatidão

Essas correções custaram código. O Kalyx define na CI um teto para o bundle do entry padrão, e um PR que o ultrapassa falha em um check obrigatório. Esse teto começou em 12KB e subia 1KB a cada funcionalidade que entrava, e em agosto de 2026, ao refazer por completo a exatidão de fusos horários e restrições, eu o subi de 17KB para 20KB de uma vez.

O tamanho era um argumento de venda exibido no badge do README. Um seletor de datas que desloca um dia em fusos com offset negativo não serve, seja pequeno ou grande.

Se eu tiver que escolher entre pequeno e correto, fico com o correto. Hoje o teto está apertado. Segundo o documento de mapa de bytes do bundle do repositório, de 2026-09-11, dist/index.cjs medido com o gzip padrão do Node tem 20.259 B, contra um teto de 20.480 B, deixando 221 B de folga. (É o tamanho do próprio arquivo com as dependências externas, então é uma quantidade diferente da do gráfico anterior.) A próxima funcionalidade vai precisar recuperar bytes antes de entrar.

Uma conclusão diferente da inicial

O que eu queria era usar bibliotecas de datas complexas de forma declarativa. Depois de construir, percebi que APIs de composição declarativas e opções headless completas já existiam. A diferença que restou estava mais para dentro. Fixar o valor como um único instante, reduzir a conversão entre coordenadas e instantes a duas funções e proteger essa ida e volta com testes em todos os fusos horários. O tratamento de DST baseado em Intl, a fronteira de adapter com strings e os sete pickers feitos com três contextos são consequências dessa decisão.

Pelo objetivo de aprender, a maior lição foi como afirmar que algo está "correto". A comparação de bundles do post original media quantidades diferentes, e o teste que passava em Seul estava errado em Nova York. Se você não registra junto o que mediu e com qual amostra verificou, números viram facilmente motivo de vaidade.

Os limites também são claros. Sou o único maintainer, só há suporte a React 19, e os downloads no npm de @kalyx/react de 5 a 11 de setembro de 2026 foram 200, dos quais 156 se concentraram no único dia do lançamento da 1.4.7. A impossibilidade de separar coordenadas e instantes por tipos é contida só pela documentação, e também não decidi se vou garantir como API pública os pontos de contato para estilo, classNames e os atributos data-*. Em acessibilidade, há os papéis grid nos calendários, combobox nos campos de entrada e listbox nas listas de horário, com navegação por setas, Home/End e PageUp/PageDown, e a CI roda as verificações de jest-axe de 8 arquivos de teste, mas ainda não tenho base para dizer que ela é tão comprovada quanto a do React Aria.

Por isso, se o seu app já usa MUI, vale olhar primeiro o MUI X; se entrada por segmentos e acessibilidade comprovada vêm primeiro, o React Aria; e se você só precisa de um calendário, o react-day-picker. Se você já passou por datas deslocando um dia em formulários onde os valores trafegam como JSON, eu ficaria feliz se desse uma olhada no Kalyx nesse momento, e se conhece uma solução melhor, agradeceria se me contasse em uma GitHub Issue.

pnpm add @kalyx/react

No Playground do site de documentação, você pode testar os sete pickers e mudar as configurações de locale e timezone por conta própria.

No começo, eu me concentrava mais nos resultados e no processo do que em desempenho e custo. Como as respostas da IA tinham muitas falhas, era preciso verificá-las; e, como queríamos resultados rápidos, muita gente, inclusive eu, comprava mais tokens ou migrava para um plano superior quando eles acabavam. Eu também fiz isso. (Nos primeiros meses, nem sequer prestei atenção em quanto gastava com tokens.)

Com o tempo, porém, fiquei cada vez mais atento ao uso de tokens. Para as pessoas, a mensalidade pesava; para as empresas, aumentavam as preocupações com custos de pessoal e operação. Em MCP e function calling expliquei o protocolo que conecta agentes a sistemas externos; em Quatro camadas de inteligência de código, as ferramentas de busca de código e o GitHub Trending; e em Arquivos de contexto, os arquivos de regras que os agentes leem. Assim, meus textos até aqui se concentraram mais em quais ferramentas existem e em como usá-las bem. Ainda considero isso importante, mas acredito que o custo acabará sendo a maior dúvida.

Expliquei os princípios dos tokens — o que são, como o BPE os cria e o que ocorre dentro do transformador quando prompt caching reduz o preço — em Como os tokens funcionam. Com essa base, veremos primeiro como os custos são cobrados e onde surgem ineficiências, depois reuniremos padrões comprovados de economia. Os principais padrões vêm acompanhados do uso de tokens que medi eu mesmo executando a mesma tarefa com estratégias diferentes.

De onde vêm os custos dos tokens?

Vamos examinar de forma breve e objetiva como esses custos surgem e como são cobrados.

Todo texto enviado — prompt de sistema, definições de ferramentas, histórico e mensagens do usuário — vira tokens de entrada; a resposta do modelo vira tokens de saída. Para o modelo, cada chamada é uma entrada inédita. Não importa se a conversa aconteceu ontem ou há um minuto: uma nova chamada envia novamente todo o conteúdo como entrada. (Esse fato simples é o núcleo do custo: o modelo não tem memória e nós contamos tudo outra vez.)

Há mais uma variável. Reenviar do zero a parte estática de chamadas repetidas é caro, então os principais provedores de LLM criaram prompt caching. A entrada estática é armazenada uma vez e, nas chamadas seguintes, os tokens lidos da cache custam muito menos. (Em Como os tokens funcionam, tratei do mecanismo: como o BPE cria tokens e como a cache reutiliza a KV cache do transformador. Aqui, o foco é como isso vira custo.)

Tokens de entrada, tokens de saída e tokens de cache

Vejamos quatro campos do objeto usage devolvido pelo SDK da Anthropic.

• input_tokens parte da entrada enviada, excluindo leituras da cache
• output_tokens resposta gerada pelo modelo
• cache_creation_input_tokens tokens armazenados pela primeira vez nesta chamada
• cache_read_input_tokens tokens relidos de uma cache existente

Cada campo recebe uma tarifa diferente. Tokens de saída são os mais caros; os lidos da cache, os mais baratos. Segundo a documentação da Anthropic, a leitura custa 0,1 vez a tarifa base de entrada, exatamente 10%. A escrita custa 1,25 vez com TTL (Time To Live, período de validade da cache) de cinco minutos e 2 vezes com TTL de uma hora. Paga-se um pouco mais na primeira chamada e economiza-se 90% a partir da segunda.

A cache também tem restrições pouco conhecidas. O mínimo varia por modelo e até por versão da mesma família. Sonnet 4.6 e Opus 4.8 exigem 1.024 tokens, Opus 4.7 exige 2.048, e Haiku 4.5 e os antigos Opus 4.5/4.6 exigem 4.096. Um prompt menor não é armazenado mesmo com cache_control, sem aviso. Uma solicitação aceita até quatro pontos de interrupção cache_control, e a cache é lida na ordem hierárquica tools → system → messages. Assim, mudar uma definição de ferramenta no início invalida toda a cache posterior.

O desconto de 90% vem da reutilização da KV cache do transformador entre chamadas, mecanismo detalhado em Como os tokens funcionam. Para custos, lembre apenas isto: só há cache hit quando o prefixo é idêntico. Portanto, coloque o conteúdo estático primeiro e o conteúdo dinâmico, que muda a cada chamada, por último. Até um caractere de timestamp no início invalida toda a cache seguinte.

Surge uma pergunta: “Mas a entrada muda a cada turno; a cache não deveria quebrar quase sempre?” Não. A conversa não é reescrita como um bloco novo: ela usa uma estrutura append que preserva o conteúdo acumulado na frente e acrescenta apenas a nova fala no fim. Prompt de sistema, ferramentas, perguntas e respostas anteriores permanecem intactos; só a nova pergunta é anexada. Comparando as entradas desde o início, a primeira diferença estará no final. A entrada completa muda, mas o prefixo sobrevive. (A cache só quebra em todos os turnos num projeto ruim que insere valores dinâmicos na frente. Claude Code e opencode mantêm o início fixo e anexam ao fim; o usuário não precisa configurar nada. Erros de digitação também não afetam a cache, pois ficam no fim, fora do prefixo já armazenado.)

Comparação entre provedores de IA

Ao reunir as tabelas oficiais de Anthropic, OpenAI e Google de junho de 2026, o padrão fica claro. (Valores em USD por milhão de tokens, com foco em modelos comuns na programação.)

Nos três provedores, a saída custa cinco a seis vezes mais que a entrada. Respostas longas elevam rapidamente o custo, mesmo dizendo a mesma coisa. Na mesma faixa, os preços dos modelos variam de três a seis vezes. A conta revela três princípios: pedir saídas curtas, usar um modelo mais barato quando ele entregar a mesma resposta e armazenar entradas estáticas em cache. (Se um contexto estático de 10 mil tokens for reutilizado 100 vezes, custa $5 na tarifa base do GPT-5.5 e $0.50 como leitura de cache. A economia é $4.5 e, como quase não há acréscimo de escrita inicial, o retorno começa na segunda chamada.)

Diferenças entre mecanismos de cache

Mesmo com descontos parecidos, o projeto interno varia por provedor. Entender isso facilita definir políticas.

A filosofia aparece claramente. Anthropic exige marcação explícita, cobra um pequeno prêmio inicial (1,25 vez) e depois dá grande desconto. O controle do prefixo torna previsível a taxa de leitura. OpenAI automatiza tudo: entradas com 1.024 tokens ou mais são armazenadas sem custo, mas há menos controle. Google oferece os dois métodos e cobra armazenamento quando a cache é gerida explicitamente. Cache implícita serve para reutilização breve e frequente; explícita com armazenamento, para grandes contextos mantidos por uma hora ou mais.

Definições de ferramentas e tokenizadores

Duas outras variáveis têm impacto surpreendente.

A primeira são as definições de ferramentas. Com vários servidores MCP, cada chamada inclui nomes e esquemas de parâmetros — mediremos depois quanto isso aumenta o custo —. Mesmo com ferramentas idênticas, trocar apenas o modelo altera o gasto. A documentação da Anthropic mostra que o prompt de ferramentas varia: com tool_choice: auto, Sonnet 4.6 e Haiku 4.5 usam cerca de 497 tokens, Opus 4.7 usa 675 e Opus 4.8 cai para 290. Antes do model routing, vale verificar quanto o modelo expande essas definições.

A segunda é a eficiência do tokenizador, que divide texto em unidades processáveis. O mesmo texto pode gerar contagens diferentes. o200k_base da OpenAI usa bem menos tokens que cl100k_base em idiomas não ingleses; a Anthropic afirma que, com o novo tokenizador desde Opus 4.7, o mesmo texto pode ser cobrado como até 35% mais tokens do que nos modelos anteriores. Escolher apenas pela tarifa deixa o custo vazar pela ineficiência. A comparação correta é tarifa × quantidade esperada.

A diferença é marcante em coreano. Com dois tokenizadores da OpenAI, frases técnicas em inglês tiveram a mesma contagem, mas cl100k_base usou 31–43% mais tokens em coreano que o200k_base. Um parágrafo de 167 caracteres virou 169 tokens no antigo: mais tokens que caracteres. Em média, cada caractere consumiu mais de um token.

O antigo fragmenta o coreano no nível de bytes; o novo agrupa trechos frequentes como “개발” e “입니다” em um token. Mesmo com tarifa igual, uma carga em coreano pode custar mais de 1,5 vez só pela eficiência do tokenizador.

Surge então a pergunta: “Onde exatamente estamos criando toda essa ineficiência?”

Padrões comuns de desperdício de tokens

O desperdício é comum mesmo quando acreditamos usar bem a IA. Estes são os padrões que observei no meu trabalho e entre outros desenvolvedores.

Servidores MCP e ferramentas demais

Vale repetir: depois de conectar Linear, GitHub, Notion, Figma, Slack ou Sentry, raramente removemos algo. Esquemas ociosos inflam a entrada em toda chamada. Para lidar com isso, Claude Code ativa MCP Tool Search: no início entram apenas nomes e descrições; o esquema completo só é carregado quando a ferramenta é chamada.

Medi a diferença com 27 ferramentas MCP de uma sessão — 10 do Serena, oito de quatro integrações OAuth do claude.ai, duas do Figma e sete do agentmemory — e enviei a mesma mensagem em duas configurações. Uma não tinha MCP; a outra tinha as 27 conectadas, mas indisponíveis ao modelo. Ambas fizeram zero chamadas de ferramentas.

Com mesma pergunta, modelo e sentido da resposta, a entrada foi de 41 → 10,335 (+10,294) tokens no Opus 4.7. O custo subiu de $0.0048 → $0.0563, cerca de 12 vezes; o aumento de 250 vezes na entrada adicionou +783ms de latência de prefill. O mais marcante é ser um custo pago em todas as chamadas mesmo sem usar MCP naquele turno. Tool Search evita isso. (Desde a medição, removo continuamente servidores que não uso.)

Acúmulo de contexto e Lost in the Middle

Levar uma conversa longa adiante aumenta a entrada e reduz a precisão. O estudo “Lost in the Middle”, da equipe de Liu em Stanford, quantificou uma curva em U: informações no começo ou fim são recuperadas melhor; no meio, pior. Gastamos mais para receber resposta inferior. Como o self-attention cresce com o quadrado dos tokens, a atenção por token se dilui com o contexto. O meio enfraquece primeiro porque os dados de treinamento tendem a concentrar informação importante nas extremidades.

Mais a fundo, a forma como o modelo trata a “posição” traz duas tendências que enterram o meio. A intuição é simples.

Primeiro, o modelo escuta mais os tokens próximos. RoPE (Rotary Position Embedding), usado pela maioria dos modelos abertos, enfraquece a conexão conforme a distância aumenta, um decay effect. Tokens distantes recebem menos atenção.

Segundo, o modelo envia atenção demais ao primeiro token. O softmax obriga a distribuir 100% da atenção; quando não há foco específico, o excedente costuma ir ao primeiro token. Isso é attention sink. (A equipe de Xiao no MIT quantificou o fenômeno no StreamingLLM. Não indica informação importante, mas um ralo para atenção excedente.)

As duas tendências concentram atenção nas pontas — tokens recentes e primeiro token — e enfraquecem o meio. Não é bug de um modelo. LLaMA, Mistral e Qwen usam RoPE; Claude e GPT provavelmente usam mecanismos semelhantes. Lost in the middle é um viés da arquitetura moderna.

Hoje, o fenômeno também é chamado de context rot. Uma análise da Chroma submeteu 18 modelos — incluindo GPT-4.1, Claude 4, Gemini 2.5 e Qwen3 — à mesma tarefa NIAH (needle in a haystack). Quando a entrada passou de 10k para mais de 100k tokens, a precisão caiu 20–50%, conforme o modelo. Todos pioraram; Claude caiu mais lentamente. A Anthropic descreve isso como um “orçamento de atenção” derivado do n², consumido entre tokens. Contexto leve reduz custos e preserva precisão.

Chamar subagent sem critério

Delegar tudo porque subagent é útil também é uma armadilha. Ele começa num contexto separado e paga novamente o prompt de sistema e as ferramentas. Delegar um shell curto ou uma consulta simples de git pode custar mais no arranque do que economiza no contexto principal. Segundo a Anthropic, um agente usa cerca de quatro vezes os tokens de um chat; um sistema multiagente, quinze vezes. A delegação só vale se a precisão justificar isso.

O mesmo vale para MCP. Cada ferramenta ativa adiciona seu esquema ao prompt em todo turno e custa mesmo sem uso. “Ativar tudo por garantia” parece seguro, mas os dados discordam.

Testei precisão e custo com perguntas sobre o reconciler do facebook/react v19 em três cenários:

• Sem ferramentas
• Uma ferramenta (CodeGraph, Serena, ripgrep ou grep puro)
• As quatro ferramentas conectadas juntas

Três resultados se destacaram. (Recall indica quão completas foram as respostas corretas.)

• Sem ferramentas obteve recall médio de 0,31, confirmando o valor das ferramentas.
• Somente Serena (LSP) atingiu 1,00 por $0.38, a opção individual mais eficiente.
• As quatro ferramentas reduziram o recall a 0,89 e elevaram o custo a $0.47. Em perguntas multi-hop, o resultado igualou CodeGraph sozinho (0.78 / 0.88): o modelo preferiu uma ferramenta e herdou suas fraquezas.

O princípio é igual para subagent e ferramentas: o custo extra só importa se elevar a precisão. Escolher a ferramenta adequada ao domínio é mais barato e preciso que ativar tudo por garantia.

Então, quais métodos realmente economizam tokens?

Formas comprovadas de economizar tokens

Cada padrão ataca um eixo: reduzir a entrada, baixar o preço da mesma entrada ou entregar o trabalho a um modelo mais barato. Vejamos cada um.

Prompt caching

É o efeito mais imediato. Leituras custam 0,1 vez a entrada. Após o prêmio de escrita de 1,25 vez na primeira chamada, a seção estática pode ser reutilizada desde a segunda por um décimo do preço.

O ponto essencial é que as partes quase idênticas entre chamadas — ferramentas, trechos de código e contexto RAG — são exatamente as armazenáveis. O benefício continua se não forem misturadas com conteúdo dinâmico, como a pergunta atual ou um novo resultado. Ao chamar a API, agrupar blocos estáticos na frente e dinâmicos atrás entrega quase toda a economia. Claude Code e opencode fazem isso automaticamente.

Agrupar trabalho assíncrono com Batch API

Se a chamada não precisa terminar imediatamente, Batch API é a forma mais simples de reduzir a tarifa. Anthropic, OpenAI e Google dão 50% de desconto em entrada e saída em troca de entregar em até 24 horas. Na Anthropic, a maioria termina em uma hora, mas o SLA é 24 horas. A chamada não muda e o preço cai pela metade.

Esse desconto se multiplica com outros. A Anthropic afirma que cache e lote se acumulam: tarifa padrão × 0.5 (lote) × 0.1 (leitura) = 0.05, ou 5% na parte estática. Os descontos se multiplicam, não se somam.

Calculei 100 tarefas com 10 mil tokens estáticos, 500 dinâmicos e mil de saída, usando tarifas do Opus 4.8 e quatro estratégias.

Cache reduz 57%, lote 50%, e ambos até 79%. A multiplicação ocorre na entrada estática. (Saída não entra na cache e recebe apenas o desconto de lote; quanto maior sua parcela, menor a redução total. Quanto maior a parte estática, maior o efeito.) Indexação noturna, avaliação antes da publicação, extração de dados e relatórios não exigem alguém diante da tela.

Nem tudo pode esperar. Batch não serve à sessão principal de um agente ou chat interativo, onde a latência tem valor. Dividir entre “preciso agora” e “preciso até o próximo expediente” pode cortar a conta pela metade.

Isolar trabalho verbose com um subagent

Nas palavras da documentação do Claude Code, um subagent “opera em sua própria janela isolada; chamadas e resultados intermediários permanecem nele e só a mensagem final volta ao pai”. Delegar uma tarefa verbose deixa só um resumo limpo no contexto principal. Segundo o texto da Anthropic sobre context engineering, mesmo gastando dezenas de milhares de tokens, ele costuma devolver apenas 1.000–2.000 tokens ao pai.

Uma tarefa verbose produz muitos tokens para obter uma resposta de uma linha. Executar testes, pesquisar documentação e analisar logs são exemplos.

Mas subagent não reduz automaticamente o custo total. Agentes usam cerca de quatro vezes mais tokens que chats; sistemas multiagente, quinze vezes. O subagent protege a precisão e o contexto principal ao retirar saídas verbose; não é mágica. Delegue apenas se a economia de limpeza superar o arranque. Tarefas curtas saem mais baratas no pai.

O domínio também importa. No teste interno da Anthropic, um líder Opus 4 com subagent Sonnet 4 melhorou 90,2% sobre um Opus 4 sozinho. Porém, domínios onde agentes compartilham contexto ou têm muitas dependências são inadequados — e programação é exatamente assim. Pesquisa explora rumos independentes; código vive num grafo de dependências. (Em programação, um agente com um subagent isolado de exploração pode ser um padrão mais seguro.)

compact e progressive disclosure

O comando /compact resume toda a conversa e reinicia com contexto novo. A compressão é semântica: preserva trabalho atual e mudanças recentes e remove saídas repetitivas. /clear apaga tudo; /compact deixa um resumo. Perto de 95% da janela, auto-compact faz o mesmo. Organizar sessões longas interrompe o acúmulo.

Por dentro, /compact é a última etapa de uma pipeline automática. Segundo “Dive into Claude Code”, query.ts verifica cinco etapas antes de cada chamada.

• Budget Reduction corta partes de saídas que excedem o limite.
• Snip remove o histórico antigo no eixo temporal.
• Microcompact comprime finamente preservando a consciência da cache.
• Context Collapse reprojeta históricos enormes em read-time para reduzir dimensões.
• Auto-Compact aciona compressão semântica aos 95% como último recurso.

As primeiras são leves e baratas; as últimas, pesadas e eficazes. Uma estratégia não resolve toda pressão. Chamar /compact antecipa a etapa final.

A mesma ideia aparece em Skills. /compact reduz o acumulado; as três fases de /skills evitam acumulá-lo.

Segundo a Anthropic, uma skill carrega em três fases. Nome e descrição — cerca de 100 tokens — entram no início. O corpo (SKILL.md, menos de 5 mil tokens) só entra quando acionado. Scripts e recursos executados via bash retornam apenas a saída; o código não entra. Dezenas de skills quase não aumentam o contexto inicial.

Model routing: a mesma resposta com um modelo mais barato

A entrada do Opus 4.8 custa cinco vezes a do Haiku 4.5. Usar o maior modelo para busca, exploração ou resumo simples é desperdício. Encaminhar por dificuldade — Haiku → Sonnet → Opus — e reservar Opus ao raciocínio pesado virou padrão. RouteLLM, da LMSYS, preservou 95% da qualidade do GPT-4 reduzindo chamadas fortes a 14%, embora o benchmark fosse de raciocínio geral.

O ecossistema se firmou: OpenRouter, Martian e NotDiamond; no código aberto, RouteLLM, LiteLLM e Bifrost. Na Anthropic, a seleção do Agent SDK, o campo model do subagent — Explore usa Haiku — e /model apoiam routing. Mas as APIs não escolhem sozinhas pela dificuldade: executam o modelo indicado. Routing automático existe em produtos como Cursor Auto, ChatGPT auto e openrouter/auto. Para economizar, é preciso construir uma camada.

Adicionar qualquer router não é a resposta. Auto Router, que troca o modelo por chamada, conflita com prompt caching. A cache efêmera exige mesmo modelo e prefixo; mudar a chave causa miss. Perde-se o desconto de 90% e a economia de routing volta em misses. Por isso OpenRouter recomenda stickiness com session_id.

Na prática, não classifique toda chamada; divida estaticamente por tarefa. O campo model segue isso: Explore sempre usa a faixa Haiku; revisão, Opus. Cada faixa repete modelo, prompt e ferramentas e acumula sua própria cache. “Routing virou padrão” significa ramificação estática “coordenador + executor”, não classificador por chamada. Assim routing e cache coexistem.

Cursor Composer 2.5

Outra opção é usar um agente como Cursor. Composer 2.5, lançado em 18 de maio de 2026, usa o checkpoint aberto Kimi K2.5 da Moonshot AI e foi ajustado para código. A Cursor afirma desempenho comparável ao Claude Opus 4.7 por cerca de um décimo do preço. A tarifa é $0.50 de entrada e $2.50 de saída, uma ordem abaixo dos $5.00 e $25.00 do Opus 4.8.

Como o benchmark é da própria Cursor, não convém tomar o número absoluto como definitivo. A tendência importa: um modelo menor especializado em código pode se aproximar de um modelo geral de fronteira e reduzir custos em uma ordem de grandeza. É uma tendência clara de 2026.

O mais interessante é que ele também reduz a própria quantidade de tokens de entrada quando projetado junto ao IDE. Composer e Cascade consomem eficientemente arquivo atual, vizinhos e símbolos indexados, reduzindo pedidos extras e operações de grep e leitura. A tarifa cai dez vezes e a contagem também diminui, então a economia real pode ser maior.

Levar o contexto para fora do contexto

Uma tendência de 2026 é carregar “apenas o necessário, quando necessário”. A Anthropic chama isso de contexto just in time (JIT). Em vez de incluir tudo, o agente mantém referências leves e busca o material por ferramentas quando precisa. Claude Code lê sob demanda com glob e grep em vez de carregar toda a base.

memory tool e context editing, lançados com Sonnet 4.5, seguem a mesma filosofia. A “memória” de memory tool não é o histórico da sessão nem um CLAUDE.md escrito por alguém e carregado no início. memory tool é uma ferramenta com que o modelo escreve e lê arquivos diretamente.

A interface permite criar, ler, atualizar e excluir arquivos num diretório da infraestrutura do usuário. O modelo trata notas como sistema de arquivos. Isso cria memória persistente fora da janela entre sessões, enquanto o usuário controla armazenamento e retenção. A memória de sessão é volátil dentro; esta permanece fora. context editing faz o inverso: perto do limite, remove resultados antigos de ferramentas sem interromper a conversa, permitindo que o agente rode mais.

Na avaliação da Anthropic, as duas ferramentas melhoraram o desempenho em 39%; context editing sozinho, 29%. Numa busca web de 100 turnos, o consumo caiu 84%. (São benchmarks do fornecedor, mas a direção é clara: esvaziar o contexto importa mais.) Isso segue a mesma lógica da pipeline de cinco etapas de /compact. A diferença é que /compact reduz o interior do contexto, enquanto memory tool cria armazenamento exterior; os dois são complementares.

Conclusão

No fim, a economia se resume a três eixos: enviar menos para o mesmo trabalho, pagar menos pela mesma entrada e entregar a mesma resposta a um modelo mais barato. Prompt caching, Batch API, isolamento com subagent, /compact, memory tool, context editing, model routing e modelos especializados apenas atacam eixos diferentes. Em 2026, o foco migra de preencher o contexto para esvaziá-lo e selecioná-lo — context engineering. Como mostra context rot, contexto leve melhora custo e precisão.

Não há resposta única. Cada equipe trabalha de um jeito, e uma mesma pessoa tem custos diferentes ao escrever texto ou código. Mas, num ecossistema rápido, supor que “o padrão de ontem ainda funciona hoje” é arriscado. Acompanhar modelos, ferramentas e preços e validá-los num pequeno POC do próprio fluxo talvez seja a economia mais duradoura. Recomendo revisar a própria contabilidade de tokens. (Para entender a raiz, leia também BPE e KV cache em Como os tokens funcionam.)

Resta uma pergunta: depois de esvaziar e selecionar contexto, o que vem? O foco avança ao sistema de agentes inteiro: como operá-lo (projeto do harness), medir se funcionou (eval) e confiná-lo quando falha (containment). Quando a postura “meça com um POC” deste artigo escala ao sistema, ela vira exatamente eval. Tratarei disso em Além do contexto.

Até agora, escrevi principalmente sobre como usar bem as ferramentas de IA, quais estão em alta e por quê. Mas, ao preparar o texto sobre como economizar tokens, percebi novamente algo importante: para falar em reduzir custos, primeiro é preciso entender “o que é um token e como ele é cobrado”, mas eu nunca havia explicado essa base de forma adequada. (Enquanto escrevia o guia de economia, a parte sobre o funcionamento dos tokens cresceu o bastante para virar um artigo próprio.)

Este texto, portanto, estabelece os fundamentos antes das técnicas de economia. Vamos ver o que exatamente é um token, se não é palavra nem caractere (BPE); em que formato ele entra no modelo (embedding); por que a saída custa mais que a entrada (prefill/decode); de onde, dentro do Transformer — a arquitetura da rede neural — vem a redução de preço do prompt caching (KV cache); e por que um contexto mais longo fica mais caro (o custo quadrático da atenção). Para medidas práticas, depois deste artigo continue em Como economizar tokens.

Token não é palavra nem caractere

Comecemos pelo fato mais básico: token não é palavra nem caractere. É uma unidade de um vocabulário que o modelo cria ao comprimir sequências de caracteres frequentes nos dados de treinamento.

Nossa intuição ao perguntar “quantas palavras há nesta frase?” é diferente da forma como o modelo divide o texto. Ele agrupa em uma unidade as combinações de caracteres que aparecem juntas com frequência e segmenta o texto recebido de acordo com esse vocabulário. Por isso, uma palavra pode corresponder a um único token ou ser dividida em vários.

O algoritmo que constrói esse vocabulário é o BPE, uma base comum a praticamente todos os LLMs modernos.

O algoritmo BPE

BPE (Byte Pair Encoding, ou codificação de pares de bytes) expande o vocabulário ao fundir repetidamente o par de símbolos adjacentes mais frequente em um novo símbolo.

O curioso é que ele não nasceu para o processamento de linguagem natural. Philip Gage propôs o BPE pela primeira vez em 1994 como técnica de compressão de dados. O método substituía o par de bytes mais frequente por um byte não utilizado nos dados e armazenava as regras de substituição separadamente em uma tabela.

A equipe de Sennrich, da Universidade de Edimburgo, levou a ideia para o problema de vocabulário na tradução neural. No artigo “Neural Machine Translation of Rare Words with Subword Units”, publicado em 2015 e apresentado na ACL 2016, os pesquisadores usaram BPE para superar a incapacidade de um vocabulário fixo de lidar com palavras raras ou desconhecidas. Em vez de memorizar palavras inteiras, elas são representadas como combinações de fragmentos subword menores; assim, até uma palavra fora do vocabulário pode ser codificada com partes conhecidas.

O processo em si é surpreendentemente simples.

1. No início, cada caractere individual é um token.
2. Encontra-se no corpus o par de tokens adjacentes que aparece com maior frequência.
3. O par é fundido em um novo token, que substitui todas as ocorrências desse par no corpus.
4. Os passos 2 e 3 são repetidos até o vocabulário alcançar o tamanho desejado.

Assim, embora no começo cada caractere seja um token, combinações frequentes como “th”, “the” e “tion” acabam fundidas em tokens únicos. Quanto mais comum o padrão, maior a chance de ele se tornar um bloco maior.

A família GPT vai além e usa BPE em nível de bytes. Primeiro, o texto é convertido em um fluxo de bytes UTF-8; depois, aplica-se BPE. Isso permite começar com um vocabulário-base de apenas 256 itens — um para cada byte possível — e ainda codificar qualquer texto representável em UTF-8 sem tokens desconhecidos. Seja um emoji, um ideograma chinês ou um símbolo especial, sempre existe pelo menos uma representação no nível de byte.

Mesmo texto, quantidades diferentes de tokens

Por causa dessa estrutura, o mesmo texto pode gerar números de tokens muito diferentes dependendo do tokenizer, a ferramenta que divide o texto escrito por pessoas em unidades que o modelo consegue processar. Conforme a forma de treinamento do vocabulário, a mesma frase pode ser quebrada em partes menores ou em blocos maiores.

O material publicado pela OpenAI com o GPT-4o mostra bem essa diferença. O novo tokenizer o200k_base da família GPT-4o representa o mesmo texto com menos tokens que o cl100k_base da família GPT-4. Em inglês, ele é apenas cerca de 1,1 vez mais eficiente, mas a diferença cresce em outros idiomas. Nos exemplos curtos publicados, a contagem caiu aproximadamente 1,4 vez em chinês e japonês, 1,7 vez em coreano e até 2,9 vezes em hindi. (Para quem usa coreano, é interessante como a diferença entre gerações de tokenizer se mostra muito mais perceptível do que em inglês.)

Em uma visão mais ampla, também há diferenças entre os próprios idiomas. Na análise de Yennie Jun com cl100k_base, frases com o mesmo sentido quase sempre usaram menos tokens em inglês, enquanto idiomas com sistemas de escrita próprios tenderam a usar mais. Hindi e bengali podem consumir cinco vezes mais tokens que o inglês; birmanês, mais de dez vezes. Coreano e chinês também são tokenizados em mais partes que o inglês, embora sem chegar a esses extremos.

Daí surge uma consequência prática importante. Ao adotar um novo tokenizer a partir do Opus 4.7, a Anthropic declarou na documentação oficial de preços que “o mesmo texto pode ser cobrado como até 35% mais tokens do que nos modelos anteriores”. Mesmo que o preço por token permaneça igual, a conta cresce na mesma proporção da quantidade de tokens. Uma comparação honesta entre modelos precisa considerar não apenas a tarifa, mas a tarifa multiplicada pelo número esperado de tokens.

Mas, quando esses tokens segmentados entram no modelo, eles não entram como caracteres ou palavras literais. Então, em que formato um token serve de entrada para o modelo?

Como os tokens entram no modelo

Redes neurais não trabalham diretamente com texto. No fim das contas, o modelo só calcula com números — mais precisamente, vetores, que são conjuntos de números. Por isso, antes de entrar no modelo, os tokens passam por várias etapas que os transformam em valores numéricos.

A sequência é esta.

1. Texto → tokens: um tokenizer BPE divide o texto em fragmentos de token.
2. Token → token ID: cada token é mapeado para um ID inteiro que indica sua posição no vocabulário. Por exemplo, se " the" for o 1.234º token, seu ID será 1234.
3. Token ID → vetor de embedding: o ID seleciona a linha correspondente da matriz de embeddings. Essa matriz é uma tabela enorme de tamanho vocabulary size × model dimension (d_model); cada token ID corresponde a uma linha, isto é, a um vetor. Podemos imaginar esse vetor como coordenadas que carregam o “significado” do token.
4. Adicionar informação posicional: sozinha, a autoatenção não sabe a ordem dos tokens. Em outras palavras, veria “eu gosto de você” e “você eu gosto de” como a mesma coisa. Portanto, injeta-se informação posicional em cada vetor de token para informar a ordem da sequência.

Como isso soa abstrato apenas em palavras, incluí uma ferramenta interativa para explorar as quatro etapas. Ao mudar a frase ou clicar em um token, é possível acompanhar o caminho do ID ao vetor de embedding e ver a informação posicional ser adicionada até formar o vetor de entrada final. (Só algumas dimensões são exibidas, mas vale lembrar que o vetor real do GPT-4 tem 12.288.)

A dimensão do modelo (d_model) é o comprimento do vetor que representa um token. No artigo original do Transformer, o valor era 512, mas nos LLMs atuais é muito maior. (Até o Llama 2 7B usa 4.096 dimensões.) Uma dimensão maior representa diferenças sutis de significado com mais riqueza, porém também aumenta o volume de cálculo e memória.

A forma de injetar informação posicional também mudou ao longo das gerações. O Transformer original somava aos embeddings vetores de posição construídos com funções seno e cosseno. Já o RoPE (Rotary Position Embedding), hoje padrão de fato em LLMs abertos, injeta a posição relativa durante o cálculo da atenção ao rotacionar os vetores Query e Key. (O mecanismo muda, mas o objetivo é o mesmo: dar ao Transformer noção de ordem.)

Em resumo, o fluxo é texto → tokens → token IDs → vetores de embedding (+ informação posicional) → entrada do Transformer. A “contagem de tokens” da fatura corresponde à segunda etapa desse fluxo: quantos tokens resultaram da segmentação do texto.

Agora sabemos como os tokens são criados e em que formato entram no modelo. Mas, quando são processados, por que entrada e saída custam tão diferente, e como reduzir o custo de enviar repetidamente a mesma entrada?

Por que a entrada é barata e a saída é cara

Quem já trabalhou com tokens provavelmente se perguntou: nas tabelas de preços, tokens de saída custam várias vezes mais que tokens de entrada. Na Anthropic, em todos os modelos, a tarifa de saída é exatamente cinco vezes a de entrada. (No Opus, são $5 de entrada e $25 de saída; no Haiku, $1 e $5.) Se é o mesmo token, por que o preço muda conforme entra ou sai?

A resposta é que o modelo processa tokens de maneiras completamente diferentes na entrada e na saída. A inferência de um LLM tem duas etapas.

• prefill (processamento da entrada): processa todos os tokens da instrução de uma só vez e em paralelo. Com 1.000 ou 10.000 tokens, a GPU percorre todos em conjunto e calcula os vetores K/V (Key/Value) de cada token. O cálculo total é grande, mas o paralelismo proporciona boa eficiência por token.
• decode (geração da saída): gera os tokens da resposta sequencialmente, um de cada vez. Depois de produzir um token, ele é acrescentado à entrada e o próximo é gerado. O ciclo se repete até o fim da resposta.

Essa assimetria cria a diferença de custo. Segundo a análise de desempenho de inferência da Databricks, prefill é uma etapa limitada por computação, enquanto decode é limitada pela largura de banda da memória. Durante decode, para produzir cada token, é preciso reler da memória da GPU todos os pesos do modelo; no entanto, cada passagem gera apenas um token. Grande parte da enorme capacidade de cálculo da GPU fica ociosa. (Nas palavras da Databricks, você paga para manter a GPU ligada sem usar a computação disponível.)

Em outras palavras, tokens de entrada são processados juntos com eficiência no prefill paralelo, enquanto tokens de saída precisam ser extraídos de forma ineficiente, um a um. Fatores comerciais como demanda e margem também podem afetar os preços, mas essa ineficiência de decode compõe a explicação técnica. Portanto, “manter a saída curta” não é apenas uma dica genérica de economia: reduz diretamente a etapa mais cara.

Existe alguma forma de tornar decode ao menos um pouco menos ineficiente? É aqui que entra o KV cache.

Como o armazenamento em cache reduz o preço

Prompt caching armazena uma vez a entrada estática para que as chamadas seguintes a leiam por um preço bem menor. Segundo a documentação oficial da Anthropic, uma leitura custa 0,1 vez a tarifa-base de entrada, ou exatamente 10%. A escrita custa 1,25 vez com TTL (Time To Live, período de validade dos dados armazenados) de cinco minutos e 2 vezes com TTL de uma hora. Paga-se um pouco mais na primeira chamada e economiza-se 90% a partir da segunda.

Mas como o preço pode cair 90%? E por que a exigência de que “o prefixo coincida exatamente” é tão rigorosa? As duas respostas ficam claras quando olhamos dentro do Transformer.

KV cache

Ao processar tokens de entrada, o modelo cria os vetores Query/Key/Value (Q/K/V) correspondentes. A autoatenção calcula pontuações de atenção pelo produto escalar de Query e Key e usa essas pontuações para produzir uma soma ponderada dos valores. É o cálculo que determina quanto um token deve “consultar” cada um dos outros.

É justamente aí que a etapa de decode mencionada antes se torna problemática. Para gerar cada novo token, o modelo precisa dos K/V de todos os tokens anteriores. Recalculá-los do zero em todas as etapas repetiria o mesmo trabalho indefinidamente.

O KV cache elimina essa duplicação. Ele armazena os K/V já calculados e, ao gerar um novo token, lê e reutiliza os K/V anteriores, em vez de calculá-los novamente. Dentro de uma sequência, o custo de gerar mais um token cai de O(n²), que recalcularia toda a sequência a cada etapa, para O(n), que apenas lê os dados armazenados. (A rigor, esse é o custo por etapa; a ideia central é simples: não recalcular o que já foi calculado.) É também por isso que decode é limitado pela memória: cada etapa precisa reler o KV cache da memória.

Reutilização entre chamadas

Se o KV cache foi criado para acelerar decode dentro de uma resposta, prompt caching propõe reutilizar essa estrutura de memória não apenas dentro de uma chamada, mas também entre uma chamada e a próxima.

Os K/V de um prefixo estático — como uma instrução de sistema, definições de ferramentas ou trechos de código cujo início muda pouco — permanecem na memória da GPU por um TTL de cinco minutos ou uma hora. Se a chamada seguinte começar com o mesmo prefixo, o modelo ignora por completo o cálculo desses K/V e os lê diretamente dos dados armazenados. Mais precisamente, o preço dos tokens de entrada não cai por mágica: o trabalho de GPU necessário para calculá-los deixa de existir. A redução de 90% reflete a computação evitada.

Ao entender o mecanismo, também fica clara a exigência de correspondência exata do prefixo. Um acerto de cache é determinado pela comparação do hash cumulativo do prefixo. Como a autoatenção é causal, mudar um único token anterior altera os K/V de todos os tokens seguintes. Basta colocar uma marca temporal no começo da instrução: o valor muda a cada chamada, o hash deixa de coincidir e todos os dados armazenados depois desse ponto são invalidados.

A Anthropic lê os dados armazenados na hierarquia tools → system → messages. Por isso, mudar uma única definição de ferramenta no início invalida tudo o que vem depois. A conclusão é simples: conteúdo estático deve ficar no começo; conteúdo dinâmico, que muda a cada chamada, no fim.

O armazenamento em cache também tem restrições menos conhecidas. A quantidade mínima de tokens que pode ser armazenada varia por modelo e até por versão da mesma família. Uma instrução abaixo desse limite não é armazenada, sem qualquer aviso, mesmo com esse recurso habilitado. (Como esses mínimos e as políticas de cada provedor afetam diretamente o planejamento de custos, eu os detalho junto às tabelas de preços no guia de economia de tokens.)

Por que a janela de contexto impõe um limite de tokens

O último conceito indispensável é a janela de contexto: o número máximo de tokens que um modelo aceita de uma vez. Entender por que esse limite existe também esclarece o conhecido aviso de que “um contexto mais longo custa mais”.

A chave está na estrutura de cálculo da autoatenção. A atenção faz cada token consultar todos os outros uma vez. Com n tokens, existem n × n pares; portanto, a computação e a memória da autoatenção crescem com o quadrado do comprimento n da sequência. Ao dobrar o número de tokens, o custo da atenção quadruplica. (Vale esclarecer que não é o modelo inteiro que tem custo O(n²), mas a etapa de atenção.)

As estimativas da Hugging Face mostram como esse crescimento quadrático é acentuado. Com atenção padrão, sem otimização, apenas armazenar a matriz de pontuações exige cerca de 50 MB para uma entrada de 1.000 tokens, aproximadamente 19 GB para 16.000 tokens e quase 1 TB para 100.000.

O KV cache também ocupa memória proporcionalmente ao número de tokens. À medida que o contexto cresce, os K/V que precisam ser mantidos se acumulam linearmente. No fim, o limite da janela de contexto é uma fronteira física definida pelo modelo: além dela, memória e computação se tornam inviáveis.

Por isso, carregar uma conversa longa sem alterações não significa apenas somar tokens de entrada. O custo da atenção cresce ao quadrado e, quanto mais a contagem se aproxima do limite, menor também é a precisão com que o modelo lida com a informação. (Essa perda de precisão está diretamente ligada à degradação do contexto, abordada no guia de economia; manter o contexto enxuto beneficia tanto o custo quanto a qualidade das respostas.)

Conclusão

Em conjunto, o funcionamento dos tokens se resume a alguns fatos simples. Token é uma unidade de vocabulário criada pelo BPE ao agrupar padrões frequentes; depois de ser mapeado para um token ID, ele vira um vetor de embedding e entra no modelo. A entrada é processada de uma só vez com prefill paralelo, enquanto a saída é mais cara porque precisa ser extraída token por token; o KV cache reduz essa ineficiência ao reutilizar os K/V. O armazenamento reduz o preço não por mágica, mas porque o Transformer evita recalcular K/V já obtidos, e a exigência rigorosa de um prefixo idêntico decorre diretamente dessa estrutura. Por fim, um contexto mais longo custa mais porque o custo da atenção cresce com o quadrado do número de tokens.

Com essa base, a economia dos tokens fica muito mais clara. Encurtar a saída, organizar a instrução para preservar os dados armazenados, manter o contexto enxuto e migrar para um modelo mais barato quando ele oferece a mesma resposta são estratégias apoiadas nesses princípios. Se você chegou até aqui para entender o mecanismo, recomendo continuar no guia de economia de tokens e ver como essas ideias reduzem custos reais.

Este texto é para quem tem CLAUDE.md, AGENTS.md, SKILL.md e .cursor/rules acumulados no mesmo projeto e não sabe ao certo quando cada um é lido nem o que escrever nele. Ao final, você conhecerá as diferenças entre esses arquivos, como os agentes os carregam e um critério apoiado por um estudo da ETH Zurich: escrever apenas as informações que o agente não consegue inferir.

Trabalho como desenvolvedor frontend e uso Claude no dia a dia. Com isso, em algum momento surgiu um CLAUDE.md na raiz do projeto, ao lado havia um AGENTS.md criado por alguém, um .cursorrules continuava esquecido em algum canto e eu cheguei até a criar uma pasta .claude/skills/ seguindo um artigo que encontrei por aí. (Quando me dei conta, havia uns cinco arquivos com conteúdos parecidos.)

Agentes sem memória persistente

Os agentes de programação com IA têm uma limitação fundamental: não possuem memória persistente. Toda sessão começa do zero, e na conversa seguinte eles não se lembram de convenções combinadas ontem nem da estrutura de pastas explicada uma hora antes. Os arquivos de contexto são o mecanismo mais simples para resolver esse problema. Se o projeto tiver um arquivo lido automaticamente no início de cada sessão, não será necessário repetir sempre as mesmas explicações.

O problema é que cada ferramenta criou seu próprio arquivo a partir da mesma ideia. Claude Code lê CLAUDE.md; Cursor, .cursorrules (que hoje está deprecated, e a recomendação é usar .cursor/rules); GitHub Copilot, .github/copilot-instructions.md; e OpenAI Codex, AGENTS.md. Quando uma equipe usa várias ferramentas, acaba tendo de copiar o mesmo conteúdo para quatro lugares diferentes.

CLAUDE.md

CLAUDE.md é um arquivo que o Claude Code lê automaticamente no início da sessão. Segundo a documentação oficial da Anthropic (code.claude.com/docs/en/memory), o Claude Code procura CLAUDE.md nos três níveis abaixo.

• Memória do usuário (~/.claude/CLAUDE.md): valores-padrão globais aplicados a todos os projetos da máquina
• Memória do projeto (CLAUDE.md na raiz do projeto): versionada no Git e compartilhada por toda a equipe
• Memória local (CLAUDE.md em um subdiretório): carregada adicionalmente apenas ao trabalhar naquele diretório

Se os três níveis existirem, Claude lê todos e os concatena (concatenate). Ele não escolhe apenas um por ordem de prioridade; a estrutura se parece com a cascade do CSS, em que o conteúdo mais específico é acrescentado por cima. (É uma mesclagem, não um override.) Portanto, espalhar regras sobre o mesmo assunto por vários níveis pode gerar conflitos. (A documentação oficial da Anthropic afirma que o comportamento em caso de conflito não é garantido.)

Há um detalhe frequentemente ignorado: todos os arquivos CLAUDE.md encontrados ao subir do diretório de trabalho atual até a raiz do repositório são lidos. Assim, ao trabalhar em packages/ui/ dentro de um monorepo, tanto o CLAUDE.md da raiz quanto packages/ui/CLAUDE.md são carregados. (Isso é poderoso, mas também significa que o contexto pode crescer sem que ninguém perceba.)

AGENTS.md

AGENTS.md é um padrão criado para resolver a proliferação de arquivos específicos de cada ferramenta descrita acima. Em dezembro de 2025, a OpenAI doou esse padrão à Agentic AI Foundation (AAIF), vinculada à Linux Foundation. Segundo o anúncio da Linux Foundation, a AAIF foi cofundada por Anthropic, Block e OpenAI, e seus projetos fundadores são três: o MCP da Anthropic (o protocolo que conecta agentes a sistemas externos), o goose da Block e o AGENTS.md da OpenAI. O site oficial (agents.md) afirma que mais de 60 mil repositórios open source já adotam esse arquivo.

A lista de ferramentas compatíveis deixa isso ainda mais claro. OpenAI Codex, Google Jules, VS Code, GitHub Copilot, Cursor, JetBrains Junie, Aider, Devin, Zed, Factory, Warp, goose, opencode, Amp, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, Ona, Windsurf e Augment Code estão entre as muitas ferramentas com suporte. O GitHub Copilot passou a oferecer suporte nativo a AGENTS.md em agosto de 2025. Um detalhe interessante é que o suporte nativo do Claude Code a AGENTS.md ainda está no estado de active feature request. Para o Claude Code, CLAUDE.md continua sendo o arquivo principal.

Mesmo sendo chamado de padrão, é razoável desconfiar se ele está realmente sendo adotado. A evidência mais forte é o dogfooding (quando quem cria um padrão também o utiliza).

• A raiz da branch canary de Vercel/Next.js contém um AGENTS.md. Na verdade, trata-se de um link simbólico para CLAUDE.md, cujo conteúdo inclui a estrutura do monorepo, iterações de 1–2 segundos com pnpm --filter=next dev, orientações de testes para Turbopack e Webpack, o script pr-status e regras para variáveis de ambiente e secrets. O fato de create-next-app ter passado a gerar AGENTS.md e CLAUDE.md juntos em novos projetos faz parte do mesmo movimento.
• O próprio repositório OpenAI/codex mantém seu AGENTS.md.

Do ponto de vista estratégico, a abordagem que vem se consolidando é esta: manter AGENTS.md como single source of truth e reduzir CLAUDE.md ao mínimo, deixando nele apenas uma linha que referencia AGENTS.md e instruções específicas do Claude Code. Isso elimina duplicações e, como o Claude Code lê os dois arquivos, não há perda de informação.

SKILL.md

SKILL.md tem uma natureza diferente dos dois arquivos anteriores. Enquanto CLAUDE.md e AGENTS.md são instruções persistentes, sempre presentes no contexto, uma Skill é uma capacidade on-demand, invocada apenas quando necessária.

Uma Skill é organizada como uma pasta. Dentro dela ficam um arquivo SKILL.md, scripts executados pela Skill e documentos Markdown adicionais. Claude só carrega essa pasta quando a tarefa atual corresponde ao description da Skill. Esse mecanismo é chamado de progressive disclosure (divulgação progressiva), conceito estabelecido por Jakob Nielsen na área de UX em 1995. A técnica reduz a carga cognitiva e os erros ao deslocar funções avançadas ou pouco usadas para telas secundárias, permitindo que o usuário se concentre em uma tarefa de cada vez. No contexto das Claude Skills, o termo se refere ao mecanismo de “trazer o corpo da Skill para o contexto apenas quando necessário”. O resultado é uma economia drástica no custo da janela de contexto.

O frontmatter de SKILL.md possui alguns campos próprios.

• description: descreve em quais situações a Skill é necessária e funciona como gatilho para o modelo decidir se deve invocá-la
• allowed-tools: restringe as ferramentas disponíveis dentro da Skill (por exemplo, "Read, Glob, Grep, Bash(python:*)")
• disable-model-invocation: true: impede que o modelo invoque a Skill; somente o usuário pode acioná-la por um comando slash. É usado em operações com efeitos colaterais, como deploy e commit
• user-invocable: false: oculta a Skill do menu de comandos slash do usuário; apenas Claude pode invocá-la de forma autônoma como conhecimento de apoio

Claude Skills foi lançado simultaneamente no Claude.ai, Claude Code, API e Agent SDK em 16 de outubro de 2025. Em 18 de dezembro de 2025, a Anthropic publicou a própria especificação das Skills como padrão aberto (agentskills.io). Simon Willison chegou a avaliá-las dizendo: “Skills are awesome, maybe a bigger deal than MCP”. O motivo é que seu formato é drasticamente mais simples que o MCP e, ao mesmo tempo, resolve o custo da janela de contexto por meio de progressive disclosure.

O MCP (Model Context Protocol), com o qual as Skills foram comparadas aqui, é um protocolo padrão que conecta o agente a sistemas externos como Slack, GitHub ou um banco de dados para que ele possa chamá-los. Se os arquivos de contexto tratam do que informar ao agente, o MCP trata do que permitir que ele faça. Como o MCP difere de function calling está explicado à parte em MCP e function calling.

As ferramentas que reduzem o custo de o agente encontrar o código relevante (Repomix, Aider, CodeGraph, Serena) reduzem custos diferentes conforme a profundidade com que entendem o código. Essa comparação está explicada à parte em Quatro camadas de inteligência de código.

Arquivos de outras ferramentas

O .cursorrules do Cursor foi deprecated a partir da versão 0.43. A recomendação oficial atual é criar vários arquivos dentro do diretório .cursor/rules/, cada um com a extensão .mdc. Cada arquivo .mdc possui um frontmatter YAML.

• description: usado pelo agente para avaliar a relevância da regra
• globs: faz auto-attach quando um arquivo correspondente ao padrão é incluído na conversa
• alwaysApply: quando true, inclui a regra obrigatoriamente em todas as conversas (nesse caso, globs é ignorado)

O GitHub Copilot evoluiu em uma direção semelhante. Instruções válidas para todo o repositório ficam em .github/copilot-instructions.md; quando é necessário definir escopo por caminho, criam-se arquivos .github/instructions/*.instructions.md, usando a chave applyTo: no frontmatter para especificar o glob. (O Copilot code review passou a oferecer suporte oficial a path-scoped instructions em setembro de 2025.)

As demais ferramentas também convergem para padrões parecidos. A tabela abaixo resume o cenário.

O CONVENTIONS.md do Aider é especialmente interessante. Como a documentação oficial informa que o arquivo inteiro é incluído no contexto a cada solicitação, ela determina explicitamente: “mantenha-o com no máximo 200 linhas”. (Pode-se dizer que o Aider reconheceu essa limitação cedo e a comunicou diretamente aos usuários.)

MEMORY.md

Além dos arquivos anteriores, outro padrão aparece com frequência cada vez maior: MEMORY.md. Não é um padrão oficial, mas uma convenção que surgiu organicamente na comunidade para registrar decisões e erros ao longo do tempo.

## 2026-04-10
Pages Router에서 App Router로 이전. 신규 라우트는 App Router 컨벤션 사용.
 
## 2026-04-22
Prisma 쿼리 결과에 optional chaining 쓰지 말 것 — null은 if-check로 명시적 처리.
(이전에 옵셔널 체이닝으로 null을 흘려보내 프로덕션 이슈 발생.)

Se CLAUDE.md e AGENTS.md registram as regras vigentes no momento, MEMORY.md registra a história de por que essas regras foram criadas. (Eles se complementam; um não substitui o outro.)

Como o agente lê esses arquivos

Até aqui, vimos quais arquivos existem. Mas há uma pergunta que, surpreendentemente, costuma ficar de fora: para onde e de que forma exatamente o agente lê esses arquivos? Entender esse mecanismo ajuda a compreender com mais clareza o resultado da ETH Zurich apresentado adiante — o de que arquivos de contexto não são seguidos tão bem quanto se esperaria.

Primeiro, um fato importante: CLAUDE.md não é um system prompt; ele é injetado como user message. A documentação oficial da Anthropic afirma o seguinte:

O conteúdo de CLAUDE.md é entregue como uma mensagem do usuário após o prompt do sistema, e não como parte do próprio prompt do sistema. Claude o lê e tenta segui-lo, mas não há garantia de conformidade estrita.

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance.

Ou seja, ele não é uma regra obrigatória, mas um “contexto de referência”. Para impor um comportamento específico, o guia oficial recomenda usar um mecanismo separado, como um hook PreToolUse.

A ordem de carregamento se acumula de broad → specific. Mais precisamente: managed policy (configuração da organização) → global do usuário (~/.claude/CLAUDE.md) → projeto (./CLAUDE.md) → local (./CLAUDE.local.md). Dentro do mesmo diretório, CLAUDE.md vem antes de CLAUDE.local.md. É possível aproveitar o fato de que a instrução mais próxima é lida por último para fazer regras mais específicas terem maior peso, graças ao recency bias dos LLMs.

Outro ponto interessante é a sintaxe @import. Ao escrever @path/to/file em qualquer lugar do corpo de CLAUDE.md, esse arquivo é expandido naquele ponto e carregado junto. A profundidade recursiva máxima é de 4 hops, e caminhos relativos são resolvidos a partir do arquivo que contém o import. Por isso, a recomendação oficial é usar @AGENTS.md como ponte. Se CLAUDE.md ficar quase vazio, contendo apenas a linha @AGENTS.md, o Claude Code também lerá AGENTS.md naturalmente. (Na situação atual, em que CLAUDE.md ainda não oferece suporte nativo a AGENTS.md, essa é a solução alternativa mais limpa.)

Também vale examinar os tokens. CLAUDE.md não possui um limite explícito de tokens, portanto, se existir, será carregado por inteiro. Ainda assim, a recomendação oficial é de no máximo 200 linhas por arquivo. Acima de 200 linhas, a documentação diz “consume more context and may reduce adherence”. Curiosamente, no Claude 4.x, apenas habilitar o tool use adiciona automaticamente +346 tokens a um special system prompt (com tool_choice: auto). O contexto vaza sem que se perceba.

O Cursor funciona de outra maneira. As regras em .cursor/rules/*.mdc operam em quatro modos.

• Always Apply: incluída obrigatoriamente em todos os chats; ignora globs/description
• Apply Intelligently (Agent Requested): o agente lê description, avalia a relevância e usa a regra quando necessário
• Apply to Specific Files (Auto Attached): ativada quando um arquivo que corresponde ao padrão glob entra no contexto
• Apply Manually: invocada explicitamente pelo usuário com @rule-name

Outras ferramentas funcionam de formas diferentes. O OpenAI Codex percorre o caminho da raiz do repositório Git até o cwd, coleta todos os AGENTS.md e os injeta imediatamente antes do prompt do usuário. Já o GitHub Copilot insere .github/copilot-instructions.md em uma prioridade intermediária da janela de contexto: “depois do edit context e das explicit references, mas antes de open files loosely related”. Mesmo quando usam o mesmo arquivo AGENTS.md, ferramentas diferentes podem carregá-lo em momentos distintos, com prioridades e regras de mesclagem diferentes; portanto, não há garantia de que três ferramentas enxerguem esse arquivo exatamente da mesma maneira.

Mas resta uma pergunta fundamental: por que o modelo segue apenas parte das instruções presentes no contexto? Dizer apenas que “as instruções são longas” não basta. Por trás desse fenômeno existe uma limitação estrutural dos LLMs.

Alucinação e esquecimento do contexto

Se você já viu um agente de IA confundir o contexto da conversa ou esquecer mais adiante algo dito claramente no início, isso também é uma forma de alucinação (Hallucination). Em geral, pensamos primeiro em alucinação como “inventar fatos inexistentes”, mas academicamente ela se divide em três tipos. O survey de 2023 da equipe de Yue Zhang (“Siren's Song in the AI Ocean”) os classifica como conflito com a entrada (gerar algo diferente do que o usuário informou explicitamente), conflito com o contexto (contradizer algo que o próprio modelo gerou antes) e conflito factual (discordar do conhecimento de mundo). Ignorar instruções de arquivos de contexto pertence ao primeiro tipo, não ao terceiro. Ao processar a entrada, o modelo trata parte das informações como se elas “não existissem”.

O problema mais fundamental é que essa alucinação não pode ser eliminada por completo. Uma equipe da Universidade Nacional de Singapura demonstrou isso matematicamente por meio da teoria da aprendizagem. Nenhum LLM consegue aprender todas as funções computáveis e, portanto, enquanto for usado como solucionador de problemas de propósito geral, inevitavelmente alucinará em algum ponto.

O efeito da posição também é importante. Pesquisadores de Stanford demonstraram experimentalmente que o modelo consulta melhor informações relevantes quando elas estão no início ou no fim da janela de contexto, enquanto o desempenho cai bastante quando ficam enterradas no meio. Isso se relaciona diretamente aos arquivos de contexto. Pela ordem de carregamento, CLAUDE.md entra em algum ponto intermediário e, quanto mais longa fica a conversa, mais suas instruções são empurradas para o “meio” do contexto. Isso também se conecta ao outro lado do recency bias mencionado anteriormente: a faixa intermediária do efeito primazia–recência é a mais vulnerável.

Ao reunir esses fenômenos, surge uma imagem única. Um arquivo de contexto é apenas um texto adicional inserido fora do sistema antes do primeiro turno do usuário. Não é um mecanismo que impõe decisões ao modelo, mas apenas mais um bloco de tokens despejado na janela de contexto. Quanto maior ele for — e quanto mais longa ficar a conversa —, mais suas instruções serão empurradas para o “meio” e menos consultadas. O resultado da ETH Zurich apenas quantificou essa limitação estrutural.

O estudo da ETH Zurich

Muitas pessoas devem ter pensado: “Então é melhor colocar o máximo possível nesses arquivos, certo?”. Um estudo recente confrontou diretamente essa intuição: a pesquisa da ETH Zurich mencionada ao longo da seção anterior.

Em fevereiro de 2026, uma equipe da ETH Zurich publicou o artigo “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?”. Foram avaliadas 138 tarefas reais de engenharia de software em Python no benchmark AGENTBENCH e no SWE-bench Lite, usando quatro agentes: Claude Code (Sonnet-4.5), Codex (GPT-5.2 / GPT-5.1 mini) e Qwen Code. Os resultados foram inesperados.

• Arquivos de contexto gerados automaticamente por LLMs reduziram a taxa de sucesso das tarefas em cerca de 0,5% no SWE-bench Lite e 2% no AGENTBENCH
• Mesmo arquivos escritos manualmente por pessoas trouxeram apenas uma pequena melhora média, de cerca de 4%
• A adição de arquivos de contexto aumentou o custo de inferência em mais de 20% por instância
• Em modelos mais poderosos (GPT-5.2), o efeito dos arquivos de contexto foi ainda menor (quanto mais forte o modelo, maior seu conhecimento paramétrico e maior a chance de o contexto adicional virar ruído)

Houve, porém, uma exceção: quando uma ferramenta não convencional era especificada. Por exemplo, ao mencionar no contexto o gerenciador de pacotes Python uv, a frequência de uso de uv pelo agente passou de 0,01 para 1,6 vez por instância — um aumento de aproximadamente 160 vezes.

A recomendação do Aider mencionada antes — “200 linhas”, “como entra sempre no contexto, mantenha curto” — é uma orientação prática. Já o estudo da ETH Zurich demonstrou quantitativamente que “arquivos de contexto longos reduzem o desempenho”. Na minha opinião, as implicações práticas dessa pesquisa são as seguintes.

• Arquivos de contexto enormes gerados automaticamente podem causar mais danos do que benefícios. Se padrões de código, arquitetura e workflow forem todos espremidos em um CLAUDE.md de 300 linhas, o agente seguirá apenas parte e ignorará o restante. Essa inconsistência pode produzir resultados piores do que não ter contexto algum.
• O que precisa ser registrado são as informações que não podem ser inferidas: ferramentas não convencionais, convenções específicas do projeto e falhas do passado. O modelo já conhece as boas práticas gerais de programação.
• Use AGENTS.md como fonte única; deixe em CLAUDE.md apenas instruções curtas específicas da ferramenta; e separe workflows detalhados em Skills.

E então?

Os arquivos de contexto mudam de uma ferramenta para outra no nome, no local e no momento em que são lidos. Só neste artigo vimos CLAUDE.md, AGENTS.md, SKILL.md, regras do Cursor, copilot-instructions.md e MEMORY.md, e qual ferramenta oferece suporte a qual arquivo continua mudando. Decorar uma lista de arquivos fica obsoleto rapidamente.

Por isso, meu objetivo neste artigo não foi recomendar um formato de arquivo específico, mas desenvolver um olhar capaz de enxergar como os agentes leem esses arquivos. Depois de entender por que CLAUDE.md é injetado como user message, por que cada ferramenta lê o mesmo AGENTS.md de um jeito diferente e por que as instruções se enfraquecem no meio do contexto, fica mais fácil olhar para um novo formato de arquivo de contexto e perceber rapidamente “quando ele é carregado e com que força atua”.

No fim, o que permanece é uma intuição transmitida pelo estudo da ETH Zurich: o modelo já sabe muitas coisas. Encher um arquivo de contexto com todo tipo de informação não faz o agente segui-lo melhor. É preferível manter apenas o que o modelo provavelmente não conhece — convenções específicas do projeto, ferramentas não convencionais e erros do passado — e remover o restante. Escrever um arquivo de contexto longo e escrevê-lo bem são problemas diferentes.

Em vez de ampliar CLAUDE.md para centenas de linhas agora mesmo, recomendo que quem leu este artigo investigue ao menos uma vez quando, onde e com que força as ferramentas que já usa leem esse arquivo. Acredito que essa compreensão cria uma base estável, independentemente de como os formatos de arquivo mudarem.

Este texto é para desenvolvedores que já viram um agente gastar tokens repetindo grep e leituras de arquivo em uma base de código grande, e que estão em dúvida sobre qual ferramenta adicionar, como Repomix, CodeGraph ou Serena. Essas ferramentas se dividem em quatro camadas de acordo com a profundidade com que entendem o código (context packing, o repo map do tree-sitter, o grafo de conhecimento e o LSP), e cada camada reduz o custo de busca em um ponto diferente. Para o grafo de conhecimento, incluo o benchmark do seu criador; para as outras três camadas, medições feitas no próprio repositório deste blog.

Desde que vi o codegraph no GitHub Trending e o instalei por conta própria, sempre que encontro uma ferramenta nova fico curioso para saber por qual princípio ela economiza tokens. Muitas das ferramentas deste texto também conheci primeiro no GitHub Trending, que costumo ver por semana, filtrando por TypeScript e Python.

Ferramentas de inteligência de código

Antes de alterar qualquer código, um agente primeiro procura onde está o código relevante. É um loop: busca com grep, lê arquivos, filtra e faz grep de novo. No benchmark do CodeGraph que veremos mais adiante, o lado que respondia sem a ferramenta usou até 43 tool calls para uma única pergunta. As ferramentas de inteligência de código são tentativas de reduzir esse custo de busca.

Mas "custo" não aponta para uma coisa só. Os tokens que o modelo processou, o número de tool calls e os tokens que continuam na context window depois que o trabalho termina se movem separadamente. Em cada camada, este texto olha qual dos três ela reduz.

Divido essas tentativas nas quatro camadas (tiers) abaixo, de acordo com quão profundamente cada ferramenta entende o código. Não há uma classificação estabelecida no setor; o agrupamento é meu. Todos os valores medidos neste artigo foram obtidos em 2026-10-08 no commit 36e5cfa deste repositório, e os tokens foram contados com o o200k_base do tiktoken. Os valores diferem dos do tokenizador do Claude, então servem para comparar, não como números absolutos.

Empacotamento de contexto

A solução mais simples parte da ideia: "colocar tudo em uma única context window". Não constrói grafo nem faz indexação. Simplesmente serializa o repositório inteiro em um bloco de texto e o entrega inteiro ao modelo.

A ferramenta representativa é o Repomix. Seu formato de saída padrão é XML, e o README traz um link para a documentação da Anthropic sobre tags XML. Ele tem CLI, versão web, extensão de navegador e servidor MCP.

O ponto forte do GitIngest é dispensar instalação. Se você trocar github.com por gitingest.com em uma URL do GitHub, o repositório inteiro vira uma única página de texto. O code2prompt (criado por Mufeed VH), uma CLI em Rust, permite mudar o formato de saída com templates.

O rtk (rtk-ai/rtk) segue uma direção um pouco diferente. Enquanto as ferramentas acima empacotam o repositório inteiro de uma vez, o rtk comprime a saída dos comandos de CLI que o agente executa. É um único binário feito em Rust, registrado nos hooks de vários agentes, como Claude Code, Cursor, Copilot, Gemini CLI e Codex, de modo que, quando o agente chama git status, ele executa rtk git status no lugar. Aplica filtering, grouping, truncation e deduplication a mais de 100 comandos. O hook do rtk tem como alvo apenas as tool calls do Bash. Read, Grep e Glob do Claude Code passam direto.

O tamanho da redução precisa ser lido com cuidado. O README do rtk diz que reduz a saída do Bash em até 90%, e logo acrescenta que isso não significa reduzir a conta em 90%. Do lado do modelo, a saída de um comando é parte dos tokens de entrada, e os tokens de entrada são parte da conta, então a redução se dilui a cada etapa. O número que o site oficial destaca é 56% em média, nos comandos que o rtk reescreve. Se as ferramentas acima reduzem o texto que entra, o rtk reduz o texto que volta como resultado das tool calls.

O limite desta camada é que repositórios grandes esbarram no teto de tokens. Empacotar só os 109 arquivos do src/ deste blog já dá 94.596 tokens. Isso ainda cabe na janela, mas um repositório com milhares de arquivos chegaria ao limite logo. O Repomix responde a isso com --compress. Segundo o README, ele usa Tree-sitter para manter as assinaturas de funções e classes e descartar os corpos de implementação.

# repomix 1.18.1, 이 리포 커밋 36e5cfa, 2026-10-08
npx -y repomix@1.18.1 src -o out.xml              # Total Tokens: 94,596 tokens
npx -y repomix@1.18.1 src --compress -o out.xml   # Total Tokens: 30,320 tokens

A redução foi de 68%. Os comentários ficam, então visit-counter.ts, que tem JSDoc longo, só foi de 1.642 para cerca de 1.220 tokens, 26% a menos. A versão comprimida mantém as instruções import e as assinaturas, mas as chamadas dentro dos corpos das funções somem. Dá para ver no texto qual arquivo importa o quê, mas não dá para perguntar quem chama quem. Por isso a fronteira entre esta camada e a próxima está menos em a ferramenta ver a sintaxe do que em poder ser consultada sobre relações.

Mapa do repositório com tree-sitter

A camada seguinte usa o tree-sitter para analisar a estrutura do código, mas sem subir um servidor de índice separado.

O que o tree-sitter, a ferramenta em que esta camada se apoia, constrói é uma CST (Concrete Syntax Tree), uma árvore que representa a estrutura do código-fonte. A documentação oficial do tree-sitter também diz que ele constrói uma concrete syntax tree. É uma árvore que mantém como nós até os parênteses e a pontuação, e é com ela que as ferramentas abaixo trabalham.

O tree-sitter é um gerador de parsers de código aberto e uma biblioteca de parsing incremental (incremental). A code navigation do GitHub usa o tree-sitter. Como ele só refaz o parsing da parte editada, mudar uma linha no editor não refaz o parsing do arquivo inteiro; só corrige a parte da árvore que mudou. Essa vantagem é dos editores, onde as edições não param. O Aider, logo abaixo, mantém um cache baseado na hora de modificação dos arquivos para não refazer o parsing dos que não mudaram.

O Aider, uma ferramenta de programação em par com IA usada no terminal, é o exemplo representativo dessa abordagem. O Aider usa o tree-sitter para extrair de cada arquivo as definições e referências de funções, classes e métodos. Depois monta um grafo com os arquivos como nós. Quando o arquivo A referencia um identificador definido no arquivo B, surge uma aresta de A para B.

Para escolher os arquivos importantes desse grafo, o Aider usa o PageRank. O PageRank é um algoritmo que dá mais pontuação a um nó quanto mais links ele recebe e quanto mais pesados eles são. O Aider usa uma variante chamada personalized PageRank, que inclina a pontuação para os nós escolhidos. Depois coloca no orçamento de tokens as definições e assinaturas dos arquivos mais bem classificados.

O que entra no orçamento muda com a conversa atual. No repomap.py do Aider, o peso de uma aresta é a raiz quadrada do número de referências multiplicada por um fator. Identificadores mencionados na conversa recebem 10x, e identificadores em camelCase, snake_case ou kebab-case com 8 ou mais caracteres também 10x. Os que começam com _ e os definidos em mais de 5 arquivos recebem 0,1x cada, e as arestas que saem dos arquivos adicionados agora ao chat recebem 50x. Os arquivos do chat, os mencionados na conversa e aqueles cujo caminho ou nome de arquivo coincide com um identificador da conversa também recebem pontuação de personalization no PageRank.

O orçamento também não é fixo. A documentação do Aider dá 1k como padrão de --map-tokens, mas o código corta um oitavo do limite de entrada do modelo para um valor entre 1.024 e 4.096. E, quando não há arquivos no chat, amplia até --map-multiplier-no-files (padrão 2) vezes. Conferi isso com o src/ deste repositório. A versão 0.86.1 que executei e o commit linkado acima têm o mesmo código de ranking. Os maps impressos foram contados com o200k_base, incluindo as três linhas de texto de orientação que o Aider adiciona.

# aider-chat 0.86.1, 리포 루트에서 시작한다, 2026-10-08
mkdir /tmp/aidermap && cp -R src /tmp/aidermap/ && cd /tmp/aidermap && git init -q && git add -A && git commit -qm init
# 키는 더미 값이다. --show-repo-map 은 map 만 출력하고 LLM 을 부르지 않는다
export OPENAI_API_KEY=dummy
aider_map() { uvx --python 3.12 --from aider-chat==0.86.1 aider --no-check-update --analytics-disable --no-gitignore --model gpt-4o "$@"; }
aider_map --show-repo-map                                              # Repo-map: using 4096 tokens
aider_map --map-tokens 1024 --show-repo-map                            # Repo-map: using 1024 tokens
aider_map --map-tokens 1024 --show-repo-map src/lib/filter-posts.ts    # 이 파일을 채팅에 올린 상태

O limite de entrada do gpt-4o é de 128k, então um oitavo foi cortado para 4.096, e com o chat vazio o map saiu dentro do dobro disso. Ao adicionar um arquivo ao chat, o map encolheu até caber no orçamento; dos 27 arquivos anteriores só 10 ficaram, e PostList.tsx e SearchModal.tsx entraram como novos. Um repo map não é um resumo fixo do repositório, e sim um trecho ajustado à conversa daquele momento.

Há mais uma ferramenta que vale citar nesta camada: o ast-grep (ast-grep/ast-grep). É uma CLI de busca estrutural e rewrite baseada em tree-sitter, que casa nós da árvore sintática em vez de texto. Por exemplo, o padrão console.log($A) pega todas as chamadas a console.log com um único argumento, não importa como estejam as quebras de linha ou os espaços. O que ele pega é a mesma estrutura sintática. Ele não sabe o tipo de $A nem de onde vem o nome console. Também existe um servidor ast-grep-mcp, com o qual dá para fazer um agente usar busca estrutural em vez de grep de texto.

Knowledge Graph

A terceira camada vai um passo além. Ela faz o parsing de toda a base de código de antemão, constrói um grafo de conhecimento e o salva em disco; depois o agente envia consultas a esse grafo salvo. O exemplo mais comentado é uma ferramenta chamada CodeGraph.

A estrutura que o README do CodeGraph descreve é simples. Ele faz o parsing do código com tree-sitter para extrair símbolos, arestas e informações de arquivos, e os salva em um banco de dados SQLite local. A busca por nome passa pelo índice FTS5 do SQLite. O agente consulta esse grafo via MCP. Nos passos que o README descreve não aparece nenhum LLM. Por isso entendo que essa extração é determinística (deterministic), ou seja, que o mesmo código sempre dá o mesmo resultado.

Se um LLM resume o código para montar o grafo, os resultados podem variar até para o mesmo código, e alucinações podem se infiltrar. Já ao fazer o parsing direto da árvore sintática, as relações entre símbolos são extraídas apenas pelas regras da gramática da linguagem, sem espaço para esse tipo de interpretação.

O FTS5 (SQLite Full-Text Search 5), que aparece aqui, é uma extensão de busca de texto completo oferecida pelo SQLite como tabela virtual. Segundo a documentação do SQLite, ela faz parte da amalgamation desde a 3.9.0 (2015-10-14); você cria uma tabela com CREATE VIRTUAL TABLE ... USING fts5(...) e consulta com o operador MATCH. Dá para manter um índice de texto completo em um único arquivo SQLite sem subir um mecanismo de busca separado como o Elasticsearch.

Mas ser determinístico não é o mesmo que ser completo. O mesmo README registra o reconhecimento de rotas de frameworks que dependem de convenção e reflexão entre 74,1% para Django e 83,9% para ASP.NET, e chama isso de limite da análise estática (honest static-analysis ceiling). O mesmo código dá o mesmo resultado, mas a esse resultado podem faltar arestas.

O benchmark foi medido pelo próprio CodeGraph. A nova medição de 2026-08-05 no mesmo README rodou o Claude Opus 4.8 em modo headless e fez uma pergunta de arquitetura a cada um de 7 repositórios de código aberto. O lado com o CodeGraph MCP ativado reduziu o custo médio em 44%, os tokens processados em 62% e as tool calls em 88%. Essa nova medição impediu os dois lados de chamar a CLI codegraph pelo Bash. Em um ambiente de medição sem esse bloqueio, o lado sem a ferramenta encontrou e usou a CLI em 26 de 28 execuções, e o README deixa claro que os números publicados antes foram obtidos sem esse bloqueio.

O tamanho da economia não acompanhou o tamanho do repositório. Nas perguntas em que o lado sem a ferramenta usou de 28 a 43 tool calls, o custo caiu de 57 a 78%, e no Gin, que terminou em 7, ficou praticamente igual. O VS Code, com cerca de 11k arquivos, deu 71%, e o Excalidraw, com cerca de 640, 78%. O README atribui isso à quantidade de busca que cada pergunta exigiu. Como há uma única pergunta por repositório, leio daí apenas a direção.

O README também registra um número na direção oposta. Os tokens processados caem, mas ao fim de uma sessão de vários turnos, os resultados de retrieval que continuam na context window são cerca de 80% maiores do lado do CodeGraph no conjunto dos 7 repositórios. A diferença varia por repositório; só no VS Code são 67k contra 18k tokens, cerca de 3,7 vezes. Ele devolve o texto-fonte denso de uma vez, e esse texto permanece na janela. O CodeGraph reduziu as tool calls e os tokens processados ao preço de deixar mais coisa na janela.

O Cursor seguiu outro caminho e depois mudou de rumo. A indexação descrita no post do blog do Cursor de janeiro de 2026 não era um grafo sintático, e sim busca semântica baseada em embeddings vetoriais. Ela dividia os arquivos em chunks localmente, sincronizava com o servidor por meio de hashes de Merkle tree e transformava os chunks em embeddings para a busca semântica. Em julho de 2026, um Community Support Engineer do Cursor respondeu no fórum: "Semantic/embeddings indexing is being turned down in favor of grep-based retrieval". No mesmo tópico, outro membro da equipe escreveu que, à medida que os modelos ficaram bons em usar grep, o antigo caminho de busca semântica deixou de ajudar de forma significativa. Hoje a documentação do Cursor diz que o Instant Grep constrói e consulta seu índice na sua máquina e não guarda embeddings da sua base de código para busca.

LSP

A última camada depende diretamente de um servidor de linguagem. Se o tree-sitter sabe "que um símbolo existe", o LSP sabe "o que esse símbolo é".

O LSP (Language Server Protocol) é um protocolo aberto baseado em JSON-RPC que padroniza a comunicação entre editores e ferramentas de análise de linguagem (autocompletar, ir para a definição, encontrar referências, refatoração etc.). Em 2016, Microsoft, Red Hat e Codenvy anunciaram a colaboração. A ideia central é "não reimplementar um analisador de linguagem para cada editor; ter um servidor por linguagem e fazer todos os editores consultá-lo". O rust-analyzer e o pyright do Python são servidores LSP, enquanto o TypeScript usa o typescript-language-server, que envolve em LSP o tsserver, que fala um protocolo próprio.

O Serena (oraios/serena) é um servidor MCP desta camada. Em 2026-10-08 tem 30.093 stars, e o repositório foi criado em março de 2025. A ideia central do Serena cabe em uma linha: mostrar ao agente o código como símbolos. Suas ferramentas principais incluem find_symbol, find_referencing_symbols e get_symbols_overview. Dá para escolher um de dois backends. O padrão é um servidor de linguagem que implementa LSP (gratuito/código aberto); a outra opção é um plugin pago que usa a análise de código da IDE da JetBrains (com teste gratuito).

Medir neste repositório mostra de onde vem a diferença. Procurei os usos de isHiddenPost (src/lib/filter-posts.ts:12), que filtra os posts privados, de duas formas. O lado de texto é o grep.

# 커밋 36e5cfa, 2026-10-08. 이 글도 같은 이름을 담고 있어 content/ 는 뺐다
git grep -n isHiddenPost -- ':!content'   # 16줄, 파일 9개
git grep -n -C1 isHiddenPost -- ':!content'   # 같은 16곳을 앞뒤 1줄과 함께

No lado do LSP, foi chamado o find_referencing_symbols do Serena. A busca de referências do LSP pergunta por posição (arquivo, linha e coluna), não por nome, então essa ferramenta também recebe ao mesmo tempo name_path, o nome do símbolo, e relative_path, o arquivo onde está a definição. Em vez de subir o Serena como servidor MCP, a ferramenta foi chamada diretamente do Python no mesmo commit.

# serena 3b99f8b, 커밋 36e5cfa, 2026-10-08. 리포 루트에서 실행한다
# uvx --python 3.12 --from git+https://github.com/oraios/serena@3b99f8b024dafd58c962ea6e74f37c8a730ef532 python refs.py
from serena.agent import SerenaAgent
from serena.config.serena_config import SerenaConfig
from serena.tools.symbol_tools import FindReferencingSymbolsTool
agent = SerenaAgent(project=".", serena_config=SerenaConfig().with_headless_mode_overrides())
agent.execute_task(lambda: None)  # 언어 서버가 뜰 때까지 기다린다
tool = agent.get_tool(FindReferencingSymbolsTool)
print(agent.execute_task(lambda: tool.apply(name_path="isHiddenPost", relative_path="src/lib/filter-posts.ts")))

A saída é uma única linha de JSON. Este é só o primeiro item. Os números de linha começam em 0.

{"src/lib/filter-posts.ts": {"Function": [{"name_path": "filterPublishedPosts", "body_location": {"start_line": 22, "end_line": 24}, "content_around_reference": "...  22:export function filterPublishedPosts(posts: Post[]): Post[] {\n  >  23:  return posts.filter(post => !isHiddenPost(post))\n...  24:}"}]}, ...

O Serena devolveu 10 referências. Ele deixa de fora a definição em filter-posts.ts:12 e, para as linhas de import de três arquivos, devolve o próprio arquivo como símbolo (File). As 11 posições de código que o grep encontrou são essas 10 mais a linha da definição. Esse nome é único no repositório, então o grep não deixou de fora nem acrescentou nenhuma posição de código. As 5 posições a mais que o grep encontrou eram frases de documentos que explicam essa função: o CLAUDE.md da raiz, os arquivos de .claude/commands/ audit.md e write-post.md e, em docs/research/snapshot-20260816/, as cópias que restaram de CLAUDE.md e write-post.md.

O Serena devolve cada referência com uma linha antes e outra depois. Por isso o grep foi executado de duas formas, git grep -n, que devolve só números de linha, e git grep -n -C1, que também devolve uma linha antes e outra depois, e as três saídas foram contadas por inteiro com o200k_base.

Comparado a um grep que devolve uma linha antes e outra depois, o Serena usa 683 tokens a menos. A diferença vem de não devolver as 5 posições em documentos. Mas o Serena acrescenta a cada referência o nome do símbolo e as informações de posição em JSON, então, olhando só o lado do código, ele na verdade usa 159 tokens a mais. E os 892 tokens do Serena superam os 703 de git grep -n, que devolve só números de linha. O que a camada LSP economiza neste repositório não é o resultado da busca, e sim o passo seguinte: ler linhas ou arquivos ao redor depois de ver o resultado do grep.

Nesse passo seguinte, se o agente lesse inteiros os 9 arquivos que o grep encontrou, leria 47.034 tokens: 3.716 dos 4 arquivos de código e 43.318 dos 5 documentos. Isso é um limite superior. Em uma sessão real, CLAUDE.md provavelmente já está no context e não seria lido de novo. Com um nome comum como isLocale, os resultados poderiam divergir até nas posições de código.

Conclusão

Resumindo, as quatro camadas se dividem pela profundidade com que entendem o código, e reduzem custos diferentes. O context packing entrega o código como texto e, mesmo com --compress, mantém só a sintaxe, reduzindo os tokens que entram. O repo map do tree-sitter sabe que um símbolo existe, põe um teto de orçamento nos tokens que entram, e a conversa daquele momento decide com o que preenchê-lo. O grafo de conhecimento guarda as relações de antemão e reduz as tool calls e os tokens processados, mas, pela medição do próprio fornecedor, o que fica na janela até aumentou. O LSP sabe o que é um símbolo; neste repositório ele não devolveu o mesmo nome nos documentos, mas em troca acrescentou metadados a cada resultado. O que ele economiza não está no resultado da busca, e sim na leitura que vem depois.

Por isso, ao escolher uma ferramenta, olho primeiro qual custo é o problema agora, mais do que a profundidade da camada. Se a janela é pequena e as sessões são longas, olho o que fica; se as idas e voltas são lentas, o número de tool calls; se no repositório documentos e código compartilham nomes, quantos arquivos acabo lendo depois de um resultado do grep. Leio o Cursor ter removido a busca semântica por embeddings e passado a um índice de texto local (Instant Grep) como um sinal de que um índice caro nem sempre supera a própria capacidade de busca do modelo.

Se essas ferramentas reduzem o custo de um agente encontrar código, quantas regras do projeto o agente deve conhecer desde o início, e em qual arquivo escrevê-las, é outro problema. Trato disso em Arquivos de contexto.

Este texto é para quem usa servidores MCP com Claude Code ou Cursor, mas tem dificuldade em explicar onde o MCP se separa do function calling das APIs de LLM. A resposta curta é que o MCP não substitui o function calling. A aplicação host converte a lista de ferramentas que recebe de um servidor MCP no parâmetro tools do function calling e devolve ao servidor MCP a chamada que o modelo escolhe. Ao final, você saberá de que parte do protocolo vem cada uma das quatro diferenças que o MCP acrescenta por cima, quais diferenças sobrevivem à revisão 2026-07-28 e que superfície de ataque essa estrutura abre.

Trabalho como desenvolvedor frontend e uso o Claude no dia a dia, mas, a cada servidor MCP que eu adicionava, nunca ficava muito claro para mim como essas ferramentas entravam no campo de visão do modelo.

MCP (Model Context Protocol)

O MCP (Model Context Protocol) resolve o problema de “o que permitir que o agente faça”.

Em termos mais concretos: para um agente de IA enviar uma mensagem no Slack, ele precisa conseguir chamar a API do Slack. Para criar uma issue no GitHub, precisa chamar a API do GitHub. Para fazer uma query no Postgres, precisa saber lidar com a conexão ao banco. O MCP reúne todas essas integrações com sistemas externos em um único protocolo padrão. (Ou seja, cliente e servidor se conectam pela mesma especificação.)

O MCP é um padrão aberto apresentado pela primeira vez pela Anthropic em 25 de novembro de 2024. Em 9 de dezembro de 2025, a Anthropic doou o MCP à Agentic AI Foundation (AAIF), vinculada à Linux Foundation. A AAIF foi cofundada por Anthropic, Block e OpenAI.

O MCP é um protocolo construído sobre JSON-RPC. O JSON-RPC 2.0 é um protocolo de RPC (Remote Procedure Call) stateless e leve que usa JSON como wire format. Como é independente da camada de transporte, funciona sobre HTTP, TCP ou entrada e saída padrão. Este texto usa como referência a revisão 2025-11-25, na qual o MCP é um protocolo stateful que estabelece uma sessão para cada conexão. O que mudou na revisão seguinte fica para depois de percorrermos o fluxo de chamadas.

As seis primitivas

A visão geral da especificação 2025-11-25 lista três recursos oferecidos pelo servidor e três oferecidos pelo cliente. Este texto chama esses seis de primitivas. Aqui, primitiva não tem relação com os tipos primitivos do JavaScript (como string ou number); refere-se a um tipo básico de interação definido pelo protocolo.

Primitivas do lado do servidor

• Tool (model-controlled): uma ação cuja chamada o próprio modelo decide. Essas ações podem ter efeitos colaterais (side effects)
• Resource (application-controlled): dados identificados por uma URI. A especificação só tem resources/read para ler o conteúdo e nenhum método de escrita. A aplicação host decide como colocar esse recurso no contexto
• Prompt (user-controlled): um template reutilizável que o usuário aciona explicitamente, por exemplo com um comando de barra

Primitivas do lado do cliente

• Sampling: um mecanismo que permite ao servidor pedir, no sentido inverso, uma completion ao LLM do cliente, tornando bidirecional a relação entre cliente e servidor. Serve para que um servidor que precisa gerar texto enquanto executa uma ferramenta use o modelo do cliente sem ter a própria chave de API. Na revisão 2026-07-28 ficou deprecated, ou seja, com remoção prevista
• Roots: informação sobre os limites do workspace com a qual o cliente diz ao servidor “até aqui vai a área em que você pode trabalhar”
• Elicitation: um recurso que permite ao servidor pedir ao usuário dados adicionais de forma estruturada enquanto executa uma ferramenta

Essa distinção importa porque quem decide chamar ou fornecer algo é diferente. Um Tool é executado por decisão do modelo, então uma chamada errada traz risco, enquanto um Prompt é escolhido explicitamente pelo usuário. Um Resource é escolhido pela aplicação por padrão, mas a especificação também permite implementações que incluem recursos automaticamente, com base em heurísticas ou na seleção do modelo. As três primitivas do lado do cliente vão no sentido oposto: o servidor pede, e o cliente decide se responde.

Os dois mecanismos de transporte

Há dois mecanismos de transporte padrão, e a especificação também permite outros transportes personalizados (MAY). O primeiro é o stdio, que executa o servidor MCP como um subprocesso local e se comunica pela entrada e saída padrão. É adequado para ferramentas que funcionam localmente, como sistema de arquivos ou git. O segundo é o Streamable HTTP, que coloca streaming SSE (Server-Sent Events) sobre HTTP POST e GET para criar uma comunicação quase bidirecional. O SSE é uma forma de o servidor enviar dados ao cliente em uma única direção por uma conexão HTTP. É adequado para cenários que acontecem através da rede, como servidores remotos, autenticação OAuth, conexões de vários clientes e deploy em nuvem.

O fluxo de uma chamada de ferramenta MCP por um LLM

Depois de ver as primitivas e os transportes, vamos seguir o fluxo de como um LLM realmente descobre e chama uma ferramenta MCP.

Na revisão 2025-11-25, quando uma conexão começa, acontece o seguinte handshake. Em 2026-10-08, o SDK de TypeScript 1.32.1 e a versão 2.3.1 da linha v2 também seguem essa ordem na configuração padrão.

• Cliente → servidor: requisição initialize (envia a versão de protocolo suportada e as capabilities do cliente)
• Servidor → cliente: resposta initialize (capabilities do servidor e, opcionalmente, o campo instructions)
• Cliente → servidor: notificação notifications/initialized
• Cliente → servidor: requisição tools/list → recebe a lista de ferramentas disponíveis
• (Depois) O LLM decide chamar uma ferramenta → o cliente envia tools/call → recebe o resultado

Na resposta initialize, o campo instructions é onde o servidor envia um texto sobre como suas ferramentas devem ser usadas. A linha instructions na saída da demo, mais abaixo, mostra esse valor.

Então, como a própria definição da ferramenta entra no campo de visão do LLM? A definição de uma ferramenta MCP tem esta forma de JSON Schema.

{
  "name": "get_weather",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  }
}

O host converte a lista recebida por tools/list no parâmetro tools da Anthropic Messages API ou no parâmetro tools do OpenAI function calling e a inclui na chamada à API do LLM. No caso da Anthropic, quando o parâmetro de ferramentas é enviado, um special system prompt é adicionado automaticamente para que o modelo entenda como chamar ferramentas. O tamanho varia conforme o modelo. Na tabela da documentação que consultei em 2026-10-08, os modelos atuais adicionavam de 286 a 675 tokens com tool_choice: auto.

Quando o LLM decide que precisa chamar uma ferramenta, a resposta contém um bloco tool_use ({"type": "tool_use", "name": ..., "input": ...}) e o stop_reason da resposta termina como tool_use. O host recebe isso, envia tools/call ao servidor MCP real, recebe o resultado, coloca-o em um bloco tool_result da próxima mensagem user e o envia de volta ao LLM. Esse loop se repete até que stop_reason mude de tool_use para outro valor, como end_turn ou max_tokens. O que costumamos chamar de “o agente trabalhando” é, na prática, uma sequência desses loops de chamada, resultado e nova chamada.

Desenhando, não há nenhuma linha entre o modelo e o servidor MCP. O modelo só vê as definições que recebeu por tools, e o servidor MCP recebe as requisições do host, não do modelo. O que liga os dois protocolos é o host no meio.

Executei essa conversão para ver o quanto ela é curta de fato. Rodou em 2026-10-08 com Node v24.16.0, @modelcontextprotocol/sdk 1.32.1 e zod 4.6.5. Em vez de stdio, o transporte é o InMemoryTransport, que liga servidor e cliente dentro de um mesmo processo, e nenhum LLM foi chamado. O bloco tool_use foi montado à mão no formato mostrado na documentação da Anthropic.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { z } from "zod";
 
// MCP 서버: 도구 하나와 instructions 를 둔다
const server = new McpServer(
  { name: "weather", version: "1.0.0" },
  { instructions: "Use get_weather for current conditions only." }
);
server.registerTool(
  "get_weather",
  { description: "Get current weather information for a location", inputSchema: { location: z.string() } },
  async ({ location }) => ({ content: [{ type: "text", text: `${location}: 15C, partly cloudy` }] })
);
 
// 호스트: 같은 프로세스 안에서 서버와 잇고, 클라이언트가 보내는 메서드 이름을 찍는다
const [clientT, serverT] = InMemoryTransport.createLinkedPair();
const send = clientT.send.bind(clientT);
clientT.send = (m) => { console.log("C->S", m.method, m.params?.protocolVersion ?? ""); return send(m); };
await server.connect(serverT);
const client = new Client({ name: "demo-host", version: "1.0.0" });
await client.connect(clientT);
console.log("instructions:", client.getInstructions());
 
// 1. tools/list 결과를 LLM API 의 tools 파라미터 모양으로 바꾼다
const { tools } = await client.listTools();
const anthropicTools = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.inputSchema }));
const openaiTools = tools.map((t) => ({ type: "function", name: t.name, description: t.description, parameters: t.inputSchema }));
console.log("anthropic:", JSON.stringify(anthropicTools[0]));
console.log("openai:", JSON.stringify(openaiTools[0]));
 
// 2. 모델이 이런 tool_use 블록을 돌려줬다고 가정한다. input 이 그대로 tools/call 의 arguments 가 된다
const toolUse = { type: "tool_use", id: "toolu_demo", name: "get_weather", input: { location: "Seoul" } };
const result = await client.callTool({ name: toolUse.name, arguments: toolUse.input });
console.log("tool_result:", JSON.stringify({ type: "tool_result", tool_use_id: toolUse.id, content: result.content }));
await client.close();

A saída de node post-demo.mjs é esta.

C->S initialize 2025-11-25
C->S notifications/initialized 
instructions: Use get_weather for current conditions only.
C->S tools/list 
anthropic: {"name":"get_weather","description":"Get current weather information for a location","input_schema":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
openai: {"type":"function","name":"get_weather","description":"Get current weather information for a location","parameters":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
C->S tools/call 
tool_result: {"type":"tool_result","tool_use_id":"toolu_demo","content":[{"type":"text","text":"Seoul: 15C, partly cloudy"}]}

A conversão das definições de ferramenta não passa de renomear campos. O inputSchema do MCP vira input_schema na Anthropic e parameters na OpenAI. A saída também mostra que o SDK acrescenta $schema ao schema. A direção contrária é igualmente curta. O tool_use.input da Anthropic é um objeto, então entra direto em tools/call como seus arguments. No lado do resultado, blocos de texto têm o mesmo formato e passam direto, mas resultados com imagem ou de erro têm formato diferente, e o helper de MCP do SDK da Anthropic os converte separadamente. O formato da OpenAI acima é o da Responses API. Os arguments de uma chamada que a OpenAI devolve são uma string JSON, então precisam passar uma vez por JSON.parse antes de serem repassados. O código acima só monta um bloco tool_use no formato da Anthropic, então essa etapa de parse não aparece na saída.

Quatro coisas que o MCP acrescenta

Então, o que o MCP acrescenta ao function calling? Pela revisão 2025-11-25, são quatro coisas.

• Descoberta dinâmica: a lista de ferramentas não é conhecida em tempo de build, e sim obtida em tempo de execução por tools/list. O servidor pode avisar por notifications/tools/list_changed que a lista mudou durante a conexão
• Stateful session: a conexão é estabelecida com initialize, e as requisições são trocadas dentro dela. Não há uma mensagem JSON-RPC de encerramento; a sessão termina com o fechamento do transporte
• Primitivas além de Tool: Resource, Prompt, Sampling, Roots e Elicitation são expostos por capability negotiation. A capability negotiation é a etapa de initialize em que cada lado anuncia os recursos que suporta
• Bidirecionalidade: o servidor pode pedir, no sentido inverso, uma completion ao LLM do cliente por Sampling (deprecated na revisão 2026-07-28)

Depois da revisão 2026-07-28

Em 2026-10-08, a revisão que o site oficial abre como latest é a revisão 2026-07-28, e nela metade desta lista mudou. Primeiro, o handshake formado por initialize e notifications/initialized e as sessões no nível do protocolo desapareceram. Em vez disso, cada requisição leva em _meta a versão do protocolo e as capabilities do cliente. Esse campo é um espaço que o MCP reserva para anexar metadados à parte dos parâmetros próprios da mensagem. Os servidores MUST implementar server/discover. É a RPC que devolve as versões do protocolo suportadas, as capabilities e as informações do servidor, e o cliente pode chamá-la antes de qualquer outra requisição para verificar de antemão as versões e capabilities suportadas.

As requisições que o servidor enviava primeiro foram substituídas por um padrão chamado Multi Round-Trip Requests (MRTR). Em vez de enviar uma requisição separada, o servidor devolve um resultado intermediário dizendo que precisa de mais dados (input_required), e o cliente preenche esses dados e reenvia a requisição original.

Sampling e Roots ficaram deprecated junto com Logging. Continuam na especificação e funcionam, mas implementações novas não devem adotá-los, e a especificação recomenda integrar diretamente com as APIs dos provedores de LLM em vez de usar Sampling.

Mesmo assim, o comportamento padrão dos SDKs ainda é o antigo. O SDK de TypeScript 1.32.1 tem 2025-11-25 como constante de versão mais recente e não conhece a revisão 2026-07-28, e a 2.3.1 suporta essa revisão, mas sua negociação de versão padrão é legacy. A primeira linha da saída acima, initialize 2025-11-25, é o resultado disso.

O que resta das quatro, então, é a descoberta dinâmica e as primitivas além de Tool (Resource, Prompt, Elicitation). A descoberta dinâmica também mudou um pouco de forma: as notificações de mudança de lista só chegam aos clientes que fazem opt-in no stream subscriptions/listen. No fim, o ponto em que o MCP se separa do function calling está menos nas sessões ou na bidirecionalidade e mais em um contrato para trocar a lista de ferramentas e o contexto em tempo de execução.

Quando a API vira o cliente MCP

O MCP connector (beta) da Anthropic mostra quanto desse contrato chega ao modelo. É um recurso em que a Messages API se conecta diretamente a um servidor MCP remoto, e a seção Limitations da documentação diz que, dos recursos da especificação MCP, "only tool calls are currently supported", e que "Local STDIO servers cannot be connected directly". A mesma documentação orienta que, se você precisar de servidores locais, prompts ou resources do MCP, gerencie a conexão por conta própria com um SDK de MCP e use os helpers de conversão do SDK da Anthropic.

Ou seja, quando o MCP é consumido na camada de function calling, só sobra o Tool. Resource e Prompt só fazem sentido quando há um host para levá-los à tela ou ao contexto. O guia de function calling da OpenAI também apresenta uma forma de usar a funcionalidade de um servidor MCP como built-in tool. O guia MCP servers da OpenAI só explica como listar e chamar ferramentas, e não diz se oferece suporte a Resource ou Prompt.

A superfície de ataque da descoberta dinâmica

As descrições das ferramentas e os resultados de suas chamadas chegam, pelo host, ao contexto do modelo. Então, o que quer que o servidor escreva ali, o modelo lê. Os dois ataques representativos vêm daí.

• Tool Poisoning Attack (TPA): um ataque que a Invariant Labs nomeou e para o qual publicou uma PoC em abril de 2025. Se instruções maliciosas forem escondidas na descrição (description) de uma ferramenta de um servidor MCP, o modelo lê esse texto, que o usuário não vê, e pode segui-lo sem que o usuário saiba.

• Rug Pull: um ataque, descrito pela Invariant Labs no mesmo post, em que o servidor muda a definição de uma ferramenta depois que o usuário a aprovou. Como no exemplo de Elena Cross citado por Simon Willison, você aprova no dia 1 uma ferramenta que parece segura e, no dia 7, ela já foi alterada para enviar suas chaves de API a um atacante; isso acontece porque as definições de ferramenta são obtidas do servidor em tempo de execução, e não no momento da instalação. A especificação de tools recomenda (SHOULD) uma UI que mostre quais ferramentas estão expostas ao modelo, mas não exige uma nova aprovação da definição alterada, então essa aprovação fica a cargo do host.

Conclusão

Em resumo, o MCP não substitui o function calling; é um padrão que se apoia sobre ele. O modelo continua chamando ferramentas pelo parâmetro tools e pelo loop de tool_use, e o host traduz entre os dois protocolos. Na revisão 2025-11-25, o que o MCP acrescentava era a descoberta dinâmica, uma stateful session, primitivas além de Tool e chamadas que vão do servidor para o cliente. Com o fim das sessões e o Sampling deprecated na revisão 2026-07-28, o que resta é um contrato para trocar a lista de ferramentas e o contexto em tempo de execução. Por causa desse contrato, ataques que envenenam as definições de ferramentas ou as mudam em silêncio surgem no mesmo lugar. Quando adicionar mais um servidor MCP, recomendo verificar não só o que esse servidor pode fazer, mas também se o seu host avisa quando as definições dele mudam.

Se o MCP trata do que permitir que o agente faça, o que informar a ele é papel de arquivos de contexto como CLAUDE.md e AGENTS.md. Como o agente lê esses arquivos e até que ponto suas instruções são seguidas é o tema de Arquivos de contexto.

Nos últimos tempos, as ferramentas de IA (Claude, ChatGPT, Cursor, Gemini, Copilot) passaram a ocupar um espaço cada vez maior ao nosso lado. A velocidade de desenvolvimento cresceu exponencialmente, mas, para ser sincero, tenho a impressão de que a qualidade final dos serviços não acompanhou esse ritmo. Tornou-se comum encontrar tantos bugs quanto funcionalidades novas, assim como ouvir: “Não sei por que isso ficou assim”.

À medida que desenvolvemos mais rápido, deixamos de examinar cada linha de código com o mesmo cuidado. Por isso mesmo, acredito que se tornou ainda mais necessário ter uma base sólida para orientar a IA na direção correta. Para manter a qualidade do resultado, precisamos identificar problemas no código gerado pela IA e redirecioná-la para aquilo que realmente queremos. Essa base pode envolver desenvolvimento orientado ao domínio, abstração, TDD (Test-Driven Development, desenvolvimento orientado a testes), uso adequado de bibliotecas, vantagens de performance, entre outros aspectos.

No entanto, sempre que pergunto a colegas de frontend — e também a profissionais de outras áreas de TI — “Qual é a tarefa mais difícil no desenvolvimento frontend?”, a resposta que mais ouço é sempre a mesma: “Gerenciar o fluxo de estado.”

Neste artigo, pretendo explicar por que gerenciar esse fluxo é tão difícil e que tipo de discernimento e sensibilidade precisamos desenvolver para lidar bem com ele.

O que é estado (State)?

Antes de entrar no assunto propriamente dito, vamos começar pela pergunta mais básica: afinal, o que exatamente chamamos de “estado”?

Enquanto estudava desenvolvimento frontend, eu lia com frequência os textos de hoseung.me. Ali, estado é definido como “todo dado capaz de afetar a UI”. Número de curtidas, itens do carrinho, modal aberto ou fechado, valores digitados, informações do usuário autenticado, aba selecionada, resultados de busca, estado de carregamento: tudo isso é estado.

A documentação oficial do React oferece uma definição mais formal. O próprio título da página é “State: A Component's Memory”; em outras palavras, trata-se de “um mecanismo que permite ao componente reter dados entre renderizações e acionar uma nova renderização no React quando esses dados são atualizados”. Ou seja, são dados que não desaparecem com o tempo, mudam em resposta a algum evento e fazem a UI ser renderizada novamente quando mudam. Há ainda outro ponto importante: o estado é isolado por instância do componente. Mesmo que o mesmo componente apareça dez vezes em uma página, cada instância terá seu próprio estado independente. Esse fato se conecta diretamente à discussão posterior sobre “onde o estado deve ficar”.

As duas definições apontam para o mesmo lugar: estado é “um valor que muda ao longo do tempo e afeta a renderização”. Uma constante que não muda não é estado. Um design token primitivo fixado no build time não é estado, mas um dark mode que o usuário pode alternar é. (A rigor, o valor em si é resolvido conforme o estado do tema, dark ou light; portanto, é mais preciso dizer que a “seleção do tema” é o estado e que o token é o espelho no qual esse estado se reflete.)

Há um aspecto que vale destacar: nem todo estado vive em um componente. Alguns estados vivem em cookies; outros, em localStorage, sessionStorage ou IndexedDB; outros ainda, na URL. Quando trazemos dados do servidor para o cliente e os armazenamos em cache, eles também se tornam uma forma de estado. Até a posição de scroll e a pilha de histórico mantidas pelo próprio navegador às vezes precisam ser tratadas como estado, pois determinam o comportamento da aplicação.

Por que é tão difícil?

Vamos começar pensando de forma simples sobre por que lidar com estado é difícil. Não bastaria criar os estados necessários, levá-los até onde são usados e tratar corretamente suas atualizações e resets?

Com essa pergunta em mente, abra uma página do serviço em que você trabalha hoje.

Quantos componentes existem nessa página? Mesmo em uma página simples, provavelmente há de dezenas a centenas de componentes formando uma árvore. Cada componente pode manter seu próprio estado, compartilhá-lo com componentes irmãos ou recebê-lo do pai. O estado também transita entre páginas; alguns valores precisam sobreviver a um refresh, enquanto outros devem desaparecer quando a aba é fechada.

O verdadeiro motivo de ser tão difícil gerenciar estado é este: não conseguimos visualizar de imediato onde os inúmeros estados são declarados, como são atualizados e quando deixam de existir. Conforme aumenta o número de componentes com papéis semelhantes, torna-se mais difícil tanto nomear estados quanto rastrear o código que os altera.

É assim que surge uma teia invisível. Um clique no componente A invalida os dados de B; a invalidação de B fecha a UI de C; ao fechar C, os dados digitados no formulário desaparecem. Se essa cadeia não estiver explicitada em nenhum lugar do código, teremos de reconstruir mentalmente toda a teia ao depurar um bug.

Como, então, organizar essa teia? Para mim, o primeiro passo é reconhecer que “existem diferentes tipos de estado”.

Nem todo estado é igual

Kent C. Dodds divide o estado em Server Cache (informações que existem no servidor e são mantidas pelo cliente para acesso rápido) e UI State (informações que existem apenas na UI para controlar o comportamento da interface). Muitas vezes erramos justamente ao agrupar os dois.

A documentação oficial do TanStack Query define a ferramenta como uma biblioteca de Server State, responsável por gerenciar operações assíncronas entre servidor e cliente, enquanto Redux, MobX e Zustand são definidos como bibliotecas de Client State. (É possível armazenar dados assíncronos nelas, mas isso é ineficiente.)

O ponto central é claro: Server State e Client State são problemas diferentes. Server State é assíncrono, pode ser alterado por outros usuários e se torna stale com o tempo. Client State é síncrono, está sob nosso controle e desaparece com um refresh. (Mais precisamente, quando a página é descarregada, o runtime JavaScript é reiniciado, e a árvore de componentes mantida na memória heap, junto com seus estados, é coletada. Por isso, na próxima montagem, tudo recomeça pelo valor inicial de useState.) Se tentarmos tratar os dois com a mesma ferramenta, teremos de implementar por conta própria padrões como invalidação de cache, atualização em background e optimistic updates.

Vou um passo além e divido o estado do frontend em sete categorias. Vale esclarecer desde já que essas categorias não se separam perfeitamente em um único eixo. Local de armazenamento, origem, ciclo de vida e função se misturam, de modo que um mesmo estado pode pertencer a mais de uma categoria. Em vez de uma taxonomia perfeita, encare-as como perguntas que ajudam a decidir como gerenciar um estado.

• Estado local (Local State): Estado usado apenas em um componente ou em uma subárvore restrita
• Estado global (Global State): Estado que precisa ser compartilhado por toda a aplicação
• Estado do servidor (Server State): Estado cuja fonte da verdade é o servidor e cuja cópia no cliente é um cache
• Estado de formulário (Form State): Estado temporário que existe enquanto o usuário preenche dados
• Estado da URL (URL State): Estado compartilhável que vive na barra de endereços e sobrevive ao refresh
• Estado externo (External State): Estado fora do React, como cookies, localStorage, sessionStorage e IndexedDB
• Guard de estado (State Guard): Lógica que bloqueia, permite ou valida acessos e ações conforme combinações de estado, em vez de ser um estado em si

Além dessas categorias, há estados de fluxo que podem exigir uma máquina de estados e estados colaborativos em tempo real baseados em WebSocket ou CRDT.

Vamos analisar, uma a uma, por que cada categoria exige ferramentas diferentes e com que perspectiva devemos abordá-la.

Estado local (Local State)

É a forma mais simples de estado. Ele é usado apenas dentro de um componente, e quem está de fora não precisa — nem deveria precisar — conhecê-lo. Alguns exemplos são: modal aberto ou fechado, botão de alternância on/off, hover e termo de busca enquanto está sendo digitado.

function SearchBox() {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

Isso provavelmente já é familiar. A verdadeira dificuldade do estado local, porém, está na decisão de “onde esse estado deve ficar”.

No artigo de Kent C. Dodds sobre State Colocation, ele observa que as pessoas estão acostumadas a “elevar (lift up)” o estado, mas raramente voltam a “aproximá-lo (colocate)” quando o código muda.

Elevar o estado é algo que fazemos naturalmente quando componentes irmãos precisam compartilhá-lo. Como os dois precisam enxergar os mesmos dados, levamos o estado para o pai comum e o distribuímos via props.

O problema surge quando os componentes irmãos deixam de precisar desse estado. Raramente fazemos o caminho inverso, descendo-o de volta para o filho. Como resultado, o componente pai acumula vários estados que na verdade não lhe dizem respeito e, sempre que renderiza novamente, acaba levando consigo toda a árvore de filhos.

Por isso, o primeiro princípio do estado local é: para tornar o código mais rápido e simples, mantenha o estado o mais próximo possível do código que o utiliza. Se um estado é usado apenas por um único filho, não há motivo para o pai mantê-lo. Mova-o para dentro desse filho; o pai ficará mais leve.

Estado global (Global State)

Estado global é aquele que precisa estar acessível de qualquer ponto da aplicação. Informações de login, tema, idioma e notificações (toasts) são possíveis candidatos.

A diferença entre estado local e global não se resume a “onde ele vive”. O que muda é o contrato de referência. O estado local assume o compromisso de que “isso só tem significado dentro deste componente”; já o estado global publica para todo o código o compromisso de que “esse valor pode ser acessado por esse nome em qualquer lugar da aplicação”. A essência do estado global está no custo desse compromisso.

Criar um estado global significa, na prática, adicionar uma dependência implícita em toda a aplicação.

Estado de servidor (Server State)

Colocamos os dados recebidos de uma API no estado do cliente, gerenciamos loading e error manualmente com booleanos e, em algum momento, chegamos à pergunta: “Por que estou escrevendo o mesmo boilerplate toda vez?”

Tanner Linsley, principal mantenedor do TanStack, diz que “Client State é síncrono e previsível. Server State é assíncrono, compartilhado entre vários componentes e exige atenção ao cache, às atualizações em background e aos estados de erro.” Em outras palavras, Server State é uma espécie fundamentalmente diferente de Client State. Não devemos tratá-los com a mesma ferramenta.

A dificuldade do Server State não decorre das ferramentas, mas da natureza dos dados.

Os dados que o cliente exibe pertencem ao servidor. Aquilo que o cliente possui é apenas um snapshot de determinado momento. Com o passar do tempo, esses dados ficam stale. Além disso, são assíncronos, podem falhar e passam por estados como pending, error e success.

A característica mais importante é que não existe garantia de que as respostas retornarão na ordem em que as requisições foram enviadas. Imagine digitar rapidamente “react” em uma caixa de busca. As requisições r → re → rea → reac → react são enviadas nessa ordem; porém, se a resposta de “react” chegar primeiro e a de “rea” chegar depois, a tela exibirá os resultados de “rea”. Para evitar esse problema, é preciso lidar com riscos de concorrência (race conditions) que exigiriam implementar manualmente, a cada vez, um AbortController ou o rastreamento de IDs das requisições.

Estado de formulário (Form State)

Formulários têm um tipo peculiar de estado. Enquanto o usuário digita, ele muda intensamente; depois do envio, em geral desaparece. Não é compartilhado com nenhum outro lugar e, na maioria dos casos, também não há onde armazená-lo.

O problema é que essa “mudança intensa” custa caro. Se cada tecla pressionada causar uma nova renderização do React, o atraso na digitação pode se tornar perceptível em formulários grandes. Além disso, um formulário não serve apenas para “guardar valores”. Validação, dirty check, estado de envio, mensagens de erro e fluxos em múltiplas etapas coexistem e mudam ao mesmo tempo dentro de um único formulário.

Espera-se que um formulário em várias etapas, como um checkout de três passos, “preserve o progresso mesmo após um refresh no meio do processo”. Se seus valores forem mantidos apenas com useState, todos desaparecerão no refresh. É natural armazená-los em sessionStorage (armazenamento temporário por aba) ou na URL (para etapas compartilháveis). Ou seja, dependendo dos requisitos de ciclo de vida, o estado de formulário se combina com External State ou URL State.

Estado da URL (URL State)

Imagine uma página de busca em que categoria, ordenação e número da página são usados como filtros. Se esses estados forem mantidos com useState, três problemas surgirão ao mesmo tempo.

• Ao atualizar a página, todos os filtros voltam aos valores iniciais
• Ao compartilhar a URL com alguém, essa pessoa verá a página sem os filtros aplicados
• Ao clicar em voltar, você não retornará aos filtros anteriores

Para resolver esses problemas, é natural colocar o estado na URL. A própria URL é um armazenamento persistente gratuito, compatível com refresh, compartilhamento e histórico.

/products?category=shoes&sort=price-desc&page=2

Essa única URL contém o estado completo de “página 2 da categoria de calçados, ordenada por preço decrescente”. Não é necessário mantê-lo separadamente com useState.

Quando, então, é apropriado tratar estado na URL? A URL é uma interface pública. Senhas, tokens de autenticação e anotações temporárias que o usuário não queira mostrar a outras pessoas não devem estar na URL. Além disso, inserir diretamente na URL valores que mudam com muita frequência — como uma busca atualizada a cada tecla — enche a pilha de histórico de lixo. Nesses casos, devemos aplicar a alteração após um debounce, reservar push para quando fizer sentido e usar replace nas atualizações que não devem adicionar uma entrada ao histórico.

Os valores da URL são sempre strings. Números, booleanos, arrays e objetos precisam passar por serialização e desserialização. Além disso, a URL precisa seguir as regras de percent-encoding, que dão tratamento especial a &, =, caracteres coreanos, espaços e outros elementos. Implementar tudo isso manualmente a cada vez logo se transforma em uma fonte de bugs.

const params = new URLSearchParams(location.search);
const page = Number(params.get("page") ?? "1");
params.set("page", String(page + 1));
navigate(`?${params.toString()}`);
 
const [page, setPage] = useQueryState("page", parseAsInteger.withDefault(1));

Bibliotecas como nuqs resolvem os dois problemas por meio do conceito de parser. Parsers como parseAsInteger, parseAsBoolean e parseAsJson cuidam de uma só vez da serialização, da desserialização e dos tipos. A biblioteca oferece suporte à maioria dos ambientes, incluindo Next.js (App Router e Pages Router), React Router v6/v7, TanStack Router e Remix.

Isso significa que podemos colocar qualquer quantidade de estado na URL? Além dos problemas de serialização e tipos, ainda existe uma última restrição a considerar. A RFC 7230 não define um limite exato, mas recomenda que “o servidor ofereça suporte a pelo menos 8.000 octetos” (octeto é a unidade usada em redes e comunicação de dados para designar, sem ambiguidade, um conjunto de 8 bits, isto é, 1 byte). Os limites também variam entre navegadores: browsers modernos geralmente aceitam de 8 KB a dezenas de milhares de caracteres, mas mecanismos de busca, o processamento de OG/compartilhamento em redes sociais e alguns gateways podem truncar a URL por volta de 2 KB. Portanto, não devemos inserir dados indefinidamente na URL. É mais seguro manter nela apenas os principais filtros compartilháveis e deixar o restante a cargo do sessionStorage ou de um armazenamento no servidor.

Estado externo (External State)

O React conhece apenas o estado dentro dele próprio. Nossa aplicação, porém, conversa constantemente com o mundo fora do React. Os estados que vivem nesse mundo sobrevivem e mudam independentemente do ciclo de vida do React. O External State abordado aqui inclui Cookie, localStorage,sessionStorage,IndexedDB.

Como escolher o armazenamento adequado? Costumo pensar em quatro perspectivas: duração, capacidade, sincronicidade e segurança.

Para tokens de autenticação, a recomendação da OWASP prioriza cookies HttpOnly + Secure. Como o localStorage é acessível via JavaScript, basta uma exposição a XSS para que o token seja roubado diretamente. Alguns guias de segurança recomendam um padrão híbrido: access token na memória e refresh token em um cookie HttpOnly. Para dados persistentes, não sensíveis e que mudam pouco, usa-se localStorage; para dados que devem desaparecer com a aba, sessionStorage. IndexedDB costuma ser usado para cache offline, grandes volumes de dados e arquivos.

Cookies e Web Storage (local/session) armazenam apenas strings. Por isso, inserir um objeto exige passar por JSON.stringify/JSON.parse. O JSON, contudo, tem limitações.

JSON.stringify({ when: new Date() });
// → { "when": "2026-05-19T..." } — Date becomes a string
 
JSON.stringify({ map: new Map([["a", 1]]) });
// → { "map": {} } — Map is lost entirely
 
JSON.stringify({ value: undefined });
// → "{}" — the undefined field is omitted

Date se torna string em um round trip por JSON, enquanto Map, Set e undefined podem perder dados. No comportamento padrão, BigInt faz JSON.stringify lançar um TypeError, portanto a serialização falha por completo. Ao armazenar objetos fora do React, devemos sempre ter consciência de quais tipos podem desaparecer, ser alterados ou fazer a serialização falhar e, se necessário, criar um adapter.

A verdadeira dificuldade do External State é que o React não detecta suas mudanças automaticamente. Gravar um valor no localStorage não faz um componente React renderizar novamente. Em geral, há três padrões para resolver isso.

• Encapsular o armazenamento em um hook customizado (useLocalStorage) e sincronizar o External State com o estado do React. É uma solução leve, mas, quando implementada do zero, exige lidar com casos extremos como múltiplas abas, SSR e tearing.
• Usar o hook useSyncExternalStore, introduzido no React 18, para “sincronizar o React com estados externos”. Com isso, é possível garantir que não ocorra tearing durante a renderização concorrente. É a ferramenta padrão para integrar localStorage, APIs do navegador e stores externos.
• Como bibliotecas de estado oferecem integração com armazenamento externo como recurso de primeira classe — por exemplo, o middleware persist do Zustand e o atomWithStorage do Jotai —, podemos aproveitar implementações já prontas.

Há ainda outro princípio importante: no momento em que trazemos um estado externo para o React, a responsabilidade pela sincronização passa a ser nossa. E se ele for atualizado em outra aba? E se o servidor alterar o cookie? E se o usuário modificar diretamente o localStorage pelas ferramentas de desenvolvedor do navegador? Essas situações frequentemente se tornam grandes fontes de bugs.

Guard de estado (State Guard)

A última categoria tem uma natureza um pouco diferente. Não é o estado em si, mas a lógica que usa uma combinação de estados para impedir, permitir ou validar determinado fluxo.

O exemplo mais comum é o guard de autenticação (Auth Guard).

function ProtectedRoute({ children }) {
  const { isAuthenticated, isLoading } = useAuth();
 
  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return children;
}

Aqui, o estado isAuthenticated controla o fluxo de roteamento. Isso é uma lógica de guard. Existem vários tipos: guard de autenticação (usuário autenticado), guard de autorização (papel ou permissão específica), guard de fluxo (ramificação de entrada) e guard de validação (habilitação de etapa), entre outros.

A lógica de guards tende a se concentrar em um único lugar. É comum um componente reunir tudo: “se não estiver autenticado, vá para o login; se não tiver permissão, mostre 403; se o carrinho estiver vazio, vá para a página de produtos; se o usuário estiver suspenso, exiba o aviso de suspensão”. Quanto mais inchado fica o guard, mais difícil é depurar qual condição bloqueou o fluxo e onde isso aconteceu.

Um bom guard verifica apenas uma coisa. A combinação é feita por Composition.

<AuthGuard>
  <RoleGuard role="admin">
    <FlowGuard require={["cartHasItems"]}>
      <CheckoutPage />
    </FlowGuard>
  </RoleGuard>
</AuthGuard>

Cada guard toma apenas uma decisão, e a estrutura em árvore é responsável pela composição. Para adicionar um novo guard, não é necessário alterar os existentes.

Ao trabalhar com guards, há algo que exige ainda mais reflexão do que decidir o que bloquear: definir para onde encaminhar o usuário e como tratar o fluxo depois disso. Um guard que apenas bloqueia, sem fallback, termina em uma tela branca ou em um spinner infinito.

O bug mais comum ocorre quando “o conteúdo protegido pisca brevemente antes de a verificação assíncrona do guard terminar”. A validação do token de autenticação e a consulta de permissões quase sempre são assíncronas; nesse intervalo, isAuthenticated pode ficar temporariamente como undefined ou false. Se o estado de loading não for tratado explicitamente, a tela protegida pode ser exposta nesse intervalo ou o usuário pode ser redirecionado por engano para a página de login.

// Ignores loading and handles only missing data => incorrect
if (!user) return <Navigate to="/login" />;
 
// Treat loading as a first-class state (early return) => correct
if (isLoading) return <Spinner />;
if (!user) return <Navigate to="/login" replace />;
return children;

Dois modelos são usados com frequência na implementação de guards de autorização.

• RBAC (Role-Based Access Control): concede permissões por papel. Por exemplo: “admin pode ver as informações de todos os usuários”. É simples e rápido, mas o número de papéis explode à medida que eles se tornam mais granulares
• ABAC (Attribute-Based Access Control): determina permissões a partir de uma combinação de atributos. Por exemplo: “se o usuário for o autor do post, pertencer à mesma equipe ou for admin”. Tem grande poder de expressão, mas é difícil de implementar e depurar

Como mostra o guia de RBAC do TanStack Router, recomenda-se o padrão de inserir o guard em beforeLoad, no nível do router. O ponto central é que as verificações de permissão devem poder ser representadas como dados — uma lista de papéis ou permissões — em vez de ficarem espalhadas pelo código. Assim, uma mudança na política de acesso se resume a uma mudança de dados.

Conclusão

Vamos recapitular. O gerenciamento de estado não é difícil porque as bibliotecas são difíceis. Ele é difícil porque frequentemente esquecemos que existem diferentes tipos de estado e deixamos passar o fato de que cada tipo exige ferramentas e formas de pensar distintas.

Mantenha o estado local o mais próximo possível; questione mais uma vez se o estado global é realmente global; trate Server State como cache; separe os formulários do domínio; use a URL de forma mais ativa; assuma conscientemente as responsabilidades envolvidas no armazenamento externo; e divida os guards em partes pequenas que possam ser compostas. Esses são os fundamentos para lidar com as sete categorias.

Acima de tudo isso, o discernimento necessário se resume, no fim, a quatro perguntas.

• Onde está a Single Source of Truth destes dados?
• Este valor pode ser calculado ou realmente precisa ser armazenado?
• Existe alguma combinação impossível entre esses estados?
• Este estado realmente deveria estar neste lugar?

Fazer essas perguntas sempre que criamos uma nova tela, revisamos um PR ou recebemos código produzido por IA é, acredito, o caminho mais seguro para desenvolver esse discernimento e essa sensibilidade.

Como mencionei no início, a IA permanecerá ao nosso lado por muito tempo. O tempo que dedicamos a examinar linha por linha continuará diminuindo. Mas, justamente por isso, a capacidade de responder a pequenas perguntas como “Onde este estado deveria ficar?” se tornará ainda mais valiosa. É fácil pedir à IA: “adicione mais um useState aqui”. Saber que novo fio essa linha acrescenta à teia da nossa aplicação, porém, depende exclusivamente do discernimento de quem lê o código.

Não existe uma resposta única. Ainda assim, há uma diferença evidente entre “criar estado sem saber o que é estado” e “criá-lo tendo consciência de seu tipo e de sua localização”. Espero que, da próxima vez que você estiver prestes a escrever uma linha de useState, pare por um instante e pergunte: “A qual categoria de estado isto pertence?”

É para desenvolvedores frontend cujas regras de negócio, como o cálculo de impostos ou a verificação do status de uma declaração, estão espalhadas por componentes, hooks e utils, de modo que cada mudança de regra exige procurar e corrigir vários arquivos. Ao final, você saberá como mover essas regras para funções puras que não dependem do React e com que critério decidir onde essa separação deve parar.

Todos os exemplos usam o cálculo do imposto de renda, um domínio que me interessa.

Onde a lógica de domínio deve ficar no frontend?

Antes de responder, vamos alinhar um termo. Neste post, um modelo de domínio reúne os conceitos de negócio junto com as regras que operam sobre eles. Ele é diferente de um modelo de dados, como o tipo de uma resposta da API, que só define o formato em que os dados trafegam. Essa diferença também explica por que, quando os componentes dependem diretamente da estrutura da resposta, todo o frontend balança a cada mudança no schema do backend. Como os quatro termos (domínio, modelo de domínio, objeto de domínio e modelo de objetos de domínio) se diferenciam está explicado à parte em Termos de domínio.

Khalil Stemmler, que se interessa profundamente por design de software, primeiro defendeu que "a lógica de negócio não pertence ao frontend". Mais tarde, reviu sua posição e afirmou: "Podemos e devemos fazer no frontend quase tudo o que fazemos arquiteturalmente no backend."

Concordo com essa posição. É claro que o frontend não deve ser a fonte única da verdade (Single Source of Truth) da lógica de negócio. Esse é o papel do backend. Mas também existe, sem dúvida, lógica de domínio própria do frontend.

Pense no caso em que "é preciso mostrar em tempo real a restituição estimada com base nas informações inseridas pelo usuário". Se essa lógica de cálculo existir apenas no backend, será necessário chamar a API toda vez que o usuário corrigir um único caractere no valor da renda. A UI ficará parada durante o tempo de ida e volta pela rede e, se o usuário digitar rápido, o volume de solicitações desnecessárias crescerá de forma explosiva. Mesmo com debounce, um atraso de algumas centenas de milissegundos já é suficiente para comprometer a experiência de uma "prévia em tempo real". No fim, cálculos que exigem feedback imediato precisam ser executados diretamente pelo frontend, e passam a existir lógicas que só podem ser executadas nele.

Quando a lógica de domínio se mistura ao componente

Tomemos como exemplo uma tela de prévia do imposto de renda global. Nela, quando o usuário informa seus rendimentos, o imposto estimado é exibido em tempo real. Abaixo está um código comum em que a lógica de domínio e a lógica de UI estão misturadas.

function TaxPreviewPage() {
  const [총수입, set총수입] = useState(0);
  const [경비율, set경비율] = useState(0.641); 
  const [인적공제대상인원, set인적공제대상인원] = useState(1); 
 
  const 종합소득금액 = 총수입 - 총수입 * 경비율;
 
  const 소득공제합계 = 인적공제대상인원 * 1_500_000;
  const 과세표준 = Math.max(0, 종합소득금액 - 소득공제합계);
 
  let calculatedTax = 0;
  if (과세표준 <= 14_000_000) {
    calculatedTax = 과세표준 * 0.06;
  } else if (과세표준 <= 50_000_000) {
    calculatedTax = 과세표준 * 0.15 - 1_260_000;
  } else if (과세표준 <= 88_000_000) {
    calculatedTax = 과세표준 * 0.24 - 5_760_000;
  } else if (과세표준 <= 150_000_000) {
    calculatedTax = 과세표준 * 0.35 - 15_440_000;
  } else {
    calculatedTax = 과세표준 * 0.38 - 19_940_000;
  }
 
  const 기납부세액 = 총수입 * 0.033;
  const refundOrPayment = 기납부세액 - calculatedTax;
 
  return <div>...</div>;
}

Você consegue ver o problema desse código? Regras de negócio definidas pela legislação tributária, como "dedução pessoal de 1,5 milhão de won por pessoa", "alíquota progressiva em oito faixas" e "retenção na fonte de 3,3%", estão inseridas diretamente no componente React. A legislação tributária muda todos os anos; se essas regras estiverem espalhadas pelos componentes, será preciso caçar todos os lugares que devem ser corrigidos a cada revisão. E, se houver cenários E2E mantidos não só por quem desenvolve, mas também pela equipe de QA, o custo dos testes também não será pequeno.

Com isso, fica difícil distinguir lógica de View e lógica de negócio, e tudo acaba emaranhado em inúmeras condicionais e hooks customizados.

Vamos separar a lógica de domínio

Tomemos emprestado o princípio central da abordagem de Clean Architecture de Alex Bespoyasov: separar a lógica de domínio em funções puras que não dependem de framework.

O domínio é o núcleo que distingue uma aplicação de outra. Podemos pensar no domínio como algo que não mudaria se migrássemos do React para o Angular.

The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular.

Vamos refatorar o exemplo de cálculo de impostos acima.

Primeiro, definimos os tipos e as regras do domínio para manter as informações relacionadas coesas.

export interface Income {
  grossAmount: number;
  expenseRate: number;
}
 
export interface Deductions {
  personalCount: number;
  pensionPaid: number;
  additionalDeductions: number;
}
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
const TAX_BRACKETS = [
  { limit: 14_000_000, rate: 0.06, progressiveDeduction: 0 },
  /** ...구간들... **/
] as const;

Depois, separamos a lógica de domínio em funções puras.

Separamos na função computeFullTax as lógicas de cálculo de renda, deduções, base tributável, imposto e restituição mencionadas anteriormente. Cada etapa volta a ser dividida em pequenas funções puras. Se o tipo do resultado for inferido com ReturnType<typeof computeFullTax>, não será necessário declarar uma interface separada.

Depois disso, o componente apenas "usa" a lógica de domínio.

import { computeFullTax } from "../domain/tax";
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({
    grossAmount: 0,
    expenseRate: 0.641,
  });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1,
    pensionPaid: 0,
    additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

O que mudou?

• A tabela das oito faixas progressivas (TAX_BRACKETS) está reunida em um só lugar; quando a legislação mudar, basta alterar domain/tax.ts.
• O pipeline de cálculo está coeso em uma única função, computeFullTax, permitindo visualizar o fluxo completo de uma vez. (Agrupamos tudo para manter o exemplo simples, mas, em um projeto real, convém subdividir ainda mais por finalidade, como cálculo de renda, cálculo de deduções e apuração do imposto.)
• O componente se concentra apenas em "como exibir". Mesmo que a alíquota mude, não é preciso alterar o componente.
• Mesmo que haja uma migração do React para outro framework, domain/tax.ts não muda.

Quando a lógica de domínio é separada, os testes se tornam surpreendentemente simples. Isso é especialmente importante no domínio tributário, pois a precisão dos cálculos é o próprio dinheiro do usuário.

Funções puras que contêm cálculos tributários não precisam de React Testing Library, render nem screen.getByText. Basta fornecer a entrada e verificar a saída. Casos como "alíquota de 6% até 14 milhões de won", "imposto igual a zero quando a base tributável é zero" e "restituição sobre uma renda de 30 milhões de won de um profissional autônomo" podem ser expressos em um it de uma única linha. Os testes unitários do domínio estabelecem naturalmente os critérios de separação dos componentes, e o código de teste ainda funciona como documentação.

Modelo de domínio anêmico (Anemic Domain Model)

Na seção anterior, separamos a lógica de cálculo. Mas a lógica de domínio também inclui regras de transição de estado e decisões de permissão. Perguntas como "é possível editar esta declaração agora?", "ela pode ser enviada?" e "é possível mudar o tipo de solicitação?" fazem parte disso. Ao separar essas regras, é fácil cair em uma armadilha que Martin Fowler chamou de modelo de domínio anêmico (Anemic Domain Model).

Um modelo de domínio anêmico é uma situação em que os tipos estão bem definidos na linguagem do domínio, mas as regras que operam sobre eles ficam espalhadas para fora do domínio. Vejamos o domínio de declaração de impostos (Filing). Os tipos estão bem organizados.

// types/filing.ts
export interface TaxFiling {
  id: string;
  status: "draft" | "submitted" | "reviewing" | "completed" | "amended";
  taxYear: number;
  filingType: "regular" | "late" | "amendment";
  determinedTax: number;
}

Mas as regras de decisão e transição desse tipo estão inseridas em outros lugares.

// utils/filingHelpers.ts
export function canAmendFiling(filing: TaxFiling) {
  return filing.status === "completed" && filing.filingType !== "amendment";
}
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 같은 도메인 규칙을 컴포넌트 안에 다시 작성한다
  const canEdit = filing.status === "draft" || filing.status === "reviewing";
  // ...
}
 
// hooks/useSubmitFiling.ts
export function handleSubmitFiling(filing: TaxFiling) {
  if (filing.status !== "draft") return;
  // ...
}

A mesma regra de domínio existe em três lugares — utils, componente e hook —, cada um com uma forma diferente. Se surgir um requisito dizendo "as condições para solicitação serão alteradas", será necessário procurar todos os pontos que precisam mudar; qualquer um que for esquecido passará a tomar uma decisão incorreta em algum lugar do site. Fowler criticou esse tipo de código afirmando que "ele não difere de código procedural revestido apenas com uma aparência orientada a objetos".

A solução é a mesma aplicada à lógica de cálculo na seção anterior: colocar as regras ao lado do tipo.

export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus =
  | "draft"
  | "submitted"
  | "reviewing"
  | "completed"
  | "amended";
 
export type FilingType = "regular" | "late" | "amendment";
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === "draft";
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === "draft" && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === "completed" && filing.filingType !== "amendment";
}

Agora, as regras relacionadas às declarações são gerenciadas em um único lugar: domain/filing.ts. Qualquer componente pode chamar canAmend(filing), e, se a regra mudar, basta alterar esse arquivo. O ponto central é entender o tipo e as regras que operam sobre ele como um único conjunto. Uma separação parcial que coloca apenas o tipo na pasta de domínio e envia as regras para utils pode parecer organizada por fora, mas continua anêmica.

Camada de transformação entre a resposta da API e o modelo de domínio

Há mais um ponto a considerar no trabalho real: a estrutura da resposta da API do backend nem sempre coincide com o modelo de domínio do frontend. Isso é ainda mais verdadeiro em um serviço tributário integrado a órgãos governamentais. Os dados de integração do Hometax, o serviço da Receita Nacional da Coreia, estão cheios de abreviações e códigos; dificilmente chegarão no mesmo formato do modelo de domínio do frontend.

É aí que entra uma camada de transformação (Mapper). Em vez de deixar o tipo da resposta da API fluir diretamente até o componente, primeiro o refinamos para o tipo do domínio e só então o utilizamos. Uma única função pura é suficiente.

import type { Income } from "../domain/tax";
 
interface HometaxIncomeResponse {
  총수입금액: number;
  경비율: number;
  소득유형코드: string;
  // ... 나머지 약어 필드들
}
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    총수입_금액: response.총수입금액,
    경비_비율: response.경비율,
  };
}

Assim, abreviações como 총수입금액 e 경비율 e classificações baseadas em códigos da resposta da API são transformadas em um só lugar para se adequar ao domínio do frontend. Valores como o código do tipo de renda, que precisam ser convertidos para enum, podem ser tratados com uma pequena lookup table dentro do mapper. Mesmo que o nome de um campo da API do Hometax mude, basta alterar um único mapper.

Funções utilitárias e lógica de domínio

Ao separar a lógica de domínio, surge inevitavelmente uma pergunta: "isto não é uma função utilitária?"

Observe as duas funções abaixo.

function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find((bracket) => taxableBase <= bracket.limit);
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrency é uma lógica pura de apresentação (Presentation) que transforma um número em string. Acrescentar a unidade "won" e separar milhares por vírgulas não é uma regra de negócio, mas uma questão de como apresentar o valor ao usuário. Já calculateTax contém uma regra de negócio baseada na legislação tributária: a aplicação de oito faixas progressivas. É uma regra do domínio que precisa continuar igual mesmo sem UI.

Este é o critério que uso no trabalho:

Se essa lógica desaparecer, o negócio quebra ou apenas a tela quebra?

Se o negócio quebra, é lógica de domínio; se apenas a tela quebra, é lógica de apresentação. Essa única pergunta permite distinguir a maioria das fronteiras.

Mas a realidade não é tão bem delimitada. O caso mais difícil é quando algo parece lógica de domínio, mas na verdade é lógica de apresentação.

Observe o código abaixo. Como recebe o conceito de domínio FilingStatus como argumento, ele foi classificado como lógica de domínio. Mas será que realmente é?

// domain/filing.ts
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: "gray",
    submitted: "blue",
    reviewing: "yellow",
    completed: "green",
    amended: "purple",
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: "작성 중",
    submitted: "제출 완료",
    reviewing: "검토 중",
    completed: "신고 완료",
    amended: "경정청구",
  };
  return labels[status];
}

Embora getStatusBadgeColor e getStatusDisplayText usem o conceito de domínio FilingStatus, o que fazem é apresentação de tela. Se a cor do badge mudar, o negócio não quebra de forma alguma. Colocar essas funções em domain/filing.ts faz o módulo de domínio crescer cada vez mais e mistura a verdadeira lógica de domínio com a lógica de apresentação.

Separando o modelo de domínio e o ViewModel

Há uma maneira prática de resolver esse problema: separar o ViewModel em outro arquivo dentro da mesma pasta de domínio. Em vez de .ui.ts, usar o nome .viewModel.ts cria uma conexão natural com o conceito de ViewModel do padrão MVVM. O próprio nome deixa evidente o papel de "camada que transforma os dados do domínio para a tela".

domains/
└── filing/
    ├── filing.ts              # 순수 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

Movemos getStatusBadgeColor e getStatusDisplayText, vistos anteriormente, diretamente para filing.viewModel.ts. Outras transformações, como getFilingTypeLabel(type: FilingType): string, que convertem o tipo de declaração em um rótulo em coreano, também ficam reunidas ali. filing.ts fica responsável apenas pelas regras de negócio; filing.viewModel.ts, apenas pela apresentação na tela.

O ponto central é a direção das dependências. filing.viewModel.ts importa filing.ts, mas filing.ts jamais importa filing.viewModel.ts. O domínio não conhece a apresentação; a apresentação conhece o domínio. Isso pode ser visto como uma versão em miniatura da regra de dependência (Dependency Rule) de Robert C. Martin.

Coloquei esses arquivos na mesma pasta porque acredito que arquivos que mudam juntos devem ficar no mesmo diretório. Se o tipo FilingStatus receber um novo valor (por exemplo, 'rejected'), tanto filing.ts quanto filing.viewModel.ts precisarão ser alterados. Como estão na mesma pasta, o escopo da mudança fica visível de imediato.

Fronteiras e coesão

Tão importante quanto separar a lógica de domínio é decidir onde traçar as fronteiras. A seguir, organizo alguns problemas de delimitação que encontro com frequência no trabalho.

Os dados tratados no frontend vêm, aproximadamente, de quatro fontes.

• Dados do servidor: recebidos como resposta da API
• Dados derivados: calculados a partir dos dados do servidor
• Estado da UI: usado para controlar a tela e as interações do usuário
• Entrada do usuário: dados que estão sendo preenchidos em um formulário

Misturar esses quatro tipos em um único tipo contamina o modelo de domínio.

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

Nesse tipo, conceitos do domínio, estado da UI e dados temporários estão todos no mesmo recipiente. Sempre que activeStep muda, é como se o domínio da declaração fosse atualizado. (A mudança de etapa de um formulário não é um evento de negócio.)

A solução é separar os tipos de acordo com suas fronteiras. O modelo de domínio contém apenas conceitos de negócio, como id, status e determinedTax; o estado da UI (FilingFormViewState) contém apenas controles da tela, como isExpanded e activeStep; e o estado do formulário (DeductionEditForm) contém apenas os dados temporários que estão sendo preenchidos.

Assim, cada tipo passa a ter um único motivo para mudar. O tipo de domínio só muda quando a legislação tributária muda; o estado da UI, apenas quando o design da tela muda; e o estado do formulário, apenas quando a UX de entrada muda.

Mantenha junto o que muda junto

No DDD de Eric Evans, existe o conceito de Aggregate (agregado): "tratar um cluster de objetos relacionados como uma única unidade". Não é necessário aplicar esse conceito literalmente no frontend, mas vale tomar emprestado seu princípio central: dados e regras que mudam juntos devem ficar juntos.

Em um serviço tributário, por exemplo, Income (renda) e ExpenseRate (coeficiente de despesas) sempre mudam juntos. Quando o tipo de renda muda, o coeficiente de despesas aplicável também muda, o que afeta o cálculo da renda global. Portanto, eles devem ficar coesos em um único arquivo, domain/tax.ts.

Já TaxFiling (declaração) pode mudar independentemente do cálculo do imposto. Mesmo que as regras de transição de estado da declaração mudem, a lógica de cálculo das alíquotas não é afetada. Portanto, o correto é separá-la em domain/filing.ts.

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

Class vs estilo funcional

Depois de chegar até aqui, pode surgir uma pergunta fundamental. Todos os exemplos até agora usaram a combinação de interface com funções puras; a coesão não seria mais natural se representássemos o domínio com Class?

Sim. Quando representamos o domínio com Class, dados e comportamento ficam reunidos em um único objeto, e a coesão aparece diretamente na estrutura do código.

class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === "draft";
  }
 
  canAmend(): boolean {
    return this.status === "completed" && this.filingType !== "amendment";
  }
 
  canSubmit(): boolean {
    return this.status === "draft" && this.determinedTax >= 0;
  }
}
 
const filing = new TaxFilingModel(
  "F-001",
  "completed",
  2025,
  "regular",
  547200,
);
 
filing.canAmend();

Quando usamos Class, o comportamento pertence aos dados. E o sujeito fica claro no ponto de uso. filing.canAmend() é intuitivo como a leitura de uma frase em linguagem natural. O sujeito (filing) e o verbo (canAmend) estão claramente combinados. É como escrever jihoon.eat('감자탕'): dá para ler imediatamente que "Jihoon come gamjatang".

No estilo funcional, por outro lado, fica assim.

canAmend(filing);
eat("jihoon", "감자탕");

No estilo funcional, os dados existem do lado de fora. Os dois códigos acima recebem os dados filing como argumento e executam uma operação. A função eat recebe os dados jihoon e 감자탕 como argumentos e é executada.

Com isso, a ligação entre sujeito e verbo fica mais frouxa. Para saber que a função canAmend está relacionada a TaxFiling, é necessário abrir o arquivo ou conferir a assinatura do tipo. Se funções como canAmend(filing), canEdit(filing) e calculateTax(taxableBase) estiverem misturadas no mesmo arquivo, pode ficar difícil perceber de imediato a qual domínio cada função pertence.

Então devemos usar Class?

Sinceramente, a resposta é "depende da situação". Mas, segundo minha experiência, há motivos práticos para Class não ser uma solução universal em ambientes React + TypeScript.

Atrito com o gerenciamento de estado do React

O gerenciamento de estado do React combina de forma mais natural com Plain Object. Tecnicamente, useState e useReducer podem conter qualquer valor, e o Redux DevTools não remove por si só o protótipo de uma instância de Class. Porém, quando o middleware de persistência de Redux/Zustand salva e restaura o estado como JSON, uma instância de Class perde seus métodos e seu protótipo no ciclo de JSON.stringify → JSON.parse e se degrada em plain object. A fronteira de props entre React Server Component e Client Component tem outra restrição: aceita apenas valores serializáveis (serializable) compatíveis, portanto uma instância arbitrária de Class não pode atravessá-la.

Observe o código abaixo.

const [filing, setFiling] = useState(
  new TaxFilingModel("F-001", "draft", 2025, "regular", 0),
);

Atualizar o estado do React, por si só, não faz filing deixar de ser uma instância de TaxFilingModel. Porém, se a persistência de Redux/Zustand o salvar e restaurar como JSON, o valor recuperado pode ser um plain object sem métodos, e uma chamada desatenta a filing.canAmend() pode provocar um erro em runtime. Ao transmiti-lo de React Server Component para Client Component, a falha acontece antes, porque uma instância de Class não é um valor serializável de props compatível.

Dificuldade de garantir imutabilidade

O React detecta mudanças de estado com base em igualdade referencial (referential equality). Se um método de uma instância de Class fizer uma mutação interna como this.items.push(...), a referência permanecerá a mesma e o React não disparará uma nova renderização. Por isso, no fim, é preciso escrever addDeduction(item) de modo que retorne uma nova instância toda vez, como em return new DeductionList([...this.items, item]); isso esvazia a vantagem da Class de oferecer uma "mudança de estado encapsulada". O código deixa de ser muito diferente de uma atualização funcional.

Estratégias para obter coesão no estilo funcional

Então, como melhorar no estilo funcional o problema da coesão frouxa visto em eat('jihoon', '감자탕')? Apresento três métodos que considero eficazes.

Obter coesão com namespace de módulo

É o método mais intuitivo. Transformamos o próprio arquivo (módulo) em uma unidade de domínio e usamos um namespace na importação. Basta usar diretamente o domain/filing.ts que definimos anteriormente.