Esta nota explica o ciclo de vida de um sistema com modelo de linguagem: descoberta, protótipo, conjunto de avaliação, integração, produção, monitoramento e iteração. Ela responde a uma pergunta que parece simples e não é: em que ordem um projeto com modelo de linguagem deve nascer, ser validado, ir para produção e ser mantido?

Pense numa cozinha que depende de um ingrediente comprado de um fornecedor. Um dia o ingrediente muda de sabor, e a receita que funcionava passa a errar sem que ninguém tenha mexido em nada na cozinha. Com um sistema que usa um modelo de linguagem acontece algo parecido. O código pode estar intacto e a resposta ainda assim mudar, porque mudou o modelo, o prompt ou uma ferramenta que o modelo chama. Por isso o ciclo de vida desse tipo de sistema ganha etapas que um software tradicional não precisa, como avaliar com casos de teste, versionar o prompt e liberar uma mudança aos poucos. Ao fim desta aula você deve conseguir desenhar essas etapas, dizer onde uma avaliação bloqueia uma mudança e explicar por que cada etapa existe.

Mapa da aula

Pré-requisitos: Spec-driven development para a parte de descoberta e requisitos, e Avaliação de RAG para a ideia de medir antes de mudar. Os diagramas seguem um mapa de cores fixo: laranja é o que a pessoa controla (perguntas, prompts, iteração), azul são as decisões de gate, verde é o que está em produção e medido, claude é o artefato do sistema (conjunto de avaliação e integração), e rosa é o que dá errado.

Parte 1: o terreno

1. o que compõe um sistema com LLM

Um sistema com LLM é um programa que, em algum ponto, pede a um modelo de linguagem que produza texto e usa esse texto para decidir algo. Um chat de atendimento, um classificador de tickets e um agente que consulta pedidos são exemplos. Em todos eles aparecem quatro peças que mudam o comportamento final, e cada uma pode mudar sozinha.

O modelo é o motor que gera a resposta. A Anthropic publica modelos com nomes como claude-haiku-5-5, e cada um tem características próprias de custo, latência e qualidade. O prompt é o texto que o programa envia ao modelo junto com a pergunta do usuário: instruções, exemplos e regras. As ferramentas são funções que o modelo pode pedir para executar, como consultar um pedido num banco de dados. A descrição de cada ferramenta e o formato dos seus argumentos também fazem parte do comportamento, porque o modelo lê essas descrições para decidir quando chamar cada uma. Por fim, o conjunto de avaliação é a lista de casos, com a regra de correção de cada um, que diz se a resposta do sistema é aceitável.

A palavra “avaliação” aparece aqui com um sentido que talvez você não tenha visto antes. Trata-se de um teste executado sobre o sistema inteiro, com entradas fixas e um critério escrito antes de rodar, e não de uma nota da equipe nem de uma revisão de código. A seção 5 explica como ela é montada. Por enquanto, guarde a ideia de que uma avaliação é o equivalente de um teste automatizado para uma saída que muda de um dia para o outro.

2. por que o ciclo tradicional não basta

O ciclo clássico de software, com requisitos, desenvolvimento, testes, implantação e manutenção, supõe que a mesma entrada produz a mesma saída. Um teste unitário afirma que somar 2 e 3 dá 5, e essa afirmação vale para sempre enquanto o código não mudar. Com um modelo de linguagem a regra muda. A mesma pergunta pode gerar respostas diferentes em duas chamadas seguidas, porque a geração é amostrada, e uma atualização de modelo ou de prompt pode alterar o comportamento inteiro sem que nenhuma linha do seu código tenha sido tocada.

A consequência prática é que o “funciona na minha máquina” ganha uma versão mais difícil: funciona com este prompt, neste modelo, com estas ferramentas, neste dia. Se qualquer um desses quatro fatores mudar, a afirmação deixa de valer. Um ciclo de vida que ignora isso entrega um sistema que passou pelos testes e erra na primeira semana de uso real, porque os testes verificavam o código e não o comportamento.

Daí vêm as etapas extras deste ciclo. A avaliação substitui o teste unitário como régua para o comportamento. O versionamento de prompt, modelo e ferramentas permite saber o que estava rodando quando algo deu errado. A implantação gradual limita o estrago de uma mudança ruim. E o monitoramento existe porque o conjunto de avaliação só cobre os casos que alguém imaginou, e os usuários sempre trazem casos que ninguém imaginou.

