Anatomia de uma Claw: 84 hooks como camada de orquestração

O primeiro hook levou quatro minutos para ser escrito. Ele bloqueava o modelo de sugerir produtos da OpenAI em um fluxo de trabalho exclusivo Anthropic. Dois meses depois, esse único hook se tornou 84. Os 84 hooks conectados a 43 skills, 19 agents especializados e 30 módulos de biblioteca. Em algum momento, a coleção deixou de ser um conjunto de scripts e se tornou uma camada de orquestração.

Uma “Claw” é uma camada de orquestração construída sobre um CLI de agent de IA, que cuida de agendamento, gerenciamento de contexto, roteamento de ferramentas e aplicação de qualidade. Ela cresce organicamente a partir da solução de falhas individuais, em vez de um design top-down. A arquitetura mapeia cinco funções identificadas por Karpathy, com a separação entre planejamento e execução surgindo como uma propriedade natural de sistemas baseados em hooks.

Eu não planejei dessa forma. Ninguém senta e diz “vou construir 15.000 linhas de infraestrutura de agent.” Você resolve um problema. Depois outro. Depois resolve o problema dos problemas interagindo entre si. Quando percebe a arquitetura, ela já existe.

Andrej Karpathy também percebeu. Em fevereiro de 2026, ele descreveu as “Claws” como uma nova camada computacional: orquestração, agendamento, gerenciamento de contexto e roteamento de ferramentas construídos sobre agents LLM, da mesma forma que agents são construídos sobre LLMs.¹ O enquadramento cristalizou algo que praticantes vinham construindo sem nomear. Este post é a anatomia de um desses sistemas: o que contém, como cresceu, onde funciona e onde falha.

TL;DR

A camada “Claws” de Karpathy descreve sistemas de orquestração construídos sobre CLIs de agents. Construí um organicamente ao longo de dois meses no Claude Code: 84 hooks distribuídos por 15 tipos de eventos, 43 skills, 19 agents e mais de 30 módulos de biblioteca. O sistema se mapeia com clareza às cinco funções das Claws (orquestração, agendamento, gerenciamento de contexto, roteamento de ferramentas, aplicação de qualidade) com uma lacuna notável (definições declarativas de fluxo de trabalho). Descoberta-chave: a separação entre planejamento e execução emergiu como propriedade natural da orquestração baseada em hooks, não como objetivo de design. A observação de Lattner de que “julgamento e abstração permanecem centrais enquanto a IA automatiza a implementação” mapeia diretamente para a arquitetura de hooks: hooks de governança exercem julgamento, hooks de automação executam a implementação.

A taxonomia das Claws

A descrição de Karpathy identifica cinco funções que uma camada Claws executa. Cada função tem um análogo direto no sistema de hooks que construí no Claude Code ao longo dos últimos dois meses.¹

A taxonomia é útil porque separa preocupações que praticantes tendem a construir de forma emaranhada. Meus primeiros hooks misturavam gerenciamento de contexto com aplicação de qualidade. O hook de rastreamento de custo tanto injetava contexto de orçamento (gerenciamento de contexto) quanto bloqueava operações caras (aplicação de qualidade). Separá-los em hooks distintos melhorou a confiabilidade porque cada hook podia falhar de forma independente sem quebrar a outra função.

O sistema completo

Os números em fevereiro de 2026:

A distribuição dos hooks por tipo de evento revela onde a complexidade de orquestração se concentra:

UserPromptSubmit carrega o maior peso porque dispara em cada mensagem do usuário. O dispatcher (prompt-dispatcher.sh) executa nove hooks sequencialmente a cada prompt: filtragem de segurança, analytics, rastreamento de uso, monitoramento do sistema, injeção de objetivo, bloqueio de estimativas de tempo, injeção de contexto, injeção de tópico de memória e monitoramento de pressão de contexto.²

