Estudo de Caso: Arquitetando um Bot de Revisão de Código e Pipeline de Processamento de Documentos

Este checklist percorre a arquitetura de duas compilações de produção ilustrativas: um bot automatizado de revisão de código que comenta em pull requests e um pipeline de processamento de documentos que classifica e extrai dados estruturados de arquivos recebidos.

Ambos são arquiteturas de exemplo realistas destinadas a sintetizar os domínios do exame CCA Foundations, não estudos de caso publicados reais da Anthropic, e os detalhes abaixo são ilustrativos em vez de números de produção medidos.

Eles são apresentados juntos porque compartilham um tema arquitetônico que vale a pena internalizar para o exame: limite a superfície de saída do modelo de forma tão restrita que um erro seja barato e fácil de capturar, seja esse erro um comentário de código ruim ou um documento mal classificado.

Como Usar Este Checklist

Trate as duas compilações como estudos de caso paralelos; trabalhe em um completamente antes de iniciar o outro, pois intercalá-los pode obscurecer qual decisão pertence a qual sistema.
Preste atenção em onde cada sistema traça sua "fronteira de confiança", o ponto além do qual um humano, e não o modelo, toma a decisão final.
Use as etapas numeradas como um modelo para arquitetar um sistema semelhante de sua própria autoria, não apenas como fatos para memorizar.

Bot de Revisão de Código: Etapas da Arquitetura (1-8)

Defina o gatilho. O bot é executado em eventos de criação e atualização de pull request, não em cada commit, para evitar comentar em pushes em andamento.
Busque apenas o diff, não o repositório completo. Puxar a base de código completa para o contexto para cada revisão desperdiça tokens e dilui a relevância; limite a entrada aos arquivos alterados e a uma pequena janela de contexto circundante.
Defina a ferramenta de comentário de forma restrita. Uma única ferramenta post_review_comment que aceita file_path, line_number e comment_text mantém a superfície de saída do bot limitada e auditável, em vez de permitir que ele reescreva arquivos livremente.
Separe a gravidade do conteúdo. Exija que o modelo marque cada comentário com uma gravidade (blocking, suggestion, nitpick) como um campo estruturado, não embutido em prosa, para que ferramentas downstream possam filtrar ou controlar com base nele.
Defina um orçamento de comentários por pull request. Limite o número de comentários que o bot publica por PR (por exemplo, 15) para evitar fadiga de revisão por uma passagem excessivamente falante em um diff grande.
Exija que o bot explique seu raciocínio, não apenas afirme. Um comentário como "isso pode causar uma condição de corrida porque X lê a variável antes que a escrita de Y seja concluída" é revisável; "isso parece errado" não é.
Controle comentários de bloqueio atrás de um limite de confiança. Apenas comentários marcados como blocking devem ser capazes de falhar em uma verificação de CI; a saída de menor confiança permanece consultiva.
Registre cada execução de revisão com o par diff e saída. Armazene o diff que o bot viu ao lado dos comentários que ele produziu, para que uma revisão incorreta ou inútil possa ser depurada posteriormente.

Pipeline de Processamento de Documentos: Etapas da Arquitetura (9-16)

