Claude Code como Infraestrutura

Andrej Karpathy cunhou um termo para o que cresce ao redor de um agente LLM: garras. Os hooks, scripts e orquestração que permitem ao agente agarrar o mundo além da sua janela de contexto.¹ A maioria das pessoas trata o Claude Code como uma caixa de chat com acesso a arquivos. Digitam um prompt, observam ele editar um arquivo e seguem em frente. Essa perspectiva não enxerga o que a ferramenta realmente é.

Claude Code não é um recurso de IDE. É infraestrutura. E a diferença entre tratá-lo como um ou outro determina se o desenvolvimento assistido por IA fica em ganhos de 10% de produtividade ou avança para algo fundamentalmente diferente.

TL;DR

Claude Code expõe 17 eventos de ciclo de vida, cada um hookável com scripts shell que disparam antes, durante ou depois de cada chamada de ferramenta.² Empilhe hooks em dispatchers, dispatchers em skills, skills em agentes, agentes em workflows, e você obtém uma camada programável entre você e o modelo que impõe restrições que o modelo não consegue pular. Eu construí 84 hooks, 48 skills, 19 agentes e ~15.000 linhas de orquestração em dois meses. Zero frameworks. Zero dependências externas. Tudo em bash e JSON. O resultado é um sistema de desenvolvimento autônomo que escreve, revisa e publica código enquanto eu durmo. Este post explica a arquitetura, por que a perspectiva de IDE limita as pessoas e o que muda agora que o Remote Control torna essa infraestrutura acessível de qualquer lugar.

A Perspectiva de IDE Está Errada

O modelo mental padrão: Claude Code é um autocomplete mais inteligente. Você senta no terminal, dá tarefas e supervisiona o resultado. Esse modelo limita sua produtividade ao que você consegue supervisionar pessoalmente.

O modelo mental de infraestrutura: Claude Code é um runtime programável com um kernel LLM. Cada ação que o modelo executa passa por hooks que você controla. Você define políticas, não prompts. O modelo opera dentro da sua infraestrutura da mesma forma que um servidor web opera dentro das regras do nginx. Você não senta no nginx e digita requisições. Você configura, implanta e monitora.

A distinção importa porque infraestrutura tem efeito cumulativo. Um hook que bloqueia credenciais em comandos bash protege cada sessão, cada agente, cada execução autônoma. Uma skill que codifica sua rubrica de avaliação de blog se aplica consistentemente, seja você quem a invoca ou um agente. Um agente que revisa código por segurança executa as mesmas verificações esteja você assistindo ou não.

Simon Willison enquadra o momento atual em torno de uma única observação: escrever código agora é barato.³ Correto. Mas o corolário que ninguém quer ouvir é que a verificação agora é a parte cara. Código barato sem infraestrutura de verificação produz bugs em escala. O investimento que compensa não é um prompt melhor. É o sistema ao redor do modelo que captura o que o modelo deixa escapar.

A Camada de Infraestrutura

O sistema de hooks do Claude Code dispara comandos shell em 17 eventos de ciclo de vida.² PreToolUse dispara antes de uma ferramenta executar e pode bloqueá-la. PostToolUse dispara depois e pode fornecer feedback. UserPromptSubmit dispara quando você digita e pode injetar contexto. Stop dispara quando o modelo tenta finalizar e pode forçá-lo a continuar. Cada evento recebe JSON via stdin com contexto completo: ID da sessão, nome da ferramenta, entrada da ferramenta, diretório de trabalho atual.

O sistema de hooks não é um sistema de plugins. É uma arquitetura orientada a eventos. A diferença: plugins estendem os recursos de uma ferramenta. Eventos permitem que você intercepte, modifique e controle cada ação que a ferramenta executa. Você se torna o middleware.

Hooks: A Camada Determinística

Hooks são scripts shell. Não podem ser alucinados, contornados por persuasão ou burlados por injeção de prompt. O modelo quer executar rm -rf /? Um script bash de 10 linhas verifica o comando contra uma lista de bloqueio e o rejeita antes que o shell sequer o veja. O modelo tenta ler .env? Um regex no caminho do arquivo intercepta a chamada do Read. Nada disso exige cooperação do modelo. O hook dispara independentemente da vontade do modelo.