Cada hook adiciona latência. Nove hooks sequenciais somam 200ms medidos por prompt. O dispatcher os executa sequencialmente (não em paralelo) porque escritas concorrentes de hooks em arquivos de estado JSON compartilhados causaram corrupção de dados em testes iniciais. Dois hooks escrevendo em jiro.state.json simultaneamente produziram JSON truncado que quebrava todos os hooks downstream. A execução sequencial é mais lenta, porém segura. O overhead de 200ms é invisível para os usuários porque a velocidade de digitação humana é o gargalo, não a latência dos hooks.

Como cresceu

O crescimento não foi linear. Seguiu um padrão de ciclos problema-solução-integração.

Fase 1: Hooks de propósito único (Semanas 1-2). Cada hook resolvia um problema. enforce-opus-model.sh bloqueava solicitações de modelos que não fossem Opus. no-time-estimates.sh removia estimativas de esforço das respostas. filter-sensitive.sh capturava credenciais em chamadas de ferramentas. Esses hooks operavam de forma independente. Nenhum hook sabia da existência de outro hook.

Fase 2: Problemas de coordenação (Semanas 3-4). Os hooks começaram a interferir uns nos outros. O filtro de credenciais bloqueava chamadas legítimas a API. O enforcer de modelo entrava em conflito com o spawn de subagents. A solução: dispatchers. Um único ponto de entrada (prompt-dispatcher.sh) substituiu sete hooks individuais de UserPromptSubmit, controlando a ordem de execução e compartilhando estado via um pipe de stdin em cache.

Fase 3: Capacidades compostas (Semanas 5-8). Hooks individuais se compuseram em sistemas. O quality loop conectou hooks pre-tool (capturando problemas antes que aconteçam) a hooks post-tool (verificando resultados depois que acontecem) por meio de um arquivo de estado compartilhado (jiro.state.json). O sistema de deliberação usou guardas contra recursão, orçamentos de spawn e protocolos de consenso para coordenar múltiplos agents sem loops infinitos. O Ralph (o loop autônomo de desenvolvimento) conectou arquivos PRD ao spawn Claude, à verificação de testes e à revisão de código em um único pipeline orquestrado.

Fase 4: Auto-consciência (Semana 9+). O sistema ficou grande o suficiente para precisar de ferramentas que o ajudassem a entender a si mesmo. Busca semântica no sistema de hooks (skill /find) permitiu que agents descobrissem hooks por propósito em vez de pelo nome do arquivo. O monitoramento de desempenho (skill /perf) rastreava se o próprio overhead do sistema estava degradando a máquina. Um monitor de pressão de contexto avisava quando o contexto injetado pela camada de orquestração estava consumindo demais a janela de contexto do modelo.

A progressão de hooks de propósito único para infraestrutura de auto-monitoramento espelha um padrão que Chris Lattner identificou em sua análise do projeto Claude C Compiler: “Bom software depende de julgamento, comunicação e abstração clara. A IA amplificou isso.”³ A arquitetura do sistema de hooks revela a mesma verdade. Os hooks valiosos não são os que automatizam tarefas. Os hooks valiosos são os que codificam julgamento sobre quando e como as tarefas devem ser automatizadas.

Hooks de julgamento vs. hooks de automação

A análise de Lattner sobre o Claude C Compiler distinguiu entre o que a IA automatiza bem (implementação) e o que permanece fundamentalmente humano (julgamento e abstração).³ Essa distinção mapeia diretamente para o sistema de hooks.

Hooks de julgamento decidem se algo deve acontecer. Eles codificam política, não procedimento.

Hooks de automação executam ações predeterminadas. Eles codificam procedimento, não política.

Os hooks de julgamento são mais difíceis de escrever, mais difíceis de testar e mais valiosos. quality-gate.sh exigiu sete modos de falha nomeados, seis critérios de evidência e um detector de linguagem hesitante. inject-context.sh exigiu cinco linhas de bash. Mas ambos são necessários. Hooks de automação fornecem os dados que hooks de julgamento avaliam. sysmon-snapshot.sh (automação) alimenta com dados o monitor de desempenho que decide se deve recomendar a limitação da contagem de agents (julgamento).

