O cenário
Uma empresa de logística pede: "queremos que o Claude ajude nosso time de suporte a responder tickets mais rápido, usando nossa base de conhecimento interna, e também queremos que os desenvolvedores usem Claude Code no dia a dia — dá pra fazer os dois com a mesma arquitetura?"
Esse pedido, do jeito que chegou, não é uma especificação — é uma direção com pelo menos seis decisões escondidas dentro dele: que superfície usar para cada parte, como a base de conhecimento é exposta, quem revisa o que antes de ir para o cliente, como uma sessão de suporte lida com um histórico de conversa que cresce, o que fica registrado quando algo dá errado, e onde a fronteira de segurança fica entre "ferramenta interna de dev" e "sistema voltado ao cliente". Ambiguidade nesse nível é exatamente o que um cenário de capstone testa: não se você conhece cada mecanismo isoladamente, mas se você consegue montar um argumento de arquitetura coerente que resolve as seis decisões de forma consistente entre si.
Esta lição não introduz conceito novo. Ela pede que você aplique, num único artefato, os frameworks de decisão das 21 lições anteriores — e o formato desse artefato é um ADR (Architecture Decision Record).
O que um ADR precisa ter
Um ADR não é um relatório de tudo que você considerou. É um registro enxuto de uma decisão, com estrutura fixa:
- Contexto — qual é a restrição real por trás do pedido (não o pedido literal, a restrição).
- Decisão — o que foi escolhido, em uma frase que alguém consegue repetir de memória.
- Alternativas descartadas — o que mais foi considerado e por que perdeu, especificamente qual restrição a alternativa violava.
- Consequências — o que essa decisão custa (manutenção, latência, superfície de risco) em troca do que ela resolve.
O erro mais comum em um ADR de candidato é pular direto para "Decisão" sem nomear a restrição em "Contexto" — o que produz uma escolha que parece certa, mas que ninguém consegue avaliar sem adivinhar qual problema ela estava resolvendo.
Percorrendo os cinco domínios no mesmo cenário
Arquitetura agêntica e orquestração. O fluxo de suporte precisa de um loop de ferramentas controlado (buscar na base de conhecimento, verificar status de pedido, rascunhar resposta) — não um chat solto nem múltiplos agentes especializados para uma tarefa que uma sessão única resolve bem. A tentação de "multiagente parece mais robusto" é o distrator clássico: um pipeline curto com poucas ferramentas não ganha nada com coordenação entre agentes, só ganha latência e superfície de erro.
Design de ferramentas e integração MCP. A base de conhecimento interna deveria ser exposta como um servidor MCP com escopo de projeto, com descrições de ferramenta precisas o suficiente para reduzir chamadas erradas — e as respostas dessa ferramenta, vindas de conteúdo escrito por humanos, tratadas como superfície de risco (nunca instrução implícita a ser obedecida).
Configuração e fluxos do Claude Code. A parte de "desenvolvedores usando Claude Code no dia a dia" é uma superfície completamente separada da de suporte ao cliente — resolvida com convenções de equipe em CLAUDE.md, comandos e Skills do projeto. Tentar unificar as duas superfícies numa arquitetura só porque "é a mesma empresa" ignora que os requisitos de segurança, revisão e público são incompatíveis entre elas.
Engenharia de prompt e saída estruturada. O rascunho de resposta ao cliente é saída estruturada com um contrato explícito (tom, campos obrigatórios, o que nunca pode ser afirmado sem confirmação na base de conhecimento) — validado antes de chegar a um humano, não confiado por padrão.
Gestão de contexto e confiabilidade. Um histórico de conversa de suporte que cresce ao longo de dias não deveria virar uma janela de contexto cada vez maior — pede um resumo estruturado periódico (o mesmo raciocínio de scratchpads e compactação) e uma política clara de quando um ticket precisa escalar para um humano em vez de o agente seguir tentando sozinho.
O ponto de um capstone não é resolver cada domínio isoladamente — é notar onde as decisões de domínios diferentes restringem umas às outras. A escolha de manter suporte e Claude Code como superfícies separadas (decisão de arquitetura agêntica) é o que torna possível ter políticas de segurança diferentes para cada uma (decisão de segurança que, embora não seja um domínio isolado do CCAR-F, atravessa MCP e contexto). Uma arquitetura correta em cada domínio isoladamente ainda pode ser inconsistente no conjunto.
O failure mode mais caro
Em um cenário como esse, o failure mode mais caro raramente é o mais óbvio (o agente responder algo tecnicamente errado). É mais sutil: o agente responder algo plausível e bem formatado, mas não sustentado pela base de conhecimento, e essa resposta ser enviada ao cliente sem revisão porque o formato impecável passou a impressão de confiabilidade que o conteúdo não tinha.
A mitigação não é "adicionar mais validação de formato" — formato já estava correto. É garantir que toda afirmação factual no rascunho carregue uma referência rastreável de qual documento da base de conhecimento a sustenta, e que a ausência dessa referência seja, por si só, motivo de bloqueio antes de qualquer resposta sair para o cliente. Essa é a mesma lógica de proveniência e validação de saída estruturada das lições anteriores, aplicada ao ponto onde o custo do erro é mais alto: o momento em que a resposta sai do sistema e chega a uma pessoa real.
Coloque em prática
O laboratório desta lição pede que você monte e valide a estrutura de um ADR — contexto, decisão, alternativas descartadas e consequências — a partir de um conjunto de decisões de arquitetura para este mesmo cenário de suporte, verificando que nenhuma seção está vazia e que toda decisão referencia pelo menos uma restrição concreta do contexto.