Hooks de Setup do Claude Code

A qualidade de uma equipa de engenharia revela-se num número: quanto tempo demora um novo membro a fazer o projeto correr na sua máquina.

As boas equipas precisam de um link, um doc, alguns comandos. A maioria das equipas perde um dia ou dois em pair programming, threads no Slack, páginas de wiki esquecidas, e trocas de mensagens sobre por que algo partiu.

Os agentes tornam isto solucionável.

Preparar uma codebase sempre foi uma escolha entre três formas problemáticas:

Scripts puros são previsíveis mas frágeis. Correm os mesmos comandos sempre e param logo que a realidade muda. Uma dependência em falta ou uma base de dados fora do ar, e o script morre.

Agentes puros são inteligentes mas pouco fiáveis. Não dás um ao pipeline de CI/CD e esperas o mesmo output em cada execução.

Documentação pura é flexível mas depende de humanos. Ninguém a lê, e fica desatualizada em poucas semanas.

O que funciona é entrançar os três. Scripts tratam da execução. Agentes supervisionam. Acabas com um documento vivo que se executa.

Os hooks de setup chegaram ao Claude Code a 25 de janeiro de 2026. São um tipo dedicado de hook que dispara antes de a sessão arrancar. Quando corres:

claude --init

O hook de setup vai primeiro, depois o Claude arranca. O hook pode instalar pacotes, popular a base de dados, e preparar o teu ambiente. Quando o Claude inicia, já sabe o que aconteceu.

É aqui que as coisas ficam interessantes. Podes juntar um prompt ao flag init:

claude --init "/install"

Agora o hook corre, e o comando /install dispara logo a seguir. O agente lê os ficheiros de log, percebe o que aconteceu, e reporta em linguagem simples.

claude --init "/install true"

Três modos resultam disto:

┌─────────────────────────────────────────────────────────┐
│  DETERMINÍSTICO        AGÊNTICO           INTERATIVO    │
│  (só hooks)            (hooks + prompt)   (hooks + Qs)  │
│                                                         │
│  claude --init          /install          /install true │
│                                                         │
│  - Rápido               - Supervisionado  - Faz perguntas│
│  - Previsível           - Diagnóstico     - Adapta-se   │
│  - CI-friendly          - Reporta status  - Context-    │
│                                             aware       │
└─────────────────────────────────────────────────────────┘

Modo determinístico: Só o script. Rápido, repetível, perfeito para CI/CD onde cada execução tem de ser igual.

Modo agêntico: Script primeiro, depois um agente lê os resultados. Examina ficheiros de log, faz parse de erros, e diz em linguagem simples o que correu bem ou mal.

Modo interativo: Script primeiro, depois o agente puxa-te para um Q&A rápido. "Base de dados nova ou manter a antiga? Instalação completa ou mínima? Queres que eu verifique os pré-requisitos primeiro?"

O script é sempre a fonte da verdade. Hooks e prompts chamam o mesmo script sempre. O que muda é se um agente supervisiona, e se faz perguntas antes.

Just é um pequeno command runner, e combina bem com hooks de setup. Trata-o como um lançador para o teu trabalho de engenharia. Em vez de memorizar flags, escreves just e vês todos os comandos disponíveis:

just          # Ver todos os comandos
just cldi     # Setup determinístico
just cldii    # Setup agêntico (com reporting)
just cldit    # Setup interativo (faz perguntas)

O próprio justfile mantém-se simples:

# Deterministic codebase setup
cldi:
  claude --init
 
# Agentic codebase setup
cldii:
  claude --init "/install"
 
# Interactive setup (asks questions)
cldit:
  claude --init "/install true"
 
# Deterministic maintenance
cldm:
  claude --maintenance
 
# Agentic maintenance (with reporting)
cldmm:
  claude --maintenance "/maintenance"

Colegas de equipa e agentes nunca têm de memorizar flags duas vezes. Correm just cldii e as coisas funcionam.

--init-only é o flag para pipelines. Corre o hook, devolve um exit code, e fecha. Sem sessão interativa.

O onboarding é onde isto brilha. Um novo engenheiro escreve just cldit e o agente guia-o:

Agent: How should I handle the database?

┌─ Database Setup ─────────────────────────────────┐
│  ○ Fresh database (Recommended)                  │
│  ○ Keep existing                                 │
│  ○ Skip database setup                           │
└──────────────────────────────────────────────────┘

O agente pergunta sobre o modo de instalação, variáveis de ambiente, e se deve verificar os pré-requisitos primeiro. Adapta-se às respostas e corre apenas os passos que fazem sentido.

Scripts não conseguem fazer isto. Tocam sempre a mesma fita. Agentes conseguem parar a meio, fazer uma pergunta de esclarecimento, e ramificar com base na resposta.

Os hooks de setup são um dos 12 eventos do ciclo de vida no sistema de hooks. A configuração fica em .claude/settings.json:

{
  "hooks": {
    "Setup": [
      {
        "matcher": "init",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_init.py",
            "timeout": 120
          }
        ]
      },
      {
        "matcher": "maintenance",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_maintenance.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

O script do hook corre os teus comandos e regista tudo:

def main():
    # Install backend dependencies
    run(["uv", "sync"], cwd="apps/backend")
 
    # Install frontend dependencies
    run(["npm", "install"], cwd="apps/frontend")
 
    # Initialize database
    run(["uv", "run", "python", "init_db.py"], cwd="apps/backend")
 
    # Tell Claude what happened
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "Setup",
            "additionalContext": "Setup complete. Run 'just be' and 'just fe' to start."
        }
    }))

O slash command /install pega no log e escreve um resumo dos resultados:

---
description: Run setup and report installation results
---
 
## Workflow
 
1. Run /prime to understand the codebase
2. Read the log file at .claude/hooks/setup.init.log
3. Analyze for successes and failures
4. Write results to app_docs/install_results.md
5. Report to user

Quando algo parte, o agente já tem o contexto para diagnosticar. Lista os modos de falha habituais dentro do prompt, e o agente percorre o playbook de correção sozinho.

Pensa no tempo de onboarding face ao ritmo a que queres que a equipa cresça. Consegue um único prompt tratar do setup e instalação para um novo membro? Consegue tornar cada passo claro ao perguntar antes de agir?

Sim, em ambos os casos. Os agentes estão suficientemente bons para isto. A peça em falta é a standardização.

Determinismo preservado: O hook dispara o mesmo script sempre. Zero variância de LLM durante a execução. O agente só olha para os resultados depois do trabalho determinístico terminar.

Compatível com CI: GitHub Actions corre claude --init-only e recebe um exit code limpo.

Interativo quando importa: Novos membros são guiados no setup. Toda a gente mais usa a versão rápida.

Um documento vivo que se executa: O teu processo de instalação agora vive em linguagem natural, dentro de prompts que os agentes seguem. As atualizações acontecem ao editar o prompt.

Começa simples. Escreve um script .claude/hooks/setup_init.py que instala as tuas dependências, liga-o no .claude/settings.json, depois adiciona um comando /install que lê o log e reporta. Envolve tudo num justfile para a tua equipa correr just install e parar de pensar nisso.

Queres algo mais leve? Se só queres carregar contexto diferente por tipo de sessão, um slash command normalmente chega. Sem script de instalação necessário.

Os hooks de setup compensam mais quando queres um único comando que instala tudo, diagnostica as falhas, e guia novos engenheiros em cada passo. Scripts fornecem a certeza. Agentes fornecem o julgamento. Se a tua equipa salta entre Windows, Linux e macOS, lê os padrões de hooks multiplataforma para o mesmo setup correr em todos os sistemas operativos.