Parte 2: as sete fases

Uma observação antes das fases. A ordem que você vai ler, com descoberta, protótipo, conjunto de avaliação, integração, produção, monitoramento e iteração, é uma organização que faz sentido na prática, e não uma sequência oficial publicada pela Anthropic. As páginas da documentação que consultei descrevem avaliação, critérios de sucesso e práticas de produção, mas não prescrevem essas sete fases com esses nomes. A seção 17 lista o que não consegui confirmar nas fontes.

A figura mostra o caminho principal de cima para baixo e da esquerda para a direita. Você começa em descoberta e protótipo, passa pelo conjunto de avaliação, e só chega à integração se o losango “Eval passou?” disser sim. Depois da produção, o monitoramento alimenta a iteração, e a iteração pode gerar uma falha que volta para o conjunto de avaliação como um caso novo. Esse retorno é o ponto mais importante do diagrama: o ciclo se fecha porque cada falha de produção vira um teste permanente.

A figura mostra as sete fases em uma linha, com os portões de avaliação marcados. As seções seguintes explicam cada fase e o que a faz passar ou parar.

3. descoberta

A descoberta é a fase em que você decide o que o sistema precisa fazer bem e o que é inaceitável que faça errado. Ela parece burocracia, mas é onde a equipe resolve a pergunta mais difícil do projeto: qual erro custa caro? Num assistente que responde sobre preços, um preço inventado pode gerar reclamação. Num sistema que resume prontuários, o mesmo erro pode causar dano de verdade. Cada caso pede um nível de cuidado diferente, e essa diferença precisa estar escrita antes de qualquer prompt.

Na descoberta você também define quem usa o sistema, em que situações e com que frequência. O resultado é um critério de sucesso que se possa medir. A documentação da Anthropic sobre criação de avaliações pede critérios específicos e mensuráveis, e dá um contraexemplo claro: “o modelo deve classificar bem os sentimentos” não serve, porque não diz o que é bem nem como contar. Um critério bom diz algo como “menos de 0,1% das respostas, em 10 mil execuções, marcadas como tóxicas pelo filtro”. A diferença é que o primeiro critério não pode ser verificado e o segundo pode. Este é o mesmo raciocínio de Spec-driven development aplicado a um comportamento que muda: a spec precisa ser testável antes de ser implementada.

A saída desta fase é uma lista curta de requisitos com critérios mensuráveis e a marcação dos erros que não são aceitáveis em hipótese alguma. Essa marcação importa mais adiante, porque ela decide quais casos viram gate.

4. protótipo

O protótipo é a fase em que você escreve o primeiro prompt, conecta o modelo e vê algo funcionar. Ele serve para testar uma hipótese, como “um prompt com três exemplos resolve a triagem de tickets”, e não para decidir se o sistema está pronto. O erro clássico é tomar a impressão do protótipo como prova. Cinco perguntas bem escolhidas parecem convincentes e escondem falhas, pelo mesmo motivo que a Avaliação de RAG mostra logo na primeira seção: quem escreve as perguntas tende a escolher as que o sistema responde bem.

Por isso o protótipo produz duas coisas, o prompt versão 1 e uma coleção bruta de entradas reais ou plausíveis, que será a matéria-prima do conjunto de avaliação. Anote desde já o que o prompt pressupõe, porque essas suposições viram os casos de borda da fase seguinte.

5. conjunto de avaliação

O conjunto de avaliação é a régua fixa contra a qual todas as mudanças serão medidas. Esta é a fase mais importante do ciclo, e a que mais sustenta o restante. Antes de explicar como ela se monta, vale fixar quatro termos que a documentação da Anthropic usa para descrever avaliações de agentes, mas que servem para qualquer sistema com LLM. Uma tarefa é um teste isolado, com entradas definidas e critério de sucesso. Um trial é uma execução de uma tarefa, e como a saída varia, a mesma tarefa é executada várias vezes. Um grader é a lógica que dá nota ao desempenho, podendo ser código, uma comparação de texto ou outro modelo. O transcript é o registro completo de um trial, com entradas, chamadas, saídas e resultados intermediários, e o outcome é o estado final ao fim do trial.

