Context Engineering na prática: o guia baseado no framework de Muratcan Koylan¶
🟡 Intermediário • ⏱️ 10 min de leitura
Tecnologias: Claude Code • Cursor • Codex • LLMs • Agentes de IA
Imagine sua mesa de trabalho. Se ela está cheia de papéis, cadernos antigos, post-its de tarefas já concluídas e três xícaras de café vazias, fica difícil encontrar o documento de que você realmente precisa — mesmo que ele esteja em algum lugar debaixo da pilha. Um modelo de IA funciona de modo parecido: quanto mais informação desorganizada você empilha no contexto, mais difícil pode ser para o modelo identificar o que é relevante para responder bem.
Context engineering é, essencialmente, a prática de arrumar essa mesa antes de pedir que alguém trabalhe nela.
Este artigo explica o que é context engineering, por que a disciplina vai além de escrever o “prompt perfeito” e como aplicar seus princípios na prática. Como referência, usaremos o projeto open-source Agent Skills for Context Engineering, criado por Muratcan Koylan, membro da equipe técnica da Sully.ai que trabalha com IA clínica. O projeto reúne milhares de estrelas no GitHub e aparece nas referências de pesquisas da Peking University e de um estudo sobre agent harness engineering com autores de instituições como CMU, Yale, Johns Hopkins e Amazon.
Não é preciso ser programador para entender os conceitos. As instruções de instalação são voltadas a quem já usa ferramentas como Claude Code, Cursor ou Codex, mas os princípios valem para qualquer pessoa que trabalhe com LLMs.
1. O que é context engineering, sem jargão¶
Quando gera uma resposta, um modelo de linguagem considera uma janela limitada de informação. Ela pode incluir:
- as instruções do sistema;
- o histórico da conversa;
- os documentos recuperados ou anexados;
- as ferramentas disponíveis;
- os resultados retornados por essas ferramentas.
Essa janela tem um limite não apenas de tamanho, mas também de atenção útil. Estudos sobre contextos longos observaram que a posição da informação pode afetar o desempenho: em determinadas tarefas e modelos, conteúdos no início ou no fim são recuperados melhor do que aqueles no meio. Esse padrão ficou conhecido como lost in the middle.
Isso não significa que todo modelo sempre ignorará o meio do contexto. Significa que aumentar o volume de informação, por si só, não garante uma resposta melhor. O objetivo do context engineering é selecionar, organizar e disponibilizar as informações com melhor relação entre sinal e ruído para a tarefa atual.
Prompt engineering vs. context engineering, em uma frase: prompt engineering melhora a instrução; context engineering cuida de todo o estado informacional que acompanha essa instrução.
2. Por que isso importa agora¶
Em tarefas curtas — como resumir um texto ou escrever um e-mail — um bom prompt costuma resolver grande parte do problema. A complexidade aumenta quando a IA executa tarefas longas, usa várias ferramentas, recupera memórias de sessões anteriores ou coordena outros agentes.
Nesses casos, o gargalo deixa de ser apenas “o que foi pedido” e passa a incluir “o que o agente está carregando, recuperando e produzindo a cada etapa”. É esse território que o projeto de Koylan mapeia.
3. O framework de Koylan: 17 skills em 5 blocos¶
O Agent Skills for Context Engineering é uma coleção de módulos reutilizáveis de instruções, scripts e referências, chamados de Agent Skills. O projeto pode ser instalado como plugin e também adaptado a plataformas que aceitam skills ou instruções customizadas.
| Bloco | O que ensina | Skills incluídas |
|---|---|---|
| Fundamentos | Entender o contexto, reconhecer sua degradação e comprimir sessões longas | context-fundamentals, context-degradation, context-compression |
| Arquitetura | Estruturar agentes, memória, ferramentas e contexto persistido em arquivos | multi-agent-patterns, long-horizon-prompting, memory-systems, tool-design, filesystem-context, hosted-agents |
| Operação | Otimizar, avaliar e controlar agentes em produção | context-optimization, latent-briefing, evaluation, advanced-evaluation, harness-engineering, self-improvement-loops |
| Metodologia | Avaliar e desenvolver projetos baseados em LLMs | project-development |
| Cognição avançada | Modelar estados mentais formais de um agente | bdi-mental-states |
Uma ideia que atravessa a coleção é a divulgação progressiva. No início, o agente carrega apenas os nomes e as descrições das skills disponíveis. O conteúdo completo de uma skill só entra no contexto quando ela é relevante para a tarefa. Assim, a própria estrutura do projeto aplica o princípio que ensina.
4. Como instalar¶
O repositório oferece integração direta com o Claude Code e uma estrutura compatível com outras ferramentas. A disponibilidade e os comandos podem mudar; por isso, consulte também o README do projeto antes de instalar.
Opção A — Instalar o pacote completo no Claude Code¶
Passo 1. Dentro do Claude Code, registre o repositório como fonte de plugins:
Passo 2. Instale o plugin com todas as skills publicadas:
Depois da instalação, o Claude Code pode descobrir e ativar a skill adequada conforme o contexto da tarefa. Ao pedir ajuda para desenhar uma arquitetura com vários agentes, por exemplo, a ferramenta pode carregar multi-agent-patterns.
Opção B — Instalar uma skill específica¶
Agent Skills usam uma estrutura de diretórios. Portanto, copie a pasta completa da skill, e não apenas seu arquivo SKILL.md:
git clone --depth 1 \
https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering.git
mkdir -p .claude/skills
cp -R Agent-Skills-for-Context-Engineering/skills/context-fundamentals \
.claude/skills/
Para um projeto no Cursor ou no Codex, use respectivamente .cursor/skills/ ou .codex/skills/ como destino. Copiar somente o SKILL.md para um arquivo isolado pode quebrar links relativos para scripts e referências que fazem parte da skill.
As skills publicadas atualmente são: context-fundamentals, context-degradation, context-compression, context-optimization, latent-briefing, multi-agent-patterns, long-horizon-prompting, memory-systems, tool-design, filesystem-context, hosted-agents, evaluation, advanced-evaluation, harness-engineering, self-improvement-loops, project-development e bdi-mental-states.
Opção C — Aplicar os princípios sem instalar nada¶
Você também pode ler as skills diretamente no repositório do projeto e aplicar suas ideias manualmente em qualquer ferramenta baseada em LLM.
5. Exemplos práticos de uso¶
Exemplo 1 — Diagnosticar um agente que perde instruções em conversas longas¶
Se um agente começa bem uma tarefa, mas deixa de seguir uma regra após muitas interações, a degradação do contexto é uma hipótese a investigar — não o único diagnóstico possível. Com a skill context-degradation, você poderia pedir:
“O agente deixou de seguir uma regra de formatação depois de 20 mensagens. Analise se há degradação, distração ou conflito de contexto e sugira formas de testar e corrigir cada hipótese.”
A análise pode recomendar tornar a regra parte de uma instrução persistente, reduzir conteúdo irrelevante, resolver instruções conflitantes ou substituir o histórico por um resumo estruturado.
Exemplo 2 — Decidir entre um agente único e vários agentes¶
Criar vários agentes nem sempre melhora o sistema. A skill multi-agent-patterns trata subagentes principalmente como uma forma de separar contextos e responsabilidades. Um prompt prático seria:
“Estou construindo um sistema que pesquisa preços, compara concorrentes e gera um relatório. Avalie se um único agente é suficiente ou se a separação de contexto justifica múltiplos agentes.”
Exemplo 3 — Organizar a memória de um agente de atendimento¶
Se um assistente precisa lembrar interações anteriores, a skill memory-systems ajuda a separar o estado da conversa atual, as informações persistentes do cliente e as relações entre entidades. Por exemplo:
“Meu agente de suporte precisa usar o histórico de tickets de cada cliente entre sessões. Proponha uma arquitetura de memória, incluindo critérios de gravação, recuperação, atualização e expiração.”
Exemplo 4 — Reduzir erros no uso de ferramentas¶
A skill tool-design aborda o contrato entre um agente e as ferramentas disponíveis. Descrições vagas, parâmetros ambíguos e mensagens de erro pouco acionáveis aumentam a chance de chamadas incorretas. Um pedido possível:
“Revise os schemas destas ferramentas e proponha descrições, parâmetros e erros que tornem cada chamada menos ambígua para o agente.”
Exemplo 5 — Definir limites para um agente autônomo¶
Antes de executar um agente sem supervisão constante, a skill harness-engineering ajuda a projetar métricas protegidas, logs duráveis, mecanismos de rollback e pontos de aprovação humana. Por exemplo:
“Quero automatizar a triagem de e-mails. Defina o que o agente pode executar sozinho, o que exige confirmação e quais evidências e logs devem existir antes de cada ação.”
6. Princípios que você pode aplicar hoje¶
- Pense em orçamento de atenção, não apenas em limite de tokens. Antes de anexar um documento inteiro, avalie quais trechos são necessários para a decisão atual.
- Mantenha instruções críticas em um local estável. Regras persistentes devem ficar nas instruções apropriadas do sistema ou do projeto; critérios específicos da tarefa devem aparecer no pedido atual.
- Divida agentes por necessidade de contexto, não por cargo. Se dois agentes precisam receber exatamente as mesmas informações e produzir a mesma decisão, a separação talvez não compense o custo de coordenação.
- Comprima o histórico com critérios claros. Um bom resumo preserva decisões, restrições, evidências, pendências e próximos passos — não apenas uma narrativa curta da conversa.
- Avalie resultados com testes repetíveis. Critérios objetivos, exemplos de sucesso e casos de regressão ajudam a detectar degradação antes que ela produza erros em produção.
Conclusão¶
O trabalho de Muratcan Koylan ajuda a estruturar algo que quem constrói com IA já percebe na prática: o desafio não é apenas escrever uma boa instrução, mas gerenciar tudo que o modelo recebe durante uma tarefa complexa.
Context engineering trata de selecionar, organizar, recuperar, comprimir e descartar informações para que o modelo trabalhe com o contexto mais útil possível. Seja para construir agentes ou melhorar conversas cotidianas com uma IA, essa mudança de perspectiva tende a produzir interações mais claras, econômicas e verificáveis.