Eu executo 84 hooks em 17 tipos de evento. A distribuição conta uma história: 35 impõem julgamento (portões, guardas, validadores) e 49 cuidam de automação (injetores, loggers, rastreadores). Essa proporção começou em 1:6. Dois meses de coisas quebrando em execuções autônomas a empurraram para 4:5. Cada hook de julgamento existe porque algo falhou sem ele. Um agente fez commit de código com comentários TODO. Um agente executou um comando git destrutivo. Um agente vazou um caminho de credencial em um arquivo de log. Cada falha ganhou um portão.

A maior lição: dispatchers em vez de hooks independentes. Eu tinha sete hooks todos disparando em UserPromptSubmit, cada um lendo stdin independentemente, dois escrevendo no mesmo arquivo de estado JSON. Escritas concorrentes truncaram o JSON. Cada hook downstream que parseava esse arquivo quebrou. Um dispatcher por evento executando hooks sequencialmente a partir de stdin em cache resolveu. Overhead invisível, 200ms por prompt.

Skills: A Camada de Conhecimento

Skills são conjuntos de instruções em markdown que se ativam sob demanda ou via hooks.⁴ Cada uma codifica expertise de domínio que o modelo utiliza quando invocada. Minha skill blog-evaluator define uma rubrica ponderada de 6 categorias com critérios de pontuação específicos, mínimos por categoria e interdependências. Minha skill jiro codifica um ciclo de qualidade de 7 etapas com um portão de evidências que exige provas específicas para cada critério.

Skills se compõem com hooks. Uma skill pode definir seus próprios hooks no frontmatter que se ativam apenas enquanto a skill está em execução. Skills de filosofia se auto-ativam via hooks SessionStart, injetando restrições de qualidade em cada sessão sem invocação explícita.

48 skills cobrindo: qualidade de código (jiro, testing-philosophy, debugging-philosophy), conteúdo (blog-writer-core, blog-evaluator, citation-verifier), arquitetura (fastapi, swiftui, database, htmx-alpine), operações (deploy, cache, analytics, security) e meta-orquestração (deliberation, scan-intel, ralph). Pesquisas sobre as próprias preferências do Claude Code descobriram que ele gravita em direção a certos frameworks e padrões.⁹ Skills permitem que você substitua esses padrões pelos seus.

Agentes: A Camada de Delegação

Agentes são subagentes especializados com janelas de contexto isoladas.⁵ Cada um recebe uma tarefa focada e contexto limpo. Meu sistema de revisão de código dispara três agentes em paralelo: corretude, segurança e convenções. Cada um revisa independentemente. Discordâncias entre revisores revelam exatamente os problemas que um único revisor deixaria passar.

A restrição crítica: um guardião de recursão. Um script shell dispara antes de cada chamada da ferramenta Task, verifica um contador de profundidade de spawn em um arquivo de estado compartilhado e bloqueia a chamada se a profundidade exceder um limite. Sem isso, agentes delegam para agentes que delegam para agentes, cada um perdendo contexto e queimando tokens. O limite padrão é 3 níveis. Na prática, trabalho útil acontece na profundidade 1 (agente principal mais um subagente). Qualquer coisa mais profunda que 2 geralmente significa que a decomposição da tarefa estava errada.

19 agentes abrangendo: desenvolvimento (ios-developer, backend-architect), revisão (code-reviewer, security-reviewer, conventions-reviewer, yagni-reviewer), exploração (project-scout, code-explorer, code-architect) e validação (test-runner, correctness-reviewer).

Remote Control Muda a Equação

Em 25 de fevereiro de 2026, a Anthropic lançou o Remote Control: a capacidade de conectar a uma sessão local do Claude Code a partir de qualquer navegador ou do aplicativo móvel Claude.⁶ O recurso recebeu 531 pontos e 313 comentários no Hacker News, a maioria reclamações sobre bugs. As reclamações são válidas. O recurso ainda é transformador.