A distinção entre transcript e outcome é mais útil do que parece. Um sistema pode dizer “cancelei o pedido” sem ter cancelado nada. Quem julga só pelo texto aprova a resposta, e quem olha o outcome descobre que o pedido continua ativo. Em sistemas com ferramentas, o outcome é a verdade que importa, e o transcript serve para explicar por que a falha aconteceu.

Como montar o conjunto? A Anthropic recomenda começar com 20 a 50 tarefas simples, tiradas de falhas reais, e diz que esse número já é um bom começo. As fontes são os testes manuais que a equipe já faz durante o desenvolvimento, o histórico de bugs e a fila de suporte, com cada falha reportada transformada em caso de teste. Os casos de borda entram por obrigação: entradas vazias ou sem sentido, perguntas muito longas, entradas maliciosas e casos ambíguos em que nem duas pessoas concordariam. Sem eles, o conjunto mede só o caminho feliz, que é justamente o que o protótipo já mostrou funcionar.

A documentação também recomenda priorizar volume a qualidade artesanal quando a correção puder ser automatizada. Um conjunto grande com correção por código ou por um juiz vale mais do que poucos casos corrigidos à mão, porque é o volume que permite rodar a suíte a cada mudança. Os tipos de correção mais citados são a comparação exata depois de normalizar espaços e maiúsculas, a comparação por substring ou expressão regular, a verificação de estado no outcome e o juiz modelo, que lê a resposta e aplica uma rubrica. A página também recomenda que o juiz seja um modelo diferente do que gerou a resposta avaliada, para reduzir o viés de avaliar a própria escrita. Esse ponto fica registrado como orientação geral da página, sem medição minha.

Um cuidado de método completa a seção. O conjunto de avaliação não pode ser usado para ajustar o sistema, porque, se você escolhe o prompt olhando os mesmos casos que decidem o deploy, o conjunto deixa de medir algo novo e passa a medir a sua memória. Os times costumam guardar um conjunto de desenvolvimento para explorar e um conjunto de avaliação intocado para decidir.

6. integração e o gate que bloqueia

A integração é o momento em que o prompt, o código que chama o modelo e as ferramentas entram no repositório principal. É aqui que a avaliação deixa de ser uma atividade ocasional e passa a ser um portão. Um gate é uma verificação automática que impede a passagem para a etapa seguinte quando falha. Na prática, ele roda a suíte de avaliação sobre a mudança proposta e reprova a integração se um caso crítico falhar, se a taxa geral cair abaixo de um limiar ou se uma categoria inteira piorar em relação à versão atual.

A documentação da Anthropic sobre avaliação de agentes diz que as avaliações automatizadas são úteis no CI/CD, rodando a cada mudança do agente e a cada atualização de modelo. Essa é a base da regra que a aula defende: toda mudança que pode alterar o comportamento passa pela suíte. Essa lista é longa. Inclui mudanças óbvias, como editar o prompt, e mudanças que muita gente não trata como risco, como trocar a versão de um modelo, mudar a descrição de uma ferramenta, alterar o formato de um argumento ou atualizar um parâmetro de amostragem. A descrição de uma ferramenta é texto que o modelo lê, então uma edição de duas palavras nela pode mudar quando o modelo a chama.

Um gate precisa de limiares escritos antes de rodar. Limiar decidido depois de ver o resultado vira racionalização. Um critério razoável separa os casos críticos, que não admitem falha, dos casos comuns, que toleram uma taxa de erro acordada. A seção 13 mostra um gate pequeno que faz exatamente essa separação.

O gate de integração bloqueia a mudança. O gate de produção, que aparece na seção 7, decide se a mudança que já passou pela integração recebe tráfego real. São dois portões com perguntas diferentes: o primeiro pergunta se a mudança é aceitável sobre o conjunto fixo, e o segundo pergunta se ela continua aceitável com usuários reais.

7. produção e implantação gradual

Produção é o momento em que o sistema responde a usuários de verdade. Uma mudança que passou no gate de integração ainda não está provada, porque o conjunto de avaliação tem o tamanho que tem, e o tráfego real vai trazer entradas que ele não cobre. A implantação gradual responde a isso expondo a nova versão a uma parte pequena do tráfego enquanto a versão anterior atende o resto. Essa parte pequena é chamada de canário, por analogia aos canários de minas, e o princípio é que um problema grave apareça em poucos usuários antes de atingir todos.

