Engenharia Agêntica: Skills, Subagents e Hooks Explicados

O Momento em que o Vibe Coding Parou de Escalar

Em fevereiro de 2025, Andrej Karpathy postou no X o que parecia uma piada. Ele descreveu "vibe coding" como aceitar o que quer que um LLM produzisse sem realmente ler. "Eu só vejo coisas, digo coisas, executo coisas e copio e colo coisas", escreveu ele, "e na maior parte funciona".

E funcionou na maior parte. Por cerca de um ano.

No final de 2025, a indústria começou a ver a conta chegando. A pesquisa da Forrester publicada em 2025 descobriu que código com envolvimento significativo de IA carregava cerca de 1,7 vezes a taxa de problemas graves. Auditorias separadas de empresas de segurança colocaram a participação de código gerado por IA com falhas de segurança entre 40 e 62 por cento, dependendo do estilo de prompt e da linguagem. Modelos alucinam APIs, pulam validação de entrada, vazam segredos em logs e chamam funções com confiança que sequer existem.

O que quebrou foi a suposição de que um único prompt e uma única janela de contexto poderiam carregar uma base de código real. Os repositórios ficaram maiores. As convenções ficaram mais específicas. Os efeitos colaterais (migrations, deploys, chamadas pagas de API) ficaram mais perigosos. O fluxo de trabalho que parecia mágico em um app greenfield desmoronou quando você o apontou para um serviço com cinco anos de decisões consolidadas.

As rachaduras apareceram de três formas. Modelos esqueciam as convenções do projeto no meio de uma sessão e reintroduziam padrões que o time havia gastado meses para apagar. Sessões longas acumulavam tanto contexto irrelevante que o modelo começava a ignorar a tarefa real. Agentes alegremente rodavam comandos destrutivos porque nada os impedia. Um prompt que dizia "não dê push na main" funcionava cerca de 95 por cento das vezes, o que é outra forma de dizer que falhava 1 em cada 20 sessões.

No final de 2025, todo time sério usando Claude Code, Cursor ou ferramentas similares havia construído alguma versão do mesmo andaime ao redor do modelo. Ninguém ainda tinha um nome para isso.

---

A Renomeação de Karpathy para Engenharia Agêntica

Em fevereiro de 2026, Karpathy postou de novo. O novo termo era "engenharia agêntica" (agentic engineering).

O vibe coding, ele argumentou, descrevia o modo de brinquedo. A engenharia agêntica descrevia o que as pessoas que de fato entregavam estavam fazendo: escrevendo arquivos de contexto específicos do projeto, definindo skills estreitas, gerando subagents para trabalho isolado e controlando o uso de ferramentas através de hooks determinísticos. O modelo ainda está fazendo a digitação. O humano está fazendo a engenharia do sistema dentro do qual o modelo roda.

A tooling amadureceu entre os dois posts. As Boas Práticas do Claude Code da Anthropic documentaram a convenção do CLAUDE.md e o padrão de subagent. Building Agents with the Claude Agent SDK detalhou o agent loop e o papel dos hooks. As Skills chegaram em outubro de 2025: pequenos arquivos markdown que o agente carrega apenas quando a tarefa os aciona. O Cursor 2.0 lançou agents em background em VMs na nuvem com isolamento por git-worktree e até oito agents paralelos.

"Context Engineering for Coding Agents" de Martin Fowler capturou o princípio que amarrou tudo isso. O trabalho não é mais prompt engineering, que otimizava uma string de texto. O trabalho é context engineering: decidir o que o modelo vê, quando ele vê e o que ele tem permissão de fazer com isso.

Isso não é específico da Anthropic. Cursor chama de rules e background agents. GitHub Copilot usa a convenção AGENTS.md. Gemini CLI usa GEMINI.md. Os nomes diferem. O formato não.

---

Os Quatro Pilares da Engenharia Agêntica

Antes de mergulhar fundo em cada pilar, ajuda vê-los lado a lado. Eles parecem similares (são todos "coisas que você dá ao agente") mas resolvem problemas diferentes.

O padrão: CLAUDE.md é o que o modelo sabe. Skills são o que o modelo pode consultar. Subagents são a quem mais o modelo pode pedir. Hooks são o que o modelo não pode evitar.

Cada pilar existe porque os outros três não conseguem resolver aquele modo específico de falha.

---

CLAUDE.md: A Camada Consultiva

CLAUDE.md (ou AGENTS.md, ou GEMINI.md, dependendo da sua ferramenta) é um arquivo markdown na raiz do seu repo. O agente o lê no início de toda sessão e o trata como contexto de fundo.

