# Context Skills: Dividindo o Contexto para Agentes de IA - Author: Luiz Schons - Published: 2026-09-05 - URL: https://luizschons.com/pt-br/posts/context-skills-breaking-down-the-context-for-ai-agents/ - English: https://luizschons.com/posts/context-skills-breaking-down-the-context-for-ai-agents.md - Temas: IA, Arquitetura Este é o sexto artigo da série sobre arquitetura amigável à IA. Já discutimos como o código, a documentação e a observabilidade ajudam os agentes a entender os sistemas. Também vimos como as habilidades podem fornecer conhecimento especializado para problemas específicos. Agora quero dar um passo para trás e olhar para a arquitetura por trás dessas habilidades. Assim como aprendemos a dividir grandes sistemas em contextos menores, também podemos precisar aprender a dividir o contexto que damos aos agentes. ## O monólito de contexto Uma das primeiras tentativas de preparar um repositório para agentes é muitas vezes criar um arquivo central com todas as instruções. Algo assim ```text AGENTS.md # Como nossa empresa funciona Architecture Domains Coding standards Deployment processes Observability Business rules Runbooks Testing conventions Information about all teams ``` No começo, esse arquivo ajuda. Ele cria um lugar para registrar decisões e orientações que costumavam existir apenas na cabeça das pessoas. Mas pode crescer rapidamente. Depois de algum tempo, fica difícil saber quais partes se aplicam a cada tarefa, quem é responsável por atualizá-las e quais instruções têm prioridade. Este é um monólito de contexto. O problema não é ter um arquivo central. O problema é colocar o conhecimento de todos os domínios e todas as ferramentas no mesmo lugar, sem limites claros. ## O que aprendemos com microsserviços A evolução dos microsserviços nos ensinou uma lição importante: grandes sistemas são mais fáceis de entender quando são divididos por responsabilidade e contexto de negócios. Um contexto limitado não é apenas uma pasta ou um serviço separado. Ele define um limite que contém: - seu próprio vocabulário; - Regras Específicas - responsabilidades claras; - contratos com outros contextos; - dados e comportamentos relacionados; - propriedade definida. Por exemplo, dentro do contexto de pagamentos, a palavra transação pode ter um significado específico. Dentro do contexto de pedidos, a mesma palavra pode aparecer, mas representa outra parte do negócio. Os limites ajudam a evitar que todos os componentes precisem saber tudo. Podemos aplicar uma ideia semelhante ao contexto dado aos agentes. ## O contexto também pode ser decomposto Em vez de dar todas as instruções para cada problema, podemos criar especializações: Um agente, vários contextos Cada habilidade conhece profundamente um contexto. Pode ter seu próprio vocabulário, regras, ferramentas e limites. Uma habilidade de pagamentos pode explicar os estados das transações, as políticas de reembolso e a integração do provedor. Uma habilidade de entrega pode explicar o fluxo de implantação, ambientes e aprovações. Uma habilidade de observabilidade pode orientar investigações usando logs, métricas e traços. O agente ainda mantém uma visão geral, mas não precisa carregar todos os detalhes ao mesmo tempo. ## Context Skills não são microsserviços É importante fazer uma distinção. Context Skills não são os novos microsserviços. Uma skill não é um serviço de produção, não possui necessariamente uma API de negócio e não substitui um limite de runtime. A conexão entre os conceitos está na ideia de decomposição. Microsserviços ajudam a separar capacidades de software. Context Skills ajudam a separar conhecimento e fluxos de trabalho para agentes. O mesmo domínio pode ter um serviço, documentação, painéis e uma ou mais skills relacionadas. A skill conhece o contexto e sabe consultar as fontes corretas, mas os dados continuam nos sistemas responsáveis por eles. Contexto distribuído: pagamentos O valor vem da conexão entre essas partes. ## Uma skill é mais do que documentação Uma página de documentação explica um assunto. Uma Context Skill também precisa explicar como trabalhar com esse assunto. Ela pode orientar o agente sobre: - quando aquele contexto é relevante; - quais fontes devem ser verificadas primeiro; - quais perguntas precisam ser respondidas; - quais evidências devem aparecer no resultado; - quais ações são permitidas; - quais ações precisam de aprovação; - quando a investigação deve parar. Isso cria um contrato de trabalho para o contexto. A skill não precisa conter todos os detalhes, mas deve ajudar o agente a encontrar as informações corretas e respeitar os limites da equipe. Por exemplo, a skill de pagamentos pode dizer que uma investigação de reembolso deve verificar o contrato da operação, os eventos emitidos e o runbook de falhas. Ela também pode exigir que o agente diferencie uma transação autorizada de uma transação capturada antes de formular uma hipótese. ## O que uma Context Skill precisa saber? Uma skill baseada em contexto não precisa copiar todas as informações do domínio. Ela precisa saber como navegá-las. Alguns elementos importantes são: ### Vocabulário Quais termos têm um significado especial nesse domínio? O que é uma transação, uma autorização, uma captura ou um reembolso? ### Responsabilidades Qual serviço é responsável por cada ação? Quem é o responsável pelo contexto? Quais decisões a equipe pode tomar? ### Contratos Quais APIs, eventos e esquemas conectam esse contexto aos demais? Quais mudanças precisam de versionamento? ### Fontes de verdade Onde estão os dados atuais? Qual documentação deve ser consultada? Qual plataforma contém os sinais de produção? ### Limites Quais ações são somente leitura? O que precisa de aprovação? Quando o agente deve parar e pedir ajuda? Esse conjunto de informações dá profundidade ao agente sem exigir que ele carregue o conhecimento da empresa inteira. Esses limites devem ser definidos junto com as políticas de segurança da arquitetura. Como vimos no artigo [Funções de segurança, guarda-corpos e condicionamento físico para agentes](https://luizschons.com/pt-br/posts/guardrails-and-fitness-functions-for-ai-friendly-architecture/), uma skill pode orientar o agente, mas não deve ser a única proteção contra uma ação insegura. Permissões, escopos e aprovações também precisam ser aplicados pelas ferramentas e pelos recursos protegidos. ## Um agente conecta as skills Dividir o contexto não significa criar agentes isolados que não conseguem se comunicar. O agente principal coordena as especializações. Imagine uma investigação em que a taxa de falhas de pagamento aumentou. O agente pode fazer o seguinte: ```text 1. Activate the Payments Context Skill. 2. Use the Observability Skill to investigate the signals. 3. Use the Delivery Skill to check recent deployments. 4. Use the Data Platform Skill if the flow depends on processed data. 5. Combine the evidence into a hypothesis. 6. Show what was confirmed and what is still uncertain. ``` Cada skill acrescenta uma visão específica. O agente conecta as informações entre elas. Essa separação permite que uma skill seja mantida pelas pessoas que realmente conhecem aquele contexto. Elas não precisam manter todas as instruções do agente de engenharia. ## Contexto demais também pode ser um problema Decompor não significa criar centenas de skills pequenas. Existe um ponto em que a fragmentação excessiva começa a causar problemas. Se o agente precisa ativar dez skills para responder a uma pergunta simples, os limites podem estar errados ou a tarefa pode ter sido dividida em unidades pequenas demais. Um bom limite geralmente agrupa conhecimentos que mudam juntos, são usados juntos e têm responsabilidades relacionadas. Outra pergunta útil é: se esse contexto mudar, quem precisa revisar o conhecimento? Se a resposta incluir equipes muito diferentes, responsabilidades conflitantes ou fontes não relacionadas, o limite pode ser grande demais. Os limites também devem ser observáveis. Precisamos saber qual contexto foi consultado, quais fontes foram usadas e quais regras orientaram a resposta. Sem essa visibilidade, é difícil entender se um problema veio de informação ausente, da escolha da skill ou da interpretação do agente. Podemos começar com alguns contextos maiores: ```text Observability Delivery Data Payments Orders Security ``` Com o tempo, cada contexto pode evoluir. Uma skill de observabilidade pode ganhar especializações para incidentes, desempenho e capacidade. Essa divisão deve acontecer quando houver uma necessidade real, não apenas porque é possível criar mais arquivos. ## Onde vivem as Context Skills? Uma Context Skill pode viver junto do código da equipe, em um repositório de plataforma ou em um catálogo compartilhado. A escolha depende de quem mantém o contexto e de como os agentes serão usados. Os pontos mais importantes são deixar claro: - quem é responsável pela skill; - quais agentes podem usá-la; - quais fontes externas ela consulta; - como suas instruções são versionadas; - como as mudanças são revisadas; - quais permissões ela precisa. Por exemplo, a skill de observabilidade pode ser mantida pela equipe de plataforma. Ela pode explicar como consultar painéis e métricas padrão, mas não deve armazenar cópias dos dados de produção. Uma skill de pagamentos pode ser mantida pela equipe responsável pelo domínio. Ela pode apontar para ADRs, contratos e runbooks, mas deve continuar respeitando as fontes originais. ## Context Skills e responsabilidade A responsabilidade é uma parte essencial dessa arquitetura. Se todos são responsáveis por uma skill, provavelmente ninguém é realmente responsável. Se ninguém revisa as instruções quando uma API muda, o agente começa a trabalhar com conhecimento desatualizado. Uma skill pode ter um arquivo simples de metadados: ```yaml name: payments-context owner: payments-team review_frequency: quarterly sources: - payment-service - payment-documentation - payment-dashboards ``` Esse arquivo não resolve sozinho o problema de manutenção, mas torna a responsabilidade mais visível e pode ajudar a criar um processo de revisão. ## Conclusão Durante muito tempo, nossa preocupação foi decompor sistemas para que pudessem ser desenvolvidos e operados por equipes diferentes. Agora também precisamos decompor o conhecimento que fornecemos aos agentes. Context Skills são uma forma de criar limites para esse conhecimento. Elas permitem que cada contexto tenha vocabulário, regras, ferramentas, responsabilidade e limites claros. O agente não precisa conhecer tudo profundamente. Ele precisa saber quais contextos existem, quando usá-los e como conectar as evidências que encontra. No próximo artigo, vamos separar as partes que fazem essa arquitetura funcionar: agentes, skills, ferramentas e MCP. O objetivo é entender o papel de cada camada antes de usá-las em um caso real.