A divisão do tráfego deve ser estável por usuário. Se a mesma pessoa alterna entre duas versões a cada pergunta, a experiência oscila e a telemetria fica difícil de interpretar. Um jeito simples é calcular uma faixa a partir do identificador do usuário e mandar para o canário só quem cai numa faixa fixa, como faz a função da seção 13.

A figura abaixo mostra o caminho completo, incluindo o que acontece quando o gate reprova.

O candidato sai com o manifesto registrado e passa pelo primeiro losango. Se o gate reprova, a mudança vai para um estado bloqueado, e a produção continua intacta, o que é justamente o motivo de existir esse portão. Se aprova, 5% do tráfego vai para a versão nova, ao lado da versão 6. A telemetria alimenta o segundo losango, que compara as métricas do canário com as da versão antiga. Se as métricas estão bem, o tráfego sobe para 100% e a nova versão vira a estável. Se não estão, o caminho pontilhado leva ao rollback, que restaura a versão anterior. Os percentuais e os nomes de estágios são uma escolha de engenharia, e a documentação da Anthropic não os prescreve. A própria figura serve para ver o que é de fato obrigatório: um critério de promoção, um critério de reversão e uma versão anterior guardada.

8. monitoramento

Monitoramento é o que acontece depois que a mudança chega a todos os usuários, e é onde o ciclo de vida fica mais longo. A seção 5 explicou que o conjunto de avaliação só cobre o que alguém imaginou. A produção mostra o resto, e a documentação da Anthropic sobre avaliação de agentes diz que o monitoramento em produção serve para detectar desvio de distribuição e falhas que os testes não previram. Ele complementa a avaliação offline, e é dele que sai o material para a próxima versão do conjunto.

A figura organiza o que monitorar em quatro frentes, e cada uma responde a uma pergunta diferente.

A primeira frente é a qualidade, medida por sinais como o polegar para baixo, a reformulação da pergunta logo depois de uma resposta, a taxa de recusa e as citações quebradas, quando o sistema as usa. Esses sinais são imperfeitos, porque o usuário que desiste não reclama, mas são os únicos que indicam o que a suíte de avaliação deixou passar. A segunda frente é o custo, e a conta certa é a de custo por tarefa concluída, não o preço por token. O guia de otimização de custo da Anthropic, em trecho que consultei por busca, diz exatamente isso: um modelo mais barato que precisa de mais turnos ou de mais repetições pode sair mais caro no total. A terceira frente é a latência, medida em percentis. A média esconde a cauda, e é a cauda que o usuário sente, por isso o p95 importa mais do que a média. A quarta frente são os erros, e aqui a distinção entre tipos de erro muda a ação. Um erro 429 com cabeçalho retry-after pede espera pelo tempo indicado. Um 529 de sobrecarga pede nova tentativa com espera crescente, e um 500 de erro interno também pede nova tentativa, com registro do identificador da requisição para o suporte se persistir. O 429 de limite de gasto é diferente: não traz retry-after e não se resolve repetindo a chamada, então precisa de alerta humano.

O losango de limite na figura liga as quatro frentes a uma decisão. Um limite estourado, mantido por tendência e não por um pico isolado, leva à triagem: um caso novo entra no conjunto de avaliação, ou a versão é revertida. O monitoramento só cumpre seu papel se alguém tiver o poder de agir sobre o que mostra.

9. iteração

Iteração é a fase que fecha o ciclo. A regra que recomendo, e que não encontrei escrita como orientação oficial da Anthropic, é mudar uma coisa de cada vez, medir e liberar. Se você troca o prompt, o modelo e uma ferramenta na mesma versão e o resultado melhora, não sabe qual das três mudanças foi responsável, nem se alguma piorou algo que não estava sendo medido. Mudar uma coisa por vez custa mais rodadas, e é isso que permite atribuir um efeito a uma causa.

A iteração também devolve falhas ao conjunto. Cada falha de produção que foi triada e confirmada vira um caso novo, com o resultado esperado escrito. Por isso o conjunto de avaliação cresce com o tempo, e o gate de amanhã protege contra o erro de ontem. A Anthropic chega a sugerir essa conversão explicitamente, transformando falhas reportadas por usuários em casos de teste.

Parte 3: versões e reprodução

10. o que versionar

