Desenhando instruções para agentes: skills, hooks e hierarquias de contexto
O nascimento do desenvolvimento AI-native como disciplina trouxe uma paradoxalidade produtiva. Ferramentas como Claude Code, GitHub Copilot e Cursor transformaram o ciclo de escrita de código, mas a qualidade da colaboração homem-agente depende em maior medida da arquitetura das instruções do que das capacidades brutas do modelo. Um agente com contexto mal estruturado produz resultados inconsistentes mesmo com o modelo mais capaz. Um agente com instruções bem projetadas, hierarquia de contexto clara e hooks de ciclo de vida corretos transforma modelos medianos em assistentes de engenharia confiáveis.
A hierarquia de instruções no GitHub Copilot é definida por três nível de aplicação. O primeiro nível são as instruções globais em .github/copilot-instructions.md: aplicam-se a todos os arquivos do workspace independente de caminho. O segundo nível são as instruções específicas em .github/instructions/*.instructions.md: cada arquivo pode ter uma frontmatter com applyTo: '**/*.tsx' ou applyTo: 'src/components/**' que restringe a aplicação por glob pattern. O terceiro nível são as instruções de sessão transmitidas explicitamente via contexto. A sobreposição entre níveis é aditiva — instruções de nível mais específico complementam as de nível global, não as substituem.
O arquivo CLAUDE.md cumpre função diferente no Claude Code. Ele é o contrato de projeto: descreve a arquitetura, convenções de código, variáveis de ambiente, scripts de desenvolvimento, comandos de teste e as decisões de design que o agente deve respeitar. A diferença entre um CLAUDE.md eficaz e um ineficaz não é comprimento — é especificidade. "Use TypeScript strict mode" é uma instrução genérica que qualquer agente já aplicaria. "Nunca use any — use unknown com type guards; imports ordenados categoria → libs → components → lib → types; named exports preferidos sobre default" é uma instrução acionável que discrimina entre opções de implementação.
O arquivo AGENTS.md resolve um problema diferente: coordenação multi-agente. Em workspaces com múltiplos projetos e contextos, AGENTS.md funciona como mapa de projeto — define que projetos existem, quais agentes estão disponíveis, que skills cada agente domina, e como o orquestrador deve rotear tarefas. Um projeto no Neuro-Symbolic Context Engine, por exemplo, descreve agentes @architect, @implementer e @reviewer com domínios explicitamente separados. O @architect planeja e delega. O @implementer escreve código com auto-cura em loop. O @reviewer valida qualidade. Essa separação não é semântica — ela instrui o agente orquestrador sobre como distribuir sub-tarefas quando recebe uma instrução de alto nível.
Skills são pacotes de conhecimento de domínio encapsulados em arquivos SKILL.md. Cada skill tem frontmatter que define name, description (que serve como trigger para o agente decidir quando invocar) e applyTo opcional para escopo por arquivo. O corpo do SKILL.md contém as regras de domínio, padrões de implementação, exemplos e anti-padrões específicos para aquela especialidade. A diferença entre uma skill eficaz e uma documentação ineficaz é a densidade de instrução operacional em relação a texto explicativo. Uma skill de segurança que lista "evite SQL injection" sem explicar como detectar e corrigir o pattern específico no contexto do projeto tem utilidade próxima de zero para o agente.
Hooks de ciclo de vida controlam quando e como contexto é injetado automaticamente. O hook SessionStart é executado quando uma sessão de agente se inicia — ideal para pre-carregar contexto estático como arquitetura do projeto, variáveis de ambiente disponíveis e estado atual do repositório. O hook PostToolUse é executado após cada chamada de ferramenta — útil para observar resultados e injetar contexto corretivo se o tool produziu erro ou resultado inesperado. O hook pre-commit valida mudanças antes do commit — executa tsc, linters e testes de forma padronizada sem depender do agente lembrar de fazê-lo.
O Neuro-Symbolic Context Engine implementa uma camada de abstração sobre essa hierarquia. Em vez de gerenciar manualmente dezenas de arquivos de instrução distribuídos pelo workspace, o Engine mantém uma knowledge base estruturada com projetos, contextos, agentes e skills. Na sessão inicial, o hook SessionStart invoca smart_init que detecta o workspace, carrega os contextos relevantes com profundidade calibrada (summary vs full), injeta as instruções via copilot-instructions.md e AGENTS.md gerados automaticamente, e apresenta um digest pre-carregado no contexto da sessão. Isso elimina a latência de "search-then-load" que degrada a primeira interação de sessões sem pre-aquecimento.
A auto-cura (self-healing) é o mecanismo que torna o loop agêntico robusto. Claude Code implementa isso como: após cada mudança de código, executa tsc --noEmit para verificação de tipos. Se erros, analisa cada erro com o contexto do arquivo e tenta corrigir — máximo de 3 ciclos antes de escalar para o usuário. O protocolo explícito previne tanto a situação de agentes que param ao primeiro erro quanto a de agentes que entram em loop infinito de tentativas. A especificação de máximo de ciclos é parte da instrução de skill — ela não é um comportamento default do agente, é uma regra de domínio que a skill de self-healing define.
A avaliação da qualidade de instruções de agente segue critérios técnicos concretos. Especificidade: a instrução discrimina entre pelo menos duas opções de implementação? Acionabilidade: o agente pode verificar se a instrução foi seguida sem ambiguidade? Escopo: a instrução está corretamente restrita ao contexto onde é relevante? Hierarquia: instruções contraditórias estão resolvidas por precedência explícita? Granularidade: a instrução é tão granular que o agente a ignora por ser trivial, ou tão abstrata que produz variação indesejada? O espaço ótimo é instrução média-granular: específica o suficiente para discriminar implementações, abstrata o suficiente para cobrir variações legítimas do problema.
Arquitetos de sistemas AI-native que ignoram a disciplina de instruções eventualmente encontram o mesmo problema que arquitetos de software que ignoram a disciplina de API design: sistemas funcionando no nível da demonstração que falham no nível da produção. A diferença entre um agente de demonstração e um agente de produção não é o modelo. É a qualidade do contexto estruturado que define o que o agente pode conhecer, como deve se comportar e quali são os critérios de sucesso em cada domínio de tarefa.