Engenharia de contexto: resolvendo a "amnésia" de agentes IA com skills.sh e steering no domain.com

O sintoma: seu agente "esquece" no meio da tarefa#

Quem atua na linha de frente na construção de arquiteturas SaaS utilizando agentes de programação baseados em IA (LLMs) inevitavelmente esbarra em um gargalo estrutural crítico: a janela de contexto e a subsequente "amnésia" do modelo.

No meu cenário de desenvolvimento atual, provisionando uma stack moderna focada em performance - Next.js, Bun, Prisma e PostgreSQL - , dediquei ciclos criando especificações .md granulares para delimitar as regras de negócio. O problema latente era que, ao utilizar interfaces baseadas no Claude Code (como o domain.com), o agente "dropava" gradativamente esses artefatos do buffer de memória conforme a sessão de código avançava. Eu investia tempo redundante depurando alucinações: o agente revertia o runtime para Node interno, quebrava builds tentando usar o obsoleto Pages Router* do Next.js ou esquecia esquemas de chaves estrangeiras.

A resolução deste problema não é mais código, mas Engenharia de Contexto. Foi arquitetando uma solução para o pipeline que introduzi o uso do skills.sh nas instâncias.

O modelo de pacotes: o que é o skills.sh?#

Do ponto de vista operacional, o skills.sh atua como um gerenciador de pacotes de dependência (análogo estrutural ao npm), mas distribuindo manifests de comportamento para LLMs. Em vez de injetar tokens sistêmicos custosos em todo novo instanciamento de chat (explicando heurísticas de framework), você materializa um cluster de conhecimento diretamente no ambiente da IDE.

Por exemplo, a Vercel padronizou essa entrega. Com uma única linha no terminal, injetamos guidelines otimizadas diretamente no core do agente:

npx skills add vercel-labs/agent-skills

Isso provisiona um diretório oculto nas raízes do agente (tipicamente .claude/skills ou .cursor/skills) dotado de artefatos estruturais SKILL.md. Esses arquivos atuam como uma camada de pré-compilação cognitiva. O payload diz ao agente, por exemplo: "Se um request demandar alteração no Next.js, utilize estritamente o App Router, omitindo configurações do Pages Router". O LLM recupera essa instrução em cold-start, poupando recursos e reduzindo a latência da sua janela primária de contexto.

Engenharia reversa do contexto na stack propriamente dita (Bun, prisma, Postgres)#

O pacote da Vercel sanou a fragilidade de rotas do Next.js, mas falhou em blindar o escopo do meu domínio proprietário (regras do SaaS relativas ao banco de dados e escolhas de runtime).

Como pacotes universais jamais dariam conta de abstrações de negócios privados, implementei o controle de contexto local dividindo a infraestrutura em duas ramificações baseadas no endpoint de interface: a CLI tradicional e a IDE Kiro.

1. Injetando skills locais para o Claude code (CLI handler)#

Para ancorar a retenção de dados da CLI nativa do Claude, impedindo o context collapse da stack de banco de dados e runtime, construí repositórios de habilidades locais:

1. Instituí um path dedicado na raiz operacional: .claude/skills/meu-saas/
2. Configurei um node de instrução (arquivo): SKILL.md
3. Declarei a invariabilidade do sistema: "Este ambiente de execução é estrito. O runtime de JavaScript/TypeScript é exclusivamente Bun. O pipeline de ORM atende pelo Prisma, e o target database type é PostgreSQL. O mapa topológico do banco reside obrigatoriamente no blob prisma/schema.prisma", acoplando ponteiros para as documentações legadas.

2. Executando o steering (manejo sistemático) no domain.com#

Dado que o domain.com figura como a IDE matriz para essa stack, descobri que ele expõe nativamente um mecanismo robusto focado nesse gargalo, denominado Steering.

Simplesmente jogar artefatos Markdown em subdiretórios aguardando que indexadores RAG milagrosamente os injetassem in-time estava falhando. A solução foi padronizar o direcionamento das regras:

1. Mapeei a raiz oculta de configuração contextual da IDE no diretório: .kiro/steering/
2. Migrei todos os nós de arquitetura estrutural para a árvore interna: .kiro/steering/arquitetura.md, .kiro/steering/regras-prisma.md.

Análise Log-Output: A interceptação RAG nativa do Kiro assumiu controle do processo. A subpasta é tratada como um System Prompt Injetado de modo compulsório. Cada trigger e payload gerado (independente da profundidade do loop) passou a processar a leitura estática das premissas pré-definidas. O fenômeno da perda das configurações de Bun e Postgres foi mitigado imediatamente.

Veredito prático#

Orquestrar arquiteturas monolíticas ou de microsserviços via agentes de IA exigirá que SREs e Engenheiros gerenciem os estados de memory context das instâncias. Confiar na varredura padrão de históricos de sessão é ineficiente e propenso à ruptura sistêmica. Adotar gerenciadores como skills.sh para acoplar frameworks globais e segregar regras de domínio na blindagem de arquivos de Steering (.kiro/steering/) consolida uma defesa inquebrável, silenciando alucinações do modelo botando foco unicamente na validação iterativa e deploy do código.

Veja também

Inteligência Artificial Auditando o bypass de custos em automação CLI: analisando o OpenCode

Inteligência Artificial Por que sua IA parece defasada? O mito do "capamento" de API vs. a realidade arquitetônica

Inteligência Artificial Rodando LLMs locais no terminal: minha busca pelo modelo ideal no Ollama e Tabby

Este post está licenciado sob CC BY-NC.