Versionar é registrar, para cada versão do sistema, a combinação exata de peças que estava rodando. No caso de um sistema com LLM são quatro peças: o prompt, o modelo, as ferramentas e o conjunto de avaliação usado para aprovar a versão. Cada uma tem seu próprio histórico, e a versão do sistema é o conjunto desses quatro identificadores.

O motivo é reproduzir um problema. Imagine um relato dizendo que o sistema respondeu errado na terça-feira. Sem registro, a equipe sabe apenas que alguma coisa mudou entre a terça e hoje, e não sabe o quê. Ao testar de novo, o problema pode não aparecer, porque o prompt foi trocado, ou porque o modelo mudou de versão, ou porque o resultado depende de uma amostragem que varia. A figura mostra os dois caminhos.

A linha de cima representa o caso sem registro. O relato chega, a equipe não consegue responder qual combinação rodou, e o problema não reproduz. A linha de baixo mostra o caso com manifesto. O relato traz o identificador da versão, o manifesto diz o prompt, o modelo, as ferramentas e os casos, e o replay roda exatamente essa combinação. Se o problema aparece no replay, a causa fica isolada. Veja o campo de ferramentas no exemplo: a versão está escrita como pedidos@3. Com esse identificador você sabe qual versão da ferramenta estava ativa e pode recuperar a descrição e o formato de argumentos que foram guardados nela.

Há uma ressalva técnica que a documentação faz e que afeta essa reprodução. Os identificadores de modelo a partir da geração 4.6 são snapshots fixos: o peso e a configuração de um ID não mudam. Mas a documentação também diz que a infraestrutura em volta do modelo, como o roteador, os classificadores de segurança e a amostragem, pode mudar, e que atualizações de infraestrutura podem produzir pequenas diferenças de comportamento mesmo com o mesmo ID. Ou seja, fixar o modelo é necessário, e não garante reprodução exata byte a byte. Por isso o conjunto de avaliação faz parte do manifesto: ele permite reavaliar a versão antiga com a mesma régua quando há dúvida.

11. modelos, snapshots e aposentadoria

Vale separar três coisas que costumam ser confundidas. A primeira é o ID de modelo com data, como claude-haiku-4-5-20251001. A documentação diz que os modelos anteriores à geração 4.6 incluem uma data de snapshot no ID, e que alguns nomes curtos, como claude-sonnet-4-5, são apelidos que apontam para o snapshot mais recente daquela versão menor. Apelido não é fixo, porque muda quando sai um snapshot novo.

A segunda é o ID sem data da geração 4.6 em diante, como claude-sonnet-4-6 ou claude-haiku-5-5. Aqui a documentação é explícita: esse ID é um snapshot fixo, e não um ponteiro para a melhor versão disponível. Quando sai uma versão atualizada, ela chega com um ID novo. Essa é a tradução correta para o manifesto: o campo do modelo guarda o ID completo e nunca um apelido.

A terceira é o ciclo de aposentadoria. A página de depreciações lista os estados Ativo, Legado, Depreciado e Aposentado. Um modelo depreciado ainda funciona, mas não é recomendado, e a documentação afirma que modelos depreciados tendem a ser menos confiáveis. Um modelo aposentado não aceita mais requisições, que falham. A Anthropic informa que notifica clientes com implantações ativas e dá pelo menos 60 dias de aviso para modelos publicamente lançados. Na tabela de status que consultei, o Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) aparece como depreciado, com aposentadoria prevista para 30 de novembro de 2026 e substituição recomendada pelo claude-sonnet-5-5. Para o ciclo de vida, a consequência é que a troca de modelo é uma mudança obrigatória com prazo, e não uma escolha opcional. Ela entra no mesmo caminho de gate, canário e rollback das seções 6 a 7, e deve começar bem antes da data de aposentadoria.

Uma última ressalva da mesma página ajuda a entender por que o manifesto inclui parâmetros. A partir do Claude 4.7, os parâmetros temperature, top_p e top_k retornam erro 400 quando recebem valor diferente do padrão. Um sistema que migra de modelo e carrega esses parâmetros pode quebrar sem nenhuma mudança de lógica. Esse tipo de quebra é exatamente o que a avaliação pega antes da produção.

12. rollback