Eis o porquê. Antes do Remote Control, a infraestrutura que descrevi tinha dois modos: supervisionado (eu observo o terminal) ou não supervisionado (eu saio e torço). Nenhum é ideal. Supervisionado limita o throughput à minha capacidade de atenção. Não supervisionado arrisca o modelo tomar decisões ruins que ninguém detecta.

Remote Control cria um terceiro modo: governança assíncrona. Eu executo loops autônomos que processam PRDs com múltiplas histórias durante a noite. Os prompts de aprovação para ações externas (git push, chamadas API, qualquer coisa que saia da máquina) são encaminhados para meu celular. Eu aprovo, rejeito ou redireciono de qualquer lugar. A camada de governança permanece a mesma. A latência entre “agente precisa de aprovação” e “humano fornece” cai de “quando eu checar meu laptop” para “10 segundos do meu celular.”

O fluxo de aprovação se potencializa com a classificação de raio de impacto dos meus hooks. Operações locais (escrita de arquivos, execução de testes) são auto-aprovadas. Operações compartilhadas (git commits) alertam. Operações externas (pushes, chamadas API, deploys) são deferidas para revisão humana. Remote Control transforma esse caminho de “deferir” de uma espera bloqueante em uma notificação assíncrona. O agente continua trabalhando na próxima história enquanto eu reviso a anterior.

Ferramentas como Agent Multiplexer já gerenciam sessões do Claude Code via tmux.¹⁰ Alternativas open-source como Emdash fornecem ambientes completos de desenvolvimento agêntico.¹¹ As pessoas sugerindo SSH mais tmux como alternativa estão corretas de que funciona para acesso ao terminal. Nenhuma delas oferece o roteamento de aprovação. Esse roteamento é o que torna a operação desassistida segura, não apenas possível.

Custo como Arquitetura

O post “Tornando MCP Mais Barato via CLI” (304 pontos no HN) documentou um padrão: encapsular chamadas de ferramentas MCP em invocações CLI para evitar o overhead de manter uma conexão de servidor MCP.⁷ A percepção mais ampla é que custo é uma decisão arquitetural, não uma reflexão operacional tardia.

Minha infraestrutura lida com custo em três níveis:

Nível de tokens. Compressão do system prompt. Eu executo ~3.500 tokens de system prompt em um arquivo CLAUDE.md e 8 arquivos de regras. Os cortes de alto retorno: remover exemplos de código tutorial (o modelo conhece as APIs), consolidar regras duplicadas entre arquivos e substituir explicações por restrições. “Rejeite chamadas de ferramenta que correspondam a caminhos sensíveis” faz o mesmo trabalho que uma explicação de 15 linhas sobre por que credenciais não devem ser lidas. Densidade semântica em vez de compressão bruta.⁸

Nível de agente. Spawns limpos em vez de conversas longas. Cada história em uma execução autônoma ganha um novo agente com janela de contexto limpa. No momento do spawn, o agente recebe um briefing: estado atual do git, o que agentes anteriores realizaram, o que precisa fazer. Briefing em vez de memória. Modelos executam um briefing claro melhor do que navegam 30 etapas de contexto acumulado. O contexto nunca infla porque cada agente começa do zero. Geoffrey Huntley documentou um padrão semelhante no “The Ralph Loop,” executando desenvolvimento autônomo a $10,42/hora com Sonnet.¹³ Orquestradores multi-agente como OpenSwarm formalizam o pipeline trabalhador-revisor com escalação de modelo.¹⁴

Nível de arquitetura. CLI primeiro em vez de MCP quando a operação é stateless. Uma chamada claude --print para uma avaliação one-shot custa menos e não adiciona overhead de conexão. Um servidor MCP faz sentido quando a ferramenta precisa de estado persistente ou streaming. Context Mode demonstrou o inverso: comprimir 315 KB de saída MCP para 5,4 KB usando indexação FTS5 com ranqueamento BM25.¹² Ambas as abordagens reduzem gasto de tokens, a partir de direções diferentes. A maioria das minhas invocações de skill são one-shot. Minha análise de cache de prompts descobriu que a CLI do Claude Code cacheia system prompts por padrão acima de 4.096 tokens. Zero configuração necessária.

