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:

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:

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.

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, 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:

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:

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:

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.