Classifique antes de extrair. Direcione cada documento recebido através de uma etapa de classificação leve (fatura, contrato, currículo, outro) antes de aplicar um prompt de extração específico do tipo de documento.
Use um modelo mais barato e rápido para classificação. Claude Haiku 4.5 é adequado para a etapa de classificação, pois é uma tarefa limitada e de baixa ambiguidade, reservando um modelo mais forte para extração onde a nuance é mais importante.
Defina um esquema de saída rigoroso por tipo de documento. A extração deve ter como alvo um esquema JSON fixo por tipo de documento (por exemplo, fatura: fornecedor, valor, data de vencimento), não um resumo em texto livre, para que sistemas downstream possam consumi-lo de forma confiável.
Valide os campos extraídos contra tipos e intervalos esperados. Uma data de vencimento que é analisada para um ano 300 anos no futuro, ou um valor de zero em uma fatura, deve ser sinalizada para revisão, não aceita silenciosamente.
Direcione extrações de baixa confiança para uma fila de revisão humana. Em vez de forçar todos os documentos à automação completa, defina um limite de confiança ou falha de validação abaixo do qual um humano confirma a extração.
Mantenha o documento original vinculado à sua extração. Cada registro estruturado deve referenciar o arquivo de origem do qual foi extraído, para que um erro downstream seja rastreável de volta ao documento original.
Processe documentos de forma assíncrona, não inline com o upload. Desacople a ingestão de documentos (upload) do processamento (classificar, extrair, validar) com uma fila, para que uma etapa de processamento lenta ou com falha não bloqueie o caminho de upload.
Acompanhe a precisão da extração por tipo de documento ao longo do tempo. Diferentes tipos de documentos terão diferentes perfis de precisão; métricas agregadas sozinhas podem ocultar um tipo de documento com desempenho ruim por trás de números gerais fortes.

Aplicando o Checklist em Ordem

Bot de revisão de código, etapas 1-4: acerte o escopo e o design da ferramenta primeiro; um bot com uma ferramenta de comentário ilimitada é difícil de confiar, independentemente da qualidade do prompt.
Bot de revisão de código, etapas 5-8: adicione orçamento, controle de confiança e registro quando o loop principal funcionar, pois esses são os controles que tornam o bot seguro para ser executado sem supervisão.
Pipeline de documentos, etapas 9-12: classificação, seleção de modelo e rigor do esquema formam a espinha dorsal do pipeline; acerte esses pontos antes de adicionar automação em torno deles.
Pipeline de documentos, etapas 13-16: roteamento de revisão humana, rastreabilidade e processamento assíncrono são os controles operacionais que tornam o pipeline confiável em escala.

FAQs

Essas duas compilações são estudos de caso reais publicados pela Anthropic?

Não. Ambas são arquiteturas de exemplo ilustrativas construídas para sintetizar os domínios do exame CCA Foundations, não estudos de caso publicados reais da Anthropic; os detalhes são realistas, mas construídos para fins de ensino.

Por que o bot de revisão de código busca apenas o diff, não o repositório completo?

Puxar todo o codebase para o contexto para cada revisão desperdiça tokens e dilui a relevância para a alteração real; limitar ao diff mais uma pequena janela circundante mantém o contexto focado e o custo proporcional ao tamanho da alteração.

Por que limitar o número de comentários por pull request?

Um bot sem limites pode causar fadiga de revisão ao postar um número avassalador de comentários de baixo valor em um diff grande; um orçamento força o bot a priorizar o feedback de maior valor.

Qual o objetivo de marcar comentários com gravidade como um campo estruturado?

Um campo de gravidade estruturado (blocking, suggestion, nitpick) permite que ferramentas downstream filtrem ou controlem programaticamente, o que a linguagem de gravidade em texto livre embutida em um comentário não pode suportar de forma confiável.

Por que usar Claude Haiku 4.5 para classificação de documentos, mas não para extração?

A classificação é uma tarefa limitada e de baixa ambiguidade, adequada para um modelo mais rápido e barato, enquanto a extração geralmente envolve mais nuances (interpretação de layouts e linguagem de documentos variados) que se beneficiam de um modelo mais forte.

Por que validar campos extraídos em vez de confiar diretamente na saída estruturada do modelo?

Um modelo pode produzir uma saída sintaticamente válida, mas semanticamente incorreta, como uma data de vencimento no futuro distante ou um valor de fatura de zero dólar; validar campos extraídos contra tipos e intervalos esperados captura esses problemas antes que cheguem aos sistemas downstream.

Por que processar documentos de forma assíncrona em vez de inline com o upload?