Rollback é voltar para a versão anterior quando a nova falha em produção. A ideia parece óbvia e tem uma exigência que a torna possível: a versão anterior precisa estar guardada e pronta para ser reativada. Na prática, isso significa que o manifesto da versão 6 continua registrado, com o prompt, o modelo e as ferramentas que ela usava, e que trocar a versão ativa é uma operação pequena, feita por um ponteiro, e não uma reconstrução do sistema.

A documentação da Anthropic sobre Skills em ambiente corporativo trata deste ponto de forma direta, e vale citar o princípio, mesmo que ele seja sobre Skills e não sobre prompts em geral. A recomendação é fixar a versão em produção, em vez de usar sempre a mais nova, porque sem o fixador uma versão enviada por qualquer pessoa muda imediatamente o que a produção executa. A mesma página recomenda manter a versão anterior como alternativa e, se a nova falhar nas avaliações em produção, voltar à última versão boa imediatamente. Ela também recomenda guardar a fonte em Git, o que dá histórico e reversão. Esse é o mesmo padrão que o exemplo da seção 13 implementa com um ponteiro.

Na figura 3, o rollback aparece como o caminho pontilhado que sai do losango de métricas e restaura a versão 6. Repare que a seta de volta para o canário também está pontilhada: o tráfego volta para a versão estável, e o canário deixa de existir como versão em uso. Um rollback bem feito não exige nova avaliação para reativar a versão antiga, porque ela já foi aprovada antes. O que exige atenção é a causa da reversão, que deve voltar ao conjunto de avaliação como caso novo, conforme a seção 9.

Parte 4: exemplo executado

13. gate, canário e rollback em código

O exemplo a seguir é um gate de avaliação pequeno, executável com a biblioteca padrão do Python, sem chamar nenhuma API. Ele roda sobre respostas gravadas, uma técnica chamada replay, que relê saídas guardadas em vez de gerar outras. Isso torna o exemplo barato e determinístico, mas também significa que as respostas são fixas e foram escritas para mostrar o mecanismo. O código não mede a qualidade de nenhum modelo real. Ele mostra como o gate decide, como o canário distribui o tráfego e como o ponteiro volta atrás.

O manifesto e a função de decisão do gate ficam assim:

MANIFESTOS = {
    "v6": {"prompt": "atendimento@6", "modelo": "claude-haiku-5-5", "ferramentas": "pedidos@3", "casos": "casos@2026-10"},
    "v7": {"prompt": "atendimento@7", "modelo": "claude-haiku-5-5", "ferramentas": "pedidos@3", "casos": "casos@2026-10"},
}

LIMIAR_GERAL = 0.85
QUEDA_MAXIMA_CATEGORIA = 0.20

def gate(candidato, base):
    r = avalia(candidato)
    b = avalia(base)
    motivos = []
    for c in CASOS:
        if c["critico"] and not r[c["id"]]:
            motivos.append(f"caso crítico {c['id']} falhou")
    taxa = sum(r.values()) / len(r)
    if taxa < LIMIAR_GERAL:
        motivos.append(f"taxa geral {taxa:.2f} abaixo de {LIMIAR_GERAL}")
    cat_base, cat_cand = por_categoria(b), por_categoria(r)
    for cat in cat_base:
        queda = cat_base[cat] - cat_cand[cat]
        if queda > QUEDA_MAXIMA_CATEGORIA:
            motivos.append(f"categoria {cat} caiu {queda:.2f} em relação à base")
    estado = "aprovado" if not motivos else "bloqueado"
    return estado, taxa, motivos

def no_canario(usuario, percentual=5):
    h = int(hashlib.sha256(usuario.encode()).hexdigest(), 16)
    return h % 100 < percentual

As funções avalia e por_categoria, e os dados de CASOS e RESPOSTAS, foram omitidos por tamanho. O script completo foi executado com a biblioteca padrão do Python 3 e a saída real foi esta:

manifesto v7:
{
  "prompt": "atendimento@7",
  "modelo": "claude-haiku-5-5",
  "ferramentas": "pedidos@3",
  "casos": "casos@2026-10"
}

v7_regressao: bloqueado (taxa geral 0.75)
  - caso crítico c4 falhou
  - taxa geral 0.75 abaixo de 0.85
  - categoria prazo caiu 0.50 em relação à base
  - categoria cancelamento caiu 0.50 em relação à base

