# Do monólito de contexto às Context Skills Este é o sexto artigo da série sobre arquitetura AI friendly. Já falamos sobre como código, documentação e observabilidade ajudam agentes a entender sistemas. Também vimos como skills podem oferecer conhecimento especializado para problemas específicos. Agora quero dar um passo atrás e olhar para a arquitetura por trás dessas skills. Assim como aprendemos a separar sistemas grandes em contextos menores, talvez também precisemos aprender a separar o contexto que entregamos aos agentes. ## O monólito de contexto Uma das primeiras tentativas de preparar um repositório para agentes costuma ser criar um arquivo central com todas as instruções. Algo parecido com isto: ```text AGENTS.md # Como nossa empresa funciona Arquitetura Domínios Padrões de código Processos de deploy Observabilidade Regras de negócio Runbooks Convenções de testes Informações de todos os times ``` No começo, esse arquivo ajuda. Ele cria um lugar para registrar decisões e orientações que antes estavam apenas na cabeça das pessoas. Mas ele 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. Esse é um monólito de contexto. O problema não é ter um arquivo central. O problema é colocar conhecimento de todos os domínios e todas as ferramentas no mesmo lugar, sem fronteiras claras. ## O que aprendemos com os microserviços A evolução dos microserviços trouxe uma lição importante: sistemas grandes ficam mais fáceis de entender quando são divididos por responsabilidades e contextos de negócio. Um bounded context não é apenas uma pasta ou um serviço separado. Ele define uma fronteira dentro da qual existem: * um vocabulário próprio; * regras específicas; * responsabilidades claras; * contratos com outros contextos; * dados e comportamentos relacionados; * ownership definido. Dentro do contexto de pagamentos, por exemplo, o conceito de transação pode ter um significado específico. Dentro do contexto de pedidos, a mesma palavra pode aparecer, mas representar outra parte do negócio. As fronteiras ajudam a evitar que todos os componentes precisem conhecer tudo. Podemos aplicar uma ideia semelhante ao contexto dos agentes. ## Contexto também pode ser decomposto Em vez de entregar todas as instruções para todos os problemas, podemos criar especializações: ![](https://cdn.hashnode.com/uploads/covers/67081fa628a6c4cdb75a7fc9/aaa2f346-d5af-474b-aa16-e5914e672179.png align="center") Cada skill conhece profundamente um contexto. Ela pode ter seu próprio vocabulário, suas regras, suas ferramentas e seus limites. Uma skill de pagamentos pode explicar estados de uma transação, políticas de reembolso e integração com o provedor. Uma skill de delivery pode explicar o fluxo de deploy, ambientes e aprovações. Uma skill de observabilidade pode orientar a investigação de logs, métricas e traces. O agente continua tendo uma visão geral, mas não precisa carregar todos os detalhes ao mesmo tempo. ## Context Skills não são microserviços É importante fazer uma distinção. Context Skills não são os novos microserviços. Uma skill não é um serviço de produção, não possui uma API de negócio por definição e não substitui uma fronteira de runtime. A relação entre os conceitos é uma analogia de decomposição. Os microserviços ajudam a separar capacidades de software. As Context Skills ajudam a separar conhecimento e formas de trabalho para agentes. Um mesmo domínio pode ter um serviço, uma documentação, um conjunto de dashboards e uma ou mais skills relacionadas. A skill conhece o contexto e sabe consultar as fontes corretas, mas os dados continuam nos sistemas que são responsáveis por eles. ![](https://cdn.hashnode.com/uploads/covers/67081fa628a6c4cdb75a7fc9/726772d5-53e1-4827-b09e-30843351c986.png align="center") O valor está na conexão entre essas partes. ## Uma skill não é apenas documentação Uma página de documentação explica um assunto. Uma Context Skill também precisa explicar como trabalhar com aquele assunto. Ela pode orientar o agente sobre: * quando aquele contexto é relevante; * quais fontes devem ser consultadas primeiro; * quais perguntas precisam ser respondidas; * quais evidências devem aparecer no resultado; * quais ações são permitidas; * quais ações exigem aprovação; * quando a investigação deve ser interrompida. 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 a informação correta e a respeitar os limites da equipe. Uma skill de pagamentos, por exemplo, pode indicar que uma investigação de estorno deve consultar 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 conhecer? Uma skill baseada em contexto não precisa copiar todas as informações do domínio. Ela precisa saber como navegar por ele. Alguns elementos importantes são: ### Vocabulário Quais termos têm significado especial naquele domínio? O que é uma transação, uma autorização, uma captura ou um estorno? ### Responsabilidades Qual serviço é responsável por cada ação? Quem é o owner do contexto? Quais decisões podem ser tomadas pela equipe? ### Contratos Quais APIs, eventos e schemas conectam esse contexto a outros? Quais mudanças exigem 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 de leitura? O que precisa de aprovação? Quando o agente deve parar e pedir ajuda? Esse conjunto dá ao agente profundidade sem exigir que ele carregue o conhecimento de toda a empresa. Esses limites devem ser definidos junto com as políticas de segurança da arquitetura. Como vimos no artigo [Segurança, guardrails e fitness functions para agentes](https://luizschons.com/seguran-a-guardrails-e-fitness-functions-para-agentes), uma skill pode orientar o agente, mas não deve ser a única responsável por impedir uma ação indevida. Permissões, escopos e aprovações precisam ser aplicados também pelas ferramentas e pelos recursos protegidos. ## Um agente conecta as skills Decompor o contexto não significa criar agentes isolados que não conversam entre si. O papel do agente principal é coordenar as especializações. Imagine uma investigação em que a taxa de falha de pagamentos aumentou. O agente pode fazer o seguinte: ```text 1. Ativa a Payments Context Skill. 2. Consulta a Observability Skill para investigar os sinais. 3. Consulta a Delivery Skill para verificar deploys recentes. 4. Consulta a Data Platform Skill se o fluxo depender de dados processados. 5. Combina as evidências em uma hipótese. 6. Apresenta o que foi confirmado e o que ainda é incerto. ``` Cada skill contribui com uma visão específica. O agente faz a correlação entre elas. Essa separação permite que uma skill seja mantida por quem realmente conhece aquele contexto, sem exigir que a mesma pessoa mantenha 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 limite a partir do qual a fragmentação começa a atrapalhar. Se o agente precisa ativar dez skills para responder uma pergunta simples, talvez as fronteiras estejam erradas ou a tarefa esteja sendo dividida em unidades pequenas demais. Uma boa fronteira costuma agrupar conhecimento que muda junto, é usado junto e possui ownership relacionado. Outra pergunta útil é: se esse contexto mudar, quem precisa revisar o conhecimento? Se a resposta envolver equipes muito diferentes, responsabilidades conflitantes ou fontes sem relação, talvez a fronteira esteja grande demais. As fronteiras também devem ser observáveis. Precisamos conseguir identificar qual contexto foi consultado, quais fontes foram usadas e quais regras orientaram a resposta. Sem essa visibilidade, fica difícil entender se um problema veio da falta de informação, 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 uso, cada contexto pode evoluir. Uma skill de observabilidade pode depois ganhar especializações para incidentes, performance e capacidade. Essa divisão deve acontecer quando existir uma necessidade real, não apenas porque é possível criar mais arquivos. ## Onde as Context Skills vivem? 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. O mais importante é deixar claro: * quem é o owner da skill; * quais agentes podem usá-la; * quais fontes externas ela consulta; * como suas instruções são versionadas; * como mudanças são revisadas; * quais permissões ela exige. Uma skill para observabilidade, por exemplo, pode ser mantida pelo time de plataforma. Ela pode explicar como consultar dashboards e métricas padronizadas, mas não deve armazenar cópias dos dados de produção. Uma skill de pagamentos pode ser mantida pelo time responsável pelo domínio. Ela pode apontar para ADRs, contratos e runbooks, mas deve continuar respeitando as fontes originais. ## Context Skills e ownership O ownership é uma parte essencial dessa arquitetura. Se todos são responsáveis por uma skill, provavelmente ninguém é responsável de fato. Se ninguém revisa as instruções quando uma API muda, o agente passa 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 eles pudessem ser desenvolvidos e operados por equipes diferentes. Agora também precisamos decompor o conhecimento que entregamos aos agentes. Context Skills são uma forma de criar fronteiras para esse conhecimento. Elas permitem que cada contexto tenha vocabulário, regras, ferramentas, ownership e limites claros. O agente não precisa conhecer tudo profundamente. Ele precisa saber quais contextos existem, quando acioná-los e como conectar as evidências encontradas. No próximo artigo, vamos separar as peças que fazem essa arquitetura funcionar: agentes, skills, tools e MCP. A ideia é entender o papel de cada camada antes de usá-las em um caso real.