Estudo de Caso: Como 84 Hooks Funcionam na Prática

Um rastreamento concreto de sessão de uma execução autônoma na semana passada, processando um PRD com 5 histórias:

1. SessionStart dispara. O dispatcher injeta: data atual, detecção de projeto, restrições de filosofia, verificação de desempenho do sistema, inicialização de rastreamento de custo. Cinco hooks, 180ms no total.

2. O agente lê o PRD, planeja a primeira história. UserPromptSubmit dispara no prompt interno. O dispatcher injeta: contexto do projeto ativo, baseline de desvio de sessão (embedding Model2Vec do primeiro prompt para verificações de similaridade posteriores). 120ms.

3. O agente chama Bash para executar testes. PreToolUse:Bash dispara. O dispatcher executa: verificação de credenciais (sem caminhos .env no comando), validação de sandbox (comando não está na lista de bloqueio), detecção de projeto. 90ms. O teste executa. PostToolUse:Bash dispara: heartbeat de atividade registrado, verificação de desvio contra baseline (similaridade cosseno 0,63, bem acima do limiar de 0,30).

4. O agente chama Write para criar um arquivo. PreToolUse:Write dispara: verificação de escopo de arquivo (este caminho está dentro do diretório do projeto?). PostToolUse:Write dispara: verificação de lint no arquivo escrito, rastreamento de commit, heartbeat de atividade.

5. O agente finaliza a história. Stop dispara. O hook de portão de qualidade verifica: o agente citou evidências para cada critério? Usou linguagem evasiva (“deveria”, “provavelmente”)? Há comentários TODO no diff? Se qualquer verificação falhar, o hook retorna exit 2 e o agente continua trabalhando.

6. Verificação independente: um agente novo executa a suíte de testes sem confiar no auto-relato do agente anterior.

7. Três agentes de revisão de código são disparados em paralelo. Cada um revisa o diff independentemente. As descobertas são mescladas. Se qualquer revisor sinalizar um problema CRÍTICO, a história volta para a fila.

8. A história passa. A próxima história carrega. O ciclo se repete para todas as 5 histórias.

Total de hooks disparados em 5 histórias: ~340. Tempo total em hooks: ~12 segundos. Overhead invisível que preveniu três vazamentos de credenciais, um comando destrutivo e duas implementações incompletas em uma única execução noturna.

Principais Conclusões

Claude Code é um runtime, não uma ferramenta. Os 17 eventos de ciclo de vida o tornam programável. Hooks, skills e agentes são o conjunto de instruções. O modelo é o motor de execução. Você é o arquiteto de sistemas.

Governança escala com automação. Cada hook que adiciona uma restrição reduz o risco de operação desassistida. A proporção de hooks de julgamento para hooks de automação é sua margem de segurança. A minha é 4:5 e crescendo.

Infraestrutura tem efeito cumulativo, prompts não. Um bom prompt melhora uma interação. Um bom hook melhora toda interação. Uma boa skill melhora cada agente que a invoca. Um bom agente melhora cada workflow que delega para ele. Invista na camada que multiplica.

Remote Control torna a infraestrutura portátil. O roteamento de aprovação transforma “não supervisionado” em “supervisionado assincronamente.” Essa distinção é a diferença entre esperar que o modelo tome boas decisões e verificar que ele toma.

Custo é arquitetura, não otimização. Spawns de agentes limpos, invocações CLI primeiro, compressão de system prompt e cache de prompts são decisões estruturais que se acumulam. Otimizar depois custa mais do que projetar para isso.

Zero frameworks necessários. 84 hooks, 48 skills, 19 agentes, ~15.000 linhas de orquestração. Scripts bash em um diretório. Arquivos de estado JSON. Sem dependências de runtime. Você pode adotar um hook ou a pilha inteira. A infraestrutura cresce organicamente a partir da resolução de problemas reais, não da implementação do framework de outra pessoa.

Este artigo faz parte da série AI Engineering. Anteriormente: Why My AI Agent Has a Quality Philosophy. Veja também: Thinking With Ten Brains e The Blind Judge.