A proporção importa. Em uma camada de orquestração saudável, hooks de julgamento devem superar em número os hooks de automação. Se a maioria dos hooks apenas injeta dados ou registra métricas, o sistema automatiza bem mas governa mal. Uma contagem verificada do sistema atual: 35 hooks de julgamento, 44 hooks de automação, aproximadamente 4:5. A automação ainda lidera. A proporção começou em aproximadamente 1:6 (quase todos os hooks de injeção e logging) e se deslocou em direção ao julgamento ao longo de dois meses, conforme restrições de governança foram adicionadas após falhas que a automação pura não conseguia prevenir. A proporção ainda não alcançou paridade, o que em si é um sinal útil: este sistema ainda governa menos do que automatiza.

Separação entre planejamento e execução

O post “How I use Claude Code” de Boris Tane atraiu 936 pontos no Hacker News ao descrever um padrão de fluxo de trabalho: separar planejamento de execução.⁴ Planeje com uma sessão Claude (pesquisando, esboçando, projetando), depois execute com uma sessão nova que recebe o plano como entrada estruturada. O padrão repercutiu porque resolve um problema real: planejamento e execução competem por espaço na janela de contexto.

O sistema de hooks chegou à mesma separação por um caminho diferente. O sistema de deliberação faz spawn de agents especializados para pesquisar e debater abordagens. A saída é um PRD estruturado (Product Requirements Document) com stories, critérios de aceitação e tipos de verificação. O Ralph loop lê o PRD e faz spawn de novas instâncias Claude para implementar cada story. Agents de planejamento nunca implementam. Agents de implementação nunca planejam.

A separação não foi um objetivo de design. Ela emergiu de duas restrições independentes:

1. Pressão na janela de contexto. Planejar exige ler muitos arquivos e explorar opções. Implementar exige contexto focado na tarefa atual. Colocar ambos na mesma janela de contexto significa que nenhum recebe espaço suficiente. Sessões separadas dão a cada fase o contexto completo.

2. Independência da verificação de qualidade. Se o mesmo agent planeja e implementa, ele não consegue verificar objetivamente sua própria implementação contra o plano. Um agent novo com apenas o plano e o código fornece verificação independente. O Ralph loop impõe isso: agents de implementação executam testes, mas três agents de revisão separados (correção, segurança, convenções) verificam os resultados.

A convergência entre o fluxo de trabalho manual de Tane e o sistema automatizado de hooks sugere que a separação entre planejamento e execução é uma propriedade natural de sistemas com agents, não apenas uma preferência do praticante. Qualquer sistema que gerencie janelas de contexto e verifique saídas acabará separando planejamento de execução porque a alternativa (fazer ambos em um contexto) produz resultados piores em ambas as fases.

Onde o sistema de hooks falha

A arquitetura tem três fraquezas significativas que um framework de orquestração construído para esse propósito resolveria.

Sem definições declarativas de fluxo de trabalho. Todo fluxo de trabalho é codificado imperativamente em scripts bash. O Ralph loop tem 1.320 linhas de bash que codificam uma sequência específica: ler PRD, selecionar story, coletar contexto, fazer spawn de Claude, executar testes, executar revisões, tratar falhas, atualizar estado. Mudar o fluxo de trabalho significa editar bash. Um sistema declarativo definiria fluxos de trabalho como dados (YAML, JSON) que um interpretador executa. Fluxos declarativos são mais fáceis de modificar, compor e visualizar. Scripts imperativos são mais fáceis de escrever inicialmente, mas mais difíceis de manter conforme crescem.