Não é memória no sentido de produto de consumo. É o arquivo que você, o humano, escreve para contar ao agente o que ele teria aprendido se estivesse no time por um ano.

O que pertence a ele:

• Stack e versões: "Next.js 16 App Router, React 19, Yarn 1.22 (npm proibido), Node 22."
• Layout do repo: qual diretório faz o quê.
• Comandos: yarn dev, yarn test, yarn build:ci, com notas sobre qual é seguro de rodar.
• Regras inquebráveis: "Nunca dê push direto para main. Sempre crie uma feature branch."
• Convenções de estilo: largura de tab, regras de lint que mordem, convenções de nomenclatura.
• Atalhos de domínio: termos de glossário específicos do seu produto.

O que não pertence: instruções passo a passo para tarefas ocasionais (essas vão em Skills), documentos longos de referência (o modelo lê por cima, prefira linkar) e qualquer coisa secreta (o conteúdo do CLAUDE.md é carregado no contexto, e contexto pode ser citado de volta).

A armadilha em que a maioria dos times cai é o CLAUDE.md "tudo num bagel só". Um arquivo de 4.000 linhas com todo padrão de código e toda decisão de arquitetura. O modelo carrega tudo isso em toda tarefa e começa a tratar os 5 por cento relevantes da mesma forma que os 95 por cento irrelevantes. Os custos de token sobem. A aderência a regras específicas cai.

Um bom CLAUDE.md está mais próximo de um post-it do que de uma wiki. Mire em uma tela de contexto essencial. Se você se pegar escrevendo uma seção que começa com "Ao fazer X..." então X provavelmente quer ser uma skill. CLAUDE.md é para "sempre verdadeiro". Skills são para "verdadeiro quando".

---

Skills: Arquivos de Conhecimento Just-in-Time

Skills são pequenos arquivos markdown (tipicamente abaixo de 200 linhas) que o agente carrega apenas quando a tarefa corresponde. Cada skill tem um nome, uma descrição e um corpo. A descrição é o que o agente lê primeiro para decidir se puxa a skill completa.

A Anthropic lançou skills como um conceito de primeira classe no final de 2025. Você coloca um arquivo de skill em um diretório conhecido; seu frontmatter descreve quando usá-la. Ao planejar uma tarefa, o agente varre as descrições de skills disponíveis e carrega aquelas cuja descrição combina.

Bons exemplos de skill:

• rebase-cleanly: como rebasear em develop, regras de resolução de conflitos, o que fazer se os testes falharem pós-rebase.
• review-stripe-integration: checklist para mudanças que tocam em webhooks Stripe, idempotency keys, price IDs.
• add-shadcn-component: os comandos exatos e convenções de import para adicionar um componente shadcn/ui a este repo.
• debug-flaky-test: a ordem de operações preferida do time quando um teste de CI está intermitente.

Cada uma é procedural e estreita. Cada uma seria detalhe demais para viver no CLAUDE.md, mas importante demais para deixar ao conhecimento geral do modelo.

O modelo mental: CLAUDE.md é seu colega contando ao novato o básico no primeiro dia. Uma skill é o runbook que ele entrega ao novato quando um webhook do Stripe falha às 2 da manhã. Você não decora o runbook; você o lê quando precisa.

Skills compõem. O agente pode carregar três skills em uma tarefa ("adicionar uma nova rota de API" mais "validar entrada com Zod" mais "escrever um teste Vitest") sem você prever a combinação com antecedência.

Descrições de skills importam mais do que você imagina. Descrições vagas ("útil para coisas de código") ou nunca acionam ou acionam em tudo. Escreva descrições que nomeiem a situação: "Use quando o usuário pedir para rebasear uma branch, resolver conflitos de merge ou limpar histórico de commits."

---

Subagents: Trabalhadores de Contexto Isolado

Um subagent é um agente que o agente principal pode chamar. Ele tem seu próprio system prompt, sua própria janela de contexto e suas próprias permissões de tool. Quando termina, retorna um resultado ao agente principal. Depois desaparece.

A leitura ingênua é "subagents são para paralelismo". Isso é parte (Cursor 2.0 anuncia até oito agents em background paralelos) mas paralelismo não é o benefício principal. O benefício principal é isolamento de contexto.

Três padrões em que subagents valem a pena:

1. O pesquisador. Você quer que o agente vasculhe 200 arquivos e resuma o que encontrar. Se o agente principal faz isso, todos os 200 arquivos acabam no contexto principal, mesmo que você só precisasse de três frases de resumo. Um subagent de pesquisa lê os 200 arquivos, resume, retorna um parágrafo. O contexto principal fica limpo.