Desacoplar o upload do processamento com uma fila significa que uma etapa de processamento lenta ou com falha não bloqueia o caminho de upload voltado para o usuário, o que é importante, pois a latência de extração pode variar muito dependendo da complexidade do documento.

O que deve acontecer quando a extração de um documento tem baixa confiança?

Direcione-o para uma fila de revisão humana em vez de forçar a automação completa em todos os documentos; definir um limite de confiança ou falha de validação é o que torna essa decisão de roteamento consistente em vez de ad hoc.

Por que comentários de bloqueio de revisão de código exigiriam um limite de confiança?

Apenas comentários de alta confiança devem ser capazes de falhar em uma verificação de CI, pois um falso positivo de bloqueio em um comentário de baixa confiança corrói a confiança do desenvolvedor no bot e incentiva as pessoas a ignorá-lo ou contorná-lo.

Por que manter o documento original vinculado ao seu registro extraído?

A rastreabilidade de volta ao arquivo de origem permite que um erro downstream (como um valor incorreto usado em um pagamento) seja investigado contra o documento original real, não apenas os dados extraídos.

O que essas duas arquiteturas de caso de estudo têm em comum?

Ambas limitam a superfície de saída do modelo de forma restrita (uma ferramenta de comentário estreita, um esquema de extração rigoroso) para que os erros sejam baratos e fáceis de detectar e corrigir, em vez de depender do modelo estar certo o tempo todo.

Por que acompanhar a precisão da extração por tipo de documento em vez de apenas no geral?

Números de precisão agregados podem ocultar um tipo de documento com desempenho ruim por trás de um forte desempenho em tipos mais fáceis; o acompanhamento por tipo expõe problemas que as métricas gerais mascarariam.

Relacionados

Estudando Arquitetura e Orquestração de Agentes: o Maior Domínio do Exame CCA - princípios de orquestração por trás do roteamento de documentos através de estágios de classificação e extração.
Design de Ferramentas, Integração MCP e Gerenciamento de Contexto: Checklist de Domínio CCA - a disciplina de escopo de ferramenta por trás da ferramenta de comentário do bot de revisão de código.
Estudo de Caso: Um Assistente de Conhecimento Interno com RAG e Citações - outra compilação centrada em documentos, focada em recuperação em vez de classificação e extração.
Estudo de Caso Antes e Depois: Refatorando um Agente Claude para Reduzir Custos - como as escolhas de seleção de modelo, como a divisão Haiku/Sonnet aqui, afetam o custo em escala.
Melhores Práticas do CCA Foundations - práticas das quais essas duas arquiteturas se baseiam.

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, preços, formato de exame e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs e o guia oficial do exame CCA antes de confiar neles.

Estudo de Caso: Arquitetando um Bot de Revisão de Código e Pipeline de Processamento de Documentos

Como Usar Este Checklist

Trate as duas compilações como estudos de caso paralelos; trabalhe em um completamente antes de iniciar o outro, pois intercalá-los pode obscurecer qual decisão pertence a qual sistema.
Preste atenção em onde cada sistema traça sua "fronteira de confiança", o ponto além do qual um humano, e não o modelo, toma a decisão final.
Use as etapas numeradas como um modelo para arquitetar um sistema semelhante de sua própria autoria, não apenas como fatos para memorizar.

Bot de Revisão de Código: Etapas da Arquitetura (1-8)

