Engenharia de contexto: skills de agente, MCP e contexto governado

Engenharia de prompt nunca bastou para times que entregam software com modelos. Engenharia de contexto é montar o que o modelo vê — instruções, tools, docs recuperados, layout do repo, políticas — sob orçamento fixo de tokens, com versionamento e review como qualquer outra interface.

Skills de agente (instruções empacotadas + scripts opcionais) e MCP (servidores Model Context Protocol que expõem tools e recursos aos clientes) são duas implementações concretas dessa ideia. Não são magia; são como você para de colar os mesmos dez parágrafos em toda sessão.

Contexto é a superfície real da API

Toda completion é f(contexto) → texto | tool_calls. O que entra em contexto é decisão de design:

• Mensagens de sistema e desenvolvedor (comportamento, segurança, forma de saída)
• Definições de tools e schemas JSON
• Passagens recuperadas (RAG) — dados não confiáveis
• Arquivos, diffs, logs selecionados — muitas vezes confiáveis, ainda assim limitados
• Histórico de conversa — resumido ou em janela

Times sênior tratam montagem de contexto como código: ordem determinística, política explícita de truncamento, redação de segredos, métricas de tokens por feature flag.

Skills: runbooks operacionais, não “prompt melhor”

Uma skill em ferramentas como Cursor é, grosso modo: pacote nomeado de quando usar, procedimento passo a passo, restrições e às vezes comandos ou padrões de arquivo permitidos. Comparado a prompt avulso:

| Prompt ad hoc | Skill | |---------------|--------| | Vive no histórico do chat | Vive no repo ou biblioteca da org, diffável | | Deriva por engenheiro | Revisada em PR como runbooks | | Difícil de descobrir | Invocada por nome ou roteada quando relevante |

Skills brilham em fluxos repetíveis: checklists de deploy, rubricas de security review, passos de migração de um framework, “como escrevemos ADR neste repo”. Falham quando substituem requisito de produto ou teste automatizado — o modelo alucina se a skill descreve arquitetura fantasia.

Como escrever skills que aguentam:

1. Escopo estreito — uma skill por fluxo, não “tudo de backend”. 2. Pré-requisitos explícitos — arquivos, env, comandos que devem existir; o que fazer quando faltar. 3. Passos de verificação — “rode npm test path”, “grep por X”, não “garanta qualidade”. 4. Versionar com o codebase — skill que cita script removido é pior que nenhuma skill.

Skills são documentação que o agente executa; mantenha honestidade sobre o que o repo de fato contém.

MCP: tools e recursos sem integração bespoke

O MCP padroniza como o cliente descobre e chama tools e lê resources de um servidor (local ou remoto). Em vez de N plugins custom por IDE, você implementa um servidor por fronteira: issue tracker, observabilidade, docs internos, réplica read-only de staging (read-only!), API de deploy.

Escolhas que importam em servidores MCP de produção:

• Menor privilégio — servidores separados por sensibilidade; não monte tools de write em prod ao lado de busca de docs.
• Nomes e schemas estáveis — clientes e skills dependem; breaking change é API v2.
• Timeouts e paginação — list_issues sem limite estoura a janela de contexto.
• Auth — OAuth ou tokens de vida curta; nunca segredo long-lived no config do client commitado no git.

MCP não substitui seu backend. É cola adaptadora entre o runtime do agente e sistemas que engenharia já opera.

Skills + MCP juntos

Divisão típica:

• Skill responde como trabalhamos aqui (nome de branch, comandos de teste, checklist de review).
• MCP responde como está o mundo agora (PR aberto, trace id, status do ticket).

Loop do agente: skill escolhe procedimento → MCP busca dado vivo → skill diz como interpretar → modelo propõe patch → humano ou CI verifica.

Sem skills, MCP despeja JSON cru no contexto e o modelo improvisa processo. Sem MCP, skills envelhecem no momento em que campos do Jira mudam, salvo alguém atualizar o markdown.

Orçamento de contexto e compressão

Modelos têm janelas grandes; latência, custo e distração ainda punem encher tudo. Padrões:

• Divulgação progressiva — resumo da skill primeiro; skill completa ou chunks de arquivo sob demanda.
• Resumos estruturados — tabela de erros de API, não cauda inteira de log, salvo debug daquele incidente.
• Referência por ponteiro — “ver lib/retrieval.ts” com leitura seletiva, não @-mention do repo inteiro por padrão.
• Separar retrieval de raciocínio — RAG ou MCP de busca para fatos; instruções de sistema curtas e estáveis.

Meça tokens in / tokens out / round-trips de tool por tipo de tarefa quando discutir qual skill aparar.

Governança em orgs reais

O que distingue adoção madura:

• Donos por skill e servidor MCP (on-call quando o agente erra naquele domínio).
• Review em PR para mudanças de skill que tocam segurança, infra ou dado de cliente.
• Allowlist de quais servidores MCP roles júnior podem habilitar em laptop com VPN de prod.
• Auditoria de chamadas de tool de agentes automatizados (bots de CI, cloud agents), não só sessão humana no IDE.

“Todo mundo cola a política da empresa no ChatGPT” é o shadow IT que você substitui — skills e MCP são o caminho oficial se a governança acompanha.

O que isto não é

• Não substitui tipos, testes e code review.
• Não prova que o modelo entende seu domínio — segue instrução e estatística.
• Não é exclusivo de um vendor — as ideias portam; MCP é protocolo aberto, skills são padrão de empacotamento.

Encerramento

Engenharia de contexto é como times sênior tornam trabalho assistido por LLM repetível e revisável. Skills codificam procedimento; MCP codifica integração ao vivo; codebase e CI ainda codificam verdade.

Comece por um fluxo de alta fricção que você já documenta mal (release, incidente, migração). Vire skill, conecte uma fonte MCP read-only para fatos e meça se a próxima execução precisou de menos retrabalho — essa é a métrica que importa.