2. O revisor. Antes de um commit, você quer uma passada fresca no diff. Um subagent revisor carrega uma skill de "code review", lê o diff sem outro contexto e reporta problemas. Como ele não tem memória da discussão de implementação que o agente principal teve com você, ele não pode racionalizar para eliminar problemas.

3. A operação arriscada. Um script de migration. Um rename em massa. Uma mudança de schema. O agente planeja e executa em isolamento, depois reporta. Se algo der errado, o estrago fica contido no contexto do subagent.

Há um custo real. Cada subagent é mais uma chamada de modelo e mais uma janela de contexto. Eles adicionam complexidade de coordenação. Um time que gera um subagent para cada tarefa queima tokens e se atrasa.

A regra prática: gere um subagent quando uma das três coisas for verdadeira. (1) A tarefa despejaria muito lixo no contexto principal. (2) A tarefa se beneficia de uma perspectiva nova. (3) A tarefa é arriscada e você quer ela em sandbox. Caso contrário, continue trabalhando na sessão principal.

Coleções open-source como awesome-claude-code-subagents da VoltAgent catalogam centenas de subagents pré-construídos. A maioria dos times se sai melhor com três ou quatro subagents customizados ajustados à sua base de código do que com dezenas de genéricos.

---

Hooks: Guardrails Determinísticos

Hooks são a parte da stack da qual o modelo não consegue se safar com conversa. Eles são comandos de shell conectados a eventos de tool. Quando o evento dispara, o comando roda. O modelo não tem voz.

Os eventos canônicos:

• PreToolUse: dispara antes de uma chamada de tool. Pode bloquear a chamada.
• PostToolUse: dispara depois de uma chamada de tool. Útil para formatters, validadores, efeitos colaterais.
• Stop: dispara quando o agente termina um turno. Útil para notificações.
• Notification: dispara em certas mensagens do agente.

Por que hooks superam prompts para segurança: prompts são probabilísticos. Mesmo uma instrução clara como "nunca rode rm -rf" vai falhar ocasionalmente, porque o modelo está fazendo completação de padrão. Um hook que filtra o comando por rm -rf e sai com código diferente de zero antes do shell ver vai falhar zero por cento das vezes. É uma regex, não um vibe.

Três hooks que vale a pena ter:

pre-bash-guard (PreToolUse no Bash). Lê o comando, bloqueia padrões perigosos: rm -rf /, git push --force contra branches protegidas, DROP TABLE, sobrescritas diretas de arquivos .env*. Um shell script de 30 linhas te salva de desastres que prompts não conseguem prevenir de forma confiável.

post-edit-prettier (PostToolUse em Edit/Write). Depois que o agente edita um arquivo .ts ou .tsx, roda prettier. Capturar isso deterministicamente mantém o estilo consistente ao longo da sessão.

notify-on-stop (Stop). Quando o agente termina uma tarefa demorada, dispara uma notificação no macOS ou um ping no Slack. Qualidade de vida, mas muda como você trabalha: você pode deixar o agente rodar por dez minutos sem precisar ficar de babá.

Há um pequeno custo de performance. Cada hook é um process spawn. Na prática isso é imperceptível comparado à latência do próprio modelo, e o determinismo vale a pena.

A mudança mental: pare de pensar em segurança como algo que você pede ao modelo para fazer. Comece a pensar em segurança como algo que o ambiente impõe, da mesma forma que um pipeline de CI impõe testes. O modelo é um júnior rápido. Hooks são o pre-commit hook que o júnior não pode desabilitar.

---

Como os Quatro Pilares se Compõem

Aqui está como a configuração de um time real se parece, em prosa.

O repo tem um CLAUDE.md na raiz. Cerca de 80 linhas. Ele lista a stack (Next.js 16, React 19, Yarn, Node 22), o layout de diretórios, o comando de teste, a regra de deploy e um glossário de cinco termos de domínio.

Em .claude/skills/, seis arquivos de skill: rebase-cleanly.md, add-api-route.md, review-stripe.md, debug-firestore.md, write-deep-dive.md, sql-migration.md. Cada um tem de 80 a 150 linhas.

Em .claude/subagents/, três. Um reviewer roda antes de commits e reporta problemas do diff. Um researcher é invocado quando o agente principal precisa ler mais de dez arquivos. Um test-runner é invocado quando um teste falha na primeira tentativa; ele isola a falha sem poluir o contexto principal.

Em .claude/hooks/, quatro. pre-bash-guard.sh bloqueia comandos perigosos. pre-edit-env-guard.sh bloqueia edições em .env.local. post-edit-prettier.sh roda prettier após edições em arquivos .ts/.tsx. notification.sh dá ping no macOS quando uma tarefa longa termina.