A ordenação dos hooks é frágil. O dispatcher de prompts executa hooks em uma sequência hardcoded. Mover memory-capsule-inject.sh para antes de inject-context.sh quebraria a injeção de cápsula porque ela depende do ID de sessão que inject-context.sh resolve. Essas dependências são implícitas (codificadas na ordenação do dispatcher) em vez de explícitas (declaradas como dependências entre hooks). Um sistema construído para esse propósito expressaria as dependências dos hooks como um DAG e ordenaria a execução por ordenação topológica.

Sem visualização de fluxo de trabalho. Com 84 hooks, entender o caminho completo de execução de qualquer ação do usuário exige ler o código do dispatcher e rastrear cadeias de hooks manualmente. Não há ferramenta que mostre “quando o usuário digita uma mensagem, estes 9 hooks disparam nesta ordem, e o hook 3 chama a função de biblioteca X que escreve no arquivo de estado Y.” O sistema é observável por logs, mas não por estrutura. Um framework de orquestração construído para esse propósito forneceria um gráfico visual de dependências de hooks, fluxos de dados e caminhos de execução.

Essas fraquezas compartilham uma causa comum: o sistema cresceu organicamente a partir da solução de problemas individuais, em vez de ter sido projetado como uma camada de orquestração coerente. O crescimento orgânico produz sistemas que funcionam (todos os 84 hooks funcionam corretamente em produção), mas que são difíceis de raciocinar como um todo. O trade-off é real: projetar a camada de orquestração antecipadamente teria produzido melhor estrutura, mas piores capacidades, porque muitas capacidades (cápsulas de memória, allowlists de saída, orçamentos de spawn) foram inventadas em resposta a falhas que não poderiam ter sido previstas antes de ocorrerem.

O harness se torna mainstream

Três semanas depois de Karpathy nomear a camada, o conceito tem um segundo nome e uma comunidade crescente.

Geoffrey Huntley propôs uma definição formal: “Agent Harness — a camada de orquestração em torno de um modelo de linguagem que o transforma de ferramenta em colega de equipe.”⁵ O enquadramento é preciso. O harness não é o modelo. Não são as ferramentas que o modelo chama. É o sistema que decide quais ferramentas chamar, quando chamá-las e como avaliar se a chamada foi bem-sucedida. Todo sistema de agent em produção constrói essa camada. A maioria a constrói implicitamente, dentro do código da aplicação que mistura lógica de orquestração com lógica de negócio. Nomeá-la torna a arquitetura visível.

Os sinais da comunidade confirmam que o padrão está se espalhando. Pieter Levels relatou ter migrado permanentemente para rodar Claude Code em um servidor, tratando-o como infraestrutura em vez de ferramenta local.⁶ Anthropic lançou o Remote Control, permitindo que usuários iniciem tarefas no terminal e as retomem em Claude.ai.⁷ Ben Cherny anunciou /simplify e /batch como skills first-party.⁸ Cada uma dessas é um recurso de harness: execução persistente, orquestração remota e módulos de capacidade embutidos. O CLI está crescendo até se tornar o harness.

Enquanto isso, praticantes estão construindo seus próprios componentes de harness. Um desenvolvedor publicou 22 comandos personalizados de Obsidian + Claude Code para um sistema operacional pessoal.⁹ Outro criou uma skill de agent “Visual Explainer” com slash commands complementares.¹⁰ Os padrões coincidem: dispatchers, skills, estado compartilhado, hooks orientados a eventos. Ninguém lê um guia de framework antes de construir esses sistemas. Eles resolvem um problema, depois outro, depois os problemas dos problemas interagindo entre si.

Dois projetos recentes revelam o quão sofisticados os componentes de harness construídos pela comunidade se tornaram. nah é um guard de permissão contextual que se registra como hook PreToolUse.¹⁴ Ele classifica 20 tipos distintos de ação (escritas em arquivos, requisições de rede, spawn de processos etc.) e aplica políticas por tipo. A ferramenta detecta ataques de decomposição em pipe, em que um agent encadeia comandos inócuos para alcançar uma operação bloqueada. A arquitetura espelha filter-sensitive.sh e recursion-guard.sh deste post, alcançados de forma independente por outro praticante resolvendo os mesmos problemas de governança.