v7_ok: aprovado (taxa geral 1.00)

canário 5%: 511 de 10000 usuários caem no candidato
mesmo usuário, mesma faixa: True

produção em v7; falha detectada; rollback para v6
ponteiro de produção agora: v6 {"prompt": "atendimento@6", "modelo": "claude-haiku-5-5", "ferramentas": "pedidos@3", "casos": "casos@2026-10"}

A primeira linha de resultado mostra o gate fazendo o trabalho dele. O candidato v7_regressao falhou no caso crítico c4, que pede a possibilidade de cancelar o pedido. Além disso, a taxa geral ficou em 0,75, abaixo do limiar de 0,85, e duas categorias caíram 0,50 em relação à base. Os quatro motivos aparecem juntos porque o gate verifica tudo e não para no primeiro erro, o que ajuda a triagem. A segunda linha mostra a versão que passa, com taxa de 1,00. Repare que o gate não reprova a versão 7 apenas por ser diferente: ela só entra no canário porque nenhum dos critérios foi violado.

O canário mandou 511 de 10 mil usuários simulados para o candidato, algo próximo de 5%. O número exato depende dos identificadores, e por isso o resultado não é exatamente 500. O ponto de interesse é a segunda linha da seção: o mesmo usuário cai sempre na mesma faixa, o que mantém a experiência estável. O rollback, por fim, é a troca de um ponteiro de volta para a v6, que já estava registrada. Nada foi recompilado nem reimplantado nesse passo, e é isso que torna a reversão rápida.

Parte 5: erros e prática

14. erros comuns e boas práticas

O primeiro erro é tratar o protótipo como prova. Cinco exemplos bons mostram que o sistema funciona na demonstração e não dizem nada sobre o uso real. A boa prática é transformar o protótipo em conjunto de avaliação antes de qualquer decisão de lançamento, com casos reais, casos de borda e critérios escritos.

O segundo erro é fixar o modelo por apelido. Um nome como claude-sonnet-4-5 aponta para o snapshot mais recente daquela versão menor, então a produção muda quando sai um snapshot novo, sem nenhuma decisão da equipe. A boa prática é usar o ID completo no manifesto e tratar a troca de modelo como mudança que passa pelo gate.

O terceiro erro é mudar o prompt sem rodar a suíte, sob a justificativa de que a mudança é pequena. Uma palavra alterada numa instrução pode mudar o comportamento em casos que ninguém revisou. A boa prática é tratar qualquer alteração de texto que o modelo lê como mudança de comportamento, porque é isso que ela é.

O quarto erro é julgar a qualidade com um juiz que nunca foi comparado a pessoas. A página de desenvolvimento de testes recomenda um modelo juiz diferente do gerador, e uma boa prática adicional é conferir uma amostra de casos à mão para ver se o juiz concorda com as pessoas que conhecem o domínio. A medição de concordância é o que dá crédito ao juiz, e ela não se herda de outro projeto.

O quinto erro é monitorar só o código de erro HTTP. Um sistema pode responder 200 o tempo todo e entregar respostas erradas, ou responder rápido e caro. A boa prática é olhar as quatro frentes da seção 8, com a qualidade e o custo por tarefa tão visíveis quanto a taxa de erro.

O sexto erro é não ter rollback testado. Uma versão antiga que nunca foi reativada pode não funcionar mais, porque uma dependência mudou, um identificador foi aposentado ou um parâmetro deixou de ser aceito. A boa prática é manter a versão anterior pronta para reativar e exercitar esse caminho de vez em quando, e não apenas no dia em que ele é necessário.

Por fim, o erro que mais aparece em revisões: confiar em um número sem tamanho de amostra. Diferenças pequenas em conjuntos pequenos são ruído, e uma melhora de dois pontos em 50 casos não prova nada. A boa prática é relatar o tamanho da amostra junto com a taxa e tratar diferenças pequenas como inconclusivas, como a Avaliação de RAG mostra com testes pareados.

Parte 6: prática, glossário e limites

15. exercícios