Uma sessão normal: o desenvolvedor pede ao agente para "adicionar uma nova rota de API que retorna os bookmarks do usuário." O agente lê o CLAUDE.md, combina com a skill add-api-route e a carrega, escreve o arquivo. O hook de pós-edição roda o prettier. Ele escreve um teste, o prettier roda de novo. Ele pede ao subagent revisor para revisar o diff. O revisor sinaliza validação de entrada faltando; o agente principal adiciona. O desenvolvedor pede para commitar. O hook de pré-bash checa a branch e permite o commit. O hook de stop dá ping no desenvolvedor.

Nenhuma parte desse fluxo precisou de um prompt longo. O prompt foi "adicione uma nova rota de API que retorna os bookmarks do usuário." Todo o resto estava conectado ao ambiente.

---

Anti-Padrões que Desenvolvedores Continuam Entregando

Alguns padrões para evitar, tirados de times que adotaram esta stack mal.

O CLAUDE.md gigantesco. Alguns times tratam o CLAUDE.md como depósito de toda decisão de três anos. O resultado é um arquivo de 5.000 linhas que o modelo carrega mas não internaliza. A regra de não usar npm acaba ensanduichada entre duas páginas de justificativas arquiteturais, e o modelo absorve as justificativas e esquece a regra. Mantenha o CLAUDE.md enxuto.

A aposta sem hooks. Alguns times pulam os hooks inteiramente, contando com prompts para manter o agente seguro. Isso funciona na maior parte do tempo, o que é exatamente o problema. "Na maior parte do tempo" não é bom o suficiente para rm -rf ou git push --force. Se a consequência é "perdi uma hora de trabalho", prompts servem. Se a consequência é "derrubei uma tabela de produção", você precisa de um hook.

Espalhamento de subagents. Alguns times constroem um subagent para todo papel concebível. Pesquisador, revisor, planejador, sumarizador, nomeador, refatorador, documentador, testador. Cada um é mais um arquivo para manter, mais um conjunto de tokens, mais overhead de coordenação. Times que têm sucesso com subagents tendem a ter de três a cinco, cada um com um trabalho claro. Não vinte.

Skill como despejo de documentação. Uma skill não é um lugar para suas páginas antigas de wiki. Se uma skill tem 800 linhas, o modelo carrega 800 linhas toda vez que ela aciona. Se sua skill é longa, provavelmente são duas skills.

Tratar Skills como CLAUDE.md. Colocar contexto sempre-verdadeiro em uma skill significa que ele carrega apenas às vezes. A regra valendo para todo o time "nunca use npm" pertence ao CLAUDE.md, porque se aplica a toda tarefa.

Hooks que bloqueiam o agente por dez segundos. Um hook que roda uma suíte completa de testes em toda edição torna o agente inutilizável. Hooks devem ser rápidos. As verificações caras pertencem ao CI.

---

A Configuração Prática que Você Pode Adotar Esta Semana

Se você leu até aqui e quer um ponto de partida, aqui está a versão enxuta. Um engenheiro sênior consegue montar isto em um dia, e é o suficiente para tornar a programação agêntica significativamente mais confiável do que o padrão do vibe coding.

CLAUDE.md (cerca de 50 linhas). Stack e versões. Package manager (e quais nunca usar). Diretórios de topo. As cinco regras inquebráveis (não dê push para main, não toque em .env.local, use estes comandos de teste). Uma curta lista de termos de domínio. Resista à tentação de adicionar mais.

Duas skills. rebase-cleanly.md (os passos de rebase do seu time, no máximo 80 linhas) e review-changes.md (sua checklist de code review, no máximo 100 linhas).

Um subagent revisor. Carrega review-changes.md, lê o diff, reporta problemas. Invocado antes de commits.

Três hooks. PreToolUse no Bash bloqueia rm -rf, git push --force contra branches protegidas e edições em arquivos .env*. PostToolUse em Edit/Write roda prettier em arquivos .ts/.tsx editados. Stop dispara uma notificação no macOS quando o agente termina.

É isso. CLAUDE.md mais duas skills mais um subagent mais três hooks. Uma pasta com talvez oito arquivos, todos sob controle de versão, todos revisáveis pelo resto do time.

Você vai iterar. Depois de uma semana, você vai notar tarefas em que o agente continua tropeçando e codificá-las como novas skills. Você vai ver categorias de comandos ruins e adicioná-las ao pre-bash guard. Você vai identificar o momento em que um subagent pesquisador teria mantido seu contexto principal limpo e adicionar um. Os quatro pilares são o formato. O conteúdo é seu.

A mudança de vibe coding para engenharia agêntica não é um degrau a mais em esperteza. É um degrau em direção à disciplina operacional. Você está tratando o agente da forma como trataria qualquer outro sistema que roda em produção: com convenções, guardrails e isolamento entre responsabilidades. Menos mágica, mais engenharia, e um fluxo de trabalho que escala além do primeiro mês.

---

Perguntas Frequentes

Isso é específico do Claude Code ou se aplica ao Cursor e a outros agents?

Os pilares se aplicam entre ferramentas; os nomes diferem. Cursor usa arquivos de "rules" e "background agents". GitHub Copilot usa AGENTS.md. Gemini CLI usa GEMINI.md. Hooks ainda não são universais (Claude Code tem a implementação mais madura), mas a maioria das ferramentas tem algum equivalente. O modelo mental (camada de contexto, conhecimento sob demanda, trabalhadores isolados, guardas determinísticas) generaliza mesmo onde a implementação difere.

Qual a diferença entre uma Skill e colocar tudo no CLAUDE.md?

Carregamento. CLAUDE.md carrega no início de toda sessão. Skills carregam apenas quando sua descrição combina com a tarefa. Se você colocar conhecimento procedural para dez tarefas diferentes no CLAUDE.md, o modelo carrega tudo em toda tarefa, o contexto enche-se de conteúdo majoritariamente irrelevante e a aderência a regras específicas cai. Skills mantêm o CLAUDE.md enxuto e mantêm os detalhes procedurais disponíveis sob demanda.

Quando devo criar um subagent versus apenas usar um prompt mais longo?

Três condições te empurram para um subagent. (1) A tarefa despejaria muito conteúdo no contexto principal. (2) Você quer uma perspectiva nova que o raciocínio acumulado do agente principal não consiga contaminar. (3) A tarefa é arriscada e você quer ela em sandbox. Caso contrário, um prompt mais longo ou uma skill costuma ser a melhor ferramenta. Subagents custam tokens e coordenação.

Hooks deixam o agente mais lento?

Cada hook é um process spawn, então adiciona milissegundos a segundos dependendo do que faz. Na prática, isso é ofuscado pela latência do próprio modelo. Hooks longos (rodar uma suíte completa de testes em toda edição) vão deixar o agente parecendo lerdo; esses pertencem ao CI. Uma boa regra: hooks de PreToolUse devem sair em menos de 200ms no caso comum; hooks de PostToolUse como formatters podem levar um ou dois segundos sem ninguém notar.

Devo commitar meu CLAUDE.md no repo?

Sim, quase sempre. CLAUDE.md é um artefato do time: ele codifica as convenções que todo mundo (humano ou agente) deve seguir. Commitá-lo significa que os agents de todo o time trabalham a partir do mesmo contexto, e o arquivo é revisado como qualquer outro código. A única coisa que você pode querer manter local são as configurações de permissão por desenvolvedor (Claude Code suporta um settings.local.json para isso).

---

Considerações Finais

Os dois posts de Karpathy, com um ano de diferença, delimitam bem o que aconteceu com programação com IA em 2025. O primeiro foi permissão para brincar. O segundo foi a conta chegando. O vibe coding foi útil como modo de descoberta: ensinou as pessoas o que esses modelos podiam fazer sem fazê-las aprender um SDK primeiro. Não foi projetado para entregar.

O que está substituindo isso é reconhecível para qualquer um que tenha trabalhado em sistemas reais. Você anota as invariantes (CLAUDE.md). Você empacota os procedimentos (Skills). Você cria trabalhadores isolados para tarefas arriscadas ou pesadas em contexto (Subagents). Você instala guardrails nas fronteiras (Hooks). Nada disso é exótico. É a mesma disciplina operacional que distingue um projeto de hobby de um serviço que roda na segunda de manhã sem ninguém de plantão.

O que me surpreende sobre as configurações de times que funcionam é o quanto elas são pequenas. Oito arquivos. Talvez mil linhas no total. Um subagent revisor. Três hooks. Isso é o suficiente para converter um modelo que ocasionalmente derruba seu banco de dados em um colega de time que não derruba. A alavanca não está no volume. Está em colocar a invariante certa no pilar certo.

Se você ainda está em modo vibe coding puro em meados de 2026, você não está atrasado. Você está no estágio em que a maior parte do ganho de produtividade vem de tornar o modelo entediante: mais previsível, mais restrito, mais revisável. Menos mágica, de propósito. Esse é o trabalho.