O Rudel fornece analytics de sessão ao ingerir dados de sessões do Claude Code no ClickHouse.¹⁵ A análise de 1.573 sessões revelou que apenas 4% dos usuários invocam skills e 26% das sessões são abandonadas em até 60 segundos. Os números confirmam o que a arquitetura do harness implica: a maioria dos usuários interage com CLIs de agents no nível superficial. A camada de orquestração descrita neste post representa a extremidade profunda de uma distribuição de uso em que a grande maioria nunca deixa a extremidade rasa. A distância entre o que a ferramenta pode fazer e o que a maioria dos usuários pede a ela é o espaço que a infraestrutura do harness preenche.

Autoresearch: o harness como loop de pesquisa

O projeto autoresearch do próprio Karpathy demonstra o padrão do harness em um domínio diferente.¹¹ O sistema aponta um modelo de linguagem para um script de treinamento (train.py), executa um experimento de cinco minutos, avalia o resultado contra uma métrica fixa (bits de validação por byte) e mantém melhorias ou descarta regressões. Ao longo de dois dias, o sistema executou cerca de 700 experimentos e encontrou cerca de 20 melhorias genuínas, reduzindo o tempo de treinamento do GPT-2 em 11%.

A arquitetura é idêntica à do sistema de hooks descrito acima. Um harness fixo de avaliação (prepare.py) é o equivalente a hooks de julgamento: decide se um experimento teve sucesso. O script de treinamento (train.py) é o equivalente a hooks de automação: executa as modificações do agent. O gerenciamento de branch git (manter em caso de melhoria, resetar em caso de regressão) é o equivalente ao gerenciamento de estado do Ralph loop. O log results.tsv é o equivalente à telemetria de sessão.

O padrão se transfere porque o harness resolve um problema que é independente de domínio. Seja o agent escrevendo código, otimizando um loop de treinamento ou gerenciando um pipeline de conteúdo, ele precisa de: uma forma de avaliar resultados contra critérios, uma forma de manter ou descartar mudanças, uma forma de manter estado entre iterações e uma forma de rodar autonomamente sem intervenção humana. Esses quatro requisitos produzem a mesma arquitetura, independentemente do que o agent esteja realmente fazendo.

O CEO da Shopify, Tobi Lütke, adaptou o autoresearch internamente. Seu modelo menor otimizado por agents superou um modelo maior configurado manualmente, validando a afirmação de que a iteração autônoma guiada pelo harness descobre configurações que humanos não pensam em testar.¹²

A lacuna de segurança no harness

O harness resolve a orquestração. Ele não resolve automaticamente a segurança.

Um estudo sobre refinamento iterativo de código guiado por LLM descobriu que 43,7% das cadeias de iteração continham mais vulnerabilidades após dez rodadas de modificações do agent do que o código base do qual partiram.¹³ A causa raiz foi specification drift: à medida que o agent otimizava para correção funcional, removia progressivamente a lógica defensiva e enfraquecia o tratamento de exceções. Pior, adicionar ferramentas de análise estática de segurança (gates SAST) ao loop de iteração na verdade aumentou a degradação latente de 12,5% para 20,8%. Os scanners criaram uma falsa sensação de segurança que fez o agent ficar menos cauteloso, não mais.

A descoberta sobre degradação é diretamente relevante para o design do harness. Os hooks de julgamento descritos neste post (quality-gate.sh, filter-sensitive.sh, recursion-guard.sh) abordam as dimensões de qualidade e segurança que a automação sozinha degrada. O framework SCAFFOLD-CEGIS que tratou o problema de degradação usou quatro camadas de verificação com gates, alcançando uma taxa de degradação latente de 2,1% com 100% de monotonicidade de segurança.¹³ A arquitetura é paralela ao sistema de hooks: camadas separadas de avaliação, cada uma verificando uma propriedade diferente, com gates explícitos entre fases.