1. Escreva, para um sistema que você conhece, o manifesto da versão atual com quatro campos: prompt, modelo, ferramentas e conjunto de avaliação. Se algum campo não puder ser preenchido com um identificador exato, anote isso como risco.
2. Pegue dez falhas reais, ou imagine dez, e para cada uma diga se ela deveria virar caso crítico, caso comum ou caso de borda. Justifique a escolha em uma frase.
3. Um gate tem limiar geral de 0,90 e um caso crítico. O candidato acerta 9 de 10 casos comuns e erra o crítico. Ele passa? Explique por que o caso crítico basta para bloquear, mesmo com a taxa geral exatamente no limiar.
4. Na seção 13, troque QUEDA_MAXIMA_CATEGORIA de 0,20 para 0,60 e imagine o resultado com as mesmas respostas. Quais motivos de bloqueio desaparecem, e por quê? Que motivos continuam? O que isso diz sobre escolher limiares depois de ver o resultado?
5. Desenhe, em papel, o caminho que um relato de falha percorre até virar caso de teste. Identifique em qual etapa a informação do manifesto é indispensável.
6. Calcule o custo por tarefa concluída de duas configurações hipotéticas: uma com menos tokens por chamada e três tentativas, outra com mais tokens e uma tentativa. Qual é mais barata na média, e o que muda se a taxa de sucesso da primeira for 60%?

16. glossário

17. o que não ficou verificado

Esta seção existe porque algumas afirmações desta aula não têm confirmação na documentação que consegui ler, e a aula precisa dizer isso.

As sete fases e seus nomes são uma organização didática minha. A documentação da Anthropic não as prescreve, e não encontrei uma sequência oficial com esses rótulos.

Os valores de canário, como os 5% do exemplo, e os estágios de promoção são práticas de engenharia comuns, citadas aqui como escolha e não como recomendação da Anthropic. Não encontrei na documentação consultada uma orientação específica sobre implantação gradual de prompts ou de modelos.

Não encontrei na documentação consultada uma orientação específica sobre versionamento de prompts. O princípio de fixar versões e manter a anterior como alvo de rollback vem da página sobre Skills em ambiente corporativo, aplicado aqui por analogia.

A cartilha de boas práticas para produção que a Anthropic publica em PDF não pôde ser lida pela ferramenta de consulta, porque o arquivo chegou em formato binário. Por isso não cito nada dela.

A página completa sobre criação de avaliações tem cerca de 153 mil caracteres, e a ferramenta de leitura alcançou só os primeiros 100 mil. Os princípios citados vêm dessa leitura parcial, e a parte final da página não foi conferida. A página de erros da API e a página de limites de taxa foram consultadas por resumo de busca, e não por leitura integral. O mesmo vale para o guia de otimização de custo e para o artigo de sistema multiagente, de onde vêm os 20 casos iniciais, que usei apenas como exemplo.

Os números do exemplo da seção 13 foram produzidos pelo script com respostas gravadas que escrevi. Eles mostram o mecanismo e não medem nenhum modelo real.

Os detalhes de aposentadoria de modelos mudam com frequência. Os dados desta aula valem para a consulta de 18 de outubro de 2026, e a página de depreciações deve ser conferida antes de qualquer migração.

Fontes

Consultadas em 18 de outubro de 2026.

• Demystifying evals for AI agents, Anthropic: termos de tarefa, trial, grader, transcript e outcome, a sugestão de começar com 20 a 50 tarefas tiradas de falhas reais e a menção à execução em CI/CD.
• Create strong empirical evaluations, Claude Platform Docs: critérios específicos e mensuráveis, casos de borda, automação, graders por código e por modelo, e a recomendação de juiz diferente do gerador. Lida até o caractere 100 mil de um texto maior.
• Model IDs and versioning, Claude Platform Docs: snapshots fixos a partir da geração 4.6, apelidos anteriores e a ressalva sobre a infraestrutura.
• Model deprecations, Claude Platform Docs: estados do ciclo de vida, aviso de pelo menos 60 dias, falha de requisições após aposentadoria, tabela de status e parâmetros depreciados.
• Skills for enterprise, Claude Platform Docs: fixação de versão em produção, versão anterior como alvo de rollback, gate de avaliação antes de promover e Git como fonte.
• Claude API errors, Claude Platform Docs: consultada por resumo de busca. Códigos 429, 500 e 529, retry-after e retentativas automáticas dos SDKs.
• Cost Optimization on the Claude API, Claude Cookbook: consultada por trecho de busca. Custo por tarefa concluída em vez de preço por token.

Relacionados

• Avaliação de RAG
• Spec-driven development