Defina o gatilho. O bot é executado em eventos de criação e atualização de pull request, não em cada commit, para evitar comentar em pushes em andamento.
Busque apenas o diff, não o repositório completo. Puxar a base de código completa para o contexto para cada revisão desperdiça tokens e dilui a relevância; limite a entrada aos arquivos alterados e a uma pequena janela de contexto circundante.
Defina a ferramenta de comentário de forma restrita. Uma única ferramenta post_review_comment que aceita file_path, line_number e comment_text mantém a superfície de saída do bot limitada e auditável, em vez de permitir que ele reescreva arquivos livremente.
Separe a gravidade do conteúdo. Exija que o modelo marque cada comentário com uma gravidade (blocking, suggestion, nitpick) como um campo estruturado, não embutido em prosa, para que ferramentas downstream possam filtrar ou controlar com base nele.
Defina um orçamento de comentários por pull request. Limite o número de comentários que o bot publica por PR (por exemplo, 15) para evitar fadiga de revisão por uma passagem excessivamente falante em um diff grande.
Exija que o bot explique seu raciocínio, não apenas afirme. Um comentário como "isso pode causar uma condição de corrida porque X lê a variável antes que a escrita de Y seja concluída" é revisável; "isso parece errado" não é.
Controle comentários de bloqueio atrás de um limite de confiança. Apenas comentários marcados como blocking devem ser capazes de falhar em uma verificação de CI; a saída de menor confiança permanece consultiva.
Registre cada execução de revisão com o par diff e saída. Armazene o diff que o bot viu ao lado dos comentários que ele produziu, para que uma revisão incorreta ou inútil possa ser depurada posteriormente.

Pipeline de Processamento de Documentos: Etapas da Arquitetura (9-16)

Classifique antes de extrair. Direcione cada documento recebido através de uma etapa de classificação leve (fatura, contrato, currículo, outro) antes de aplicar um prompt de extração específico do tipo de documento.
Use um modelo mais barato e rápido para classificação. Claude Haiku 4.5 é adequado para a etapa de classificação, pois é uma tarefa limitada e de baixa ambiguidade, reservando um modelo mais forte para extração onde a nuance é mais importante.
Defina um esquema de saída rigoroso por tipo de documento. A extração deve ter como alvo um esquema JSON fixo por tipo de documento (por exemplo, fatura: fornecedor, valor, data de vencimento), não um resumo em texto livre, para que sistemas downstream possam consumi-lo de forma confiável.
Valide os campos extraídos contra tipos e intervalos esperados. Uma data de vencimento que é analisada para um ano 300 anos no futuro, ou um valor de zero em uma fatura, deve ser sinalizada para revisão, não aceita silenciosamente.
Direcione extrações de baixa confiança para uma fila de revisão humana. Em vez de forçar todos os documentos à automação completa, defina um limite de confiança ou falha de validação abaixo do qual um humano confirma a extração.
Mantenha o documento original vinculado à sua extração. Cada registro estruturado deve referenciar o arquivo de origem do qual foi extraído, para que um erro downstream seja rastreável de volta ao documento original.
Processe documentos de forma assíncrona, não inline com o upload. Desacople a ingestão de documentos (upload) do processamento (classificar, extrair, validar) com uma fila, para que uma etapa de processamento lenta ou com falha não bloqueie o caminho de upload.
Acompanhe a precisão da extração por tipo de documento ao longo do tempo. Diferentes tipos de documentos terão diferentes perfis de precisão; métricas agregadas sozinhas podem ocultar um tipo de documento com desempenho ruim por trás de números gerais fortes.

Aplicando o Checklist em Ordem

Bot de revisão de código, etapas 1-4: acerte o escopo e o design da ferramenta primeiro; um bot com uma ferramenta de comentário ilimitada é difícil de confiar, independentemente da qualidade do prompt.
Bot de revisão de código, etapas 5-8: adicione orçamento, controle de confiança e registro quando o loop principal funcionar, pois esses são os controles que tornam o bot seguro para ser executado sem supervisão.
Pipeline de documentos, etapas 9-12: classificação, seleção de modelo e rigor do esquema formam a espinha dorsal do pipeline; acerte esses pontos antes de adicionar automação em torno deles.
Pipeline de documentos, etapas 13-16: roteamento de revisão humana, rastreabilidade e processamento assíncrono são os controles operacionais que tornam o pipeline confiável em escala.