Um esforço separado corrobora o modelo de ameaças do lado da produção. A resposta da Perplexity ao NIST sobre segurança de agents de IA mapeou a superfície de ataque de sistemas agênticos operando em escala.¹⁶ Os vetores primários: injeção indireta de prompt por canais de dados (páginas web, e-mails, saídas de ferramentas), violações da tríade CIA específicas a agents (exfiltração de dados via chamadas de ferramentas, manipulação de ações via envenenamento de contexto, exaustão de recursos via spawn recursivo) e CVEs reais de sistemas adjacentes a agents. Sua arquitetura de defesa recomendada (filtragem em nível de entrada, alinhamento em nível de modelo e aplicação determinística via sandboxing e allowlists) espelha o padrão de três camadas que emergiu organicamente no sistema de hooks descrito aqui. Hooks de automação filtram entradas. O modelo exerce julgamento. Hooks de governança aplicam restrições determinísticas que o modelo não pode sobrepor.

A lição para praticantes: se o seu harness apenas automatiza e orquestra sem governar, a execução iterativa do agent introduzirá regressões de segurança que ferramentas padrão não conseguem detectar. Os hooks de julgamento não são overhead. Eles são a razão pela qual o sistema não degrada.

O que praticantes devem levar daqui

Se você está construindo uma camada de orquestração sobre um CLI de agent — partindo do guia do Claude Code ou do zero — três padrões deste sistema se transferem diretamente.

Comece com dispatchers, não com hooks individuais. A maior melhoria arquitetural foi substituir sete hooks individuais de UserPromptSubmit por um único dispatcher que os executa sequencialmente. Se você antecipa mais de três hooks em qualquer tipo de evento, construa o dispatcher primeiro. Os 30 minutos gastos escrevendo um dispatcher economizam horas depurando bugs de interação entre hooks mais tarde. O padrão mínimo:

#!/bin/bash
# dispatcher.sh — sequential hook execution with shared stdin
HANDLERS=("inject-context.sh" "track-usage.sh" "quality-gate.sh")
HOOK_DIR="$(dirname "$0")/handlers"
INPUT=$(cat)  # Cache stdin once (each handler gets the same input)

for handler in "${HANDLERS[@]}"; do
    [ -x "$HOOK_DIR/$handler" ] && echo "$INPUT" | "$HOOK_DIR/$handler"
done

Registre o dispatcher único como seu ponto de entrada de hook. Adicione handlers ao array conforme for construindo. Cada handler lê o mesmo stdin em cache (o payload do evento de hook) e escreve no stdout de forma independente.

Separe julgamento de automação cedo. Ao escrever um novo hook, pergunte: “O hook decide se algo deve acontecer, ou executa uma ação predeterminada?” Hooks de julgamento precisam de mais testes, mais tratamento de edge cases e mais iteração. Hooks de automação precisam de confiabilidade e desempenho. Tratá-los da mesma forma leva a hooks de julgamento subtestados e hooks de automação superengenheirados.

Deixe a separação entre planejamento e execução emergir. Não force a separação no primeiro dia. Construa a coisa mais simples que funcione. Quando você notar que a janela de contexto do seu agent está cheia demais tanto para planejamento quanto para implementação, separe-os. Quando notar que seu agent não consegue verificar objetivamente seu próprio trabalho, adicione agents de revisão independentes. A separação parecerá óbvia quando as restrições a exigirem.

O harness está se tornando mainstream porque o padrão é inevitável. Seja você chamando a camada de Claws, Agent Harness ou apenas “minha pasta de hooks”, qualquer sistema que coordene agents rumo a objetivos convergirá para a mesma arquitetura: dispatchers para ordenação, hooks de julgamento para governança, hooks de automação para execução e arquivos de estado para continuidade. O vazamento do código-fonte do Claude Code confirmou que a própria arquitetura interna da Anthropic segue esses mesmos padrões — o modo coordinator é implementado inteiramente como instruções de system prompt, não como orquestração em nível de código. A abordagem baseada em hooks tem uma vantagem sobre frameworks de orquestração construídos para esse propósito: zero compromisso. Cada hook é independente. Você pode adotar um hook, dez hooks ou oitenta e quatro hooks. Você pode deletar qualquer hook sem quebrar os outros (assumindo que você mantenha o dispatcher). Não há framework para aprender, nenhuma dependência para gerenciar, nenhum runtime para operar. A camada de orquestração é apenas arquivos.

FAQ

O que é um agent harness ou camada “Claws”?

Uma camada Claws (nomeada por Andrej Karpathy em fevereiro de 2026) é o sistema de orquestração construído sobre um CLI de agent que o transforma de ferramenta em colega de equipe.¹ Ela executa cinco funções: orquestração (coordenar múltiplos agents), agendamento (determinar quando tarefas são executadas), gerenciamento de contexto (manter informações relevantes entre turnos), roteamento de ferramentas (direcionar chamadas de ferramentas pelos handlers apropriados) e aplicação de qualidade (verificar se as saídas atendem aos padrões). Geoffrey Huntley formalizou a definição como “a camada de orquestração em torno de um modelo de linguagem.”⁵

Como funcionam os hooks PreToolUse no Claude Code?

Hooks PreToolUse disparam antes de cada chamada de ferramenta (comandos Bash, escritas em arquivos, edições em arquivos, spawns de subagents) e recebem o payload da chamada de ferramenta como JSON no stdin. O script do hook avalia o payload e retorna uma decisão: permitir, negar ou modificar. O modelo não pode pular, sobrepor ou negociar com hooks porque eles executam no nível da infraestrutura, não no nível do prompt.² Um padrão de dispatcher executa múltiplos hooks sequencialmente em cada evento, com um pipe de stdin em cache para que cada handler receba a mesma entrada.

Qual é a diferença entre hooks de julgamento e hooks de automação?

Hooks de julgamento decidem se algo deve acontecer (política), enquanto hooks de automação executam ações predeterminadas (procedimento). Hooks de julgamento incluem quality gates, filtros de credenciais, guardas contra recursão e cost gates. Hooks de automação incluem injeção de contexto, rastreamento de uso, monitoramento do sistema e heartbeats.³ A proporção importa: um sistema com majoritariamente hooks de automação automatiza bem, mas governa mal. O sistema atual roda 35 hooks de julgamento para 44 hooks de automação, deslocando-se em direção à governança conforme falhas revelaram o que a automação pura não consegue prevenir.

Por que a separação entre planejamento e execução emerge naturalmente em sistemas de agents?

Duas restrições independentes forçam a separação. Primeiro, planejar exige ler muitos arquivos e explorar opções, enquanto implementar exige contexto focado na tarefa atual, e colocar ambos na mesma janela de contexto significa que nenhum recebe espaço suficiente. Segundo, se o mesmo agent planeja e implementa, ele não consegue verificar objetivamente seu próprio trabalho contra o plano.⁴ Qualquer sistema que gerencie janelas de contexto e verifique saídas acabará separando planejamento de execução porque a alternativa produz resultados piores em ambas as fases.

Como começo a construir meu próprio sistema de hooks?

Comece com dispatchers, não com hooks individuais. Se você antecipa mais de três hooks em qualquer tipo de evento, construa um único dispatcher que execute handlers sequencialmente a partir de um array. Os 30 minutos gastos escrevendo um dispatcher economizam horas depurando bugs de interação entre hooks mais tarde. Separe julgamento de automação cedo perguntando “este hook decide se algo deve acontecer, ou executa uma ação predeterminada?” Comece pelo tutorial de hooks do Claude Code e adicione hooks conforme falhas reais os exigirem, em vez de projetar o sistema completo antecipadamente.

Fontes