How to wire Claude Code into your real terminal, editor, and CI workflow using genuine primitives that hold up in production
Pense nas superfícies de integração do Claude Code como três canais diferentes que você sintoniza dependendo do que está fazendo. Cada canal acessa o mesmo modelo subjacente, mas de um ponto de vista diferente com affordances distintas.
Terminal é o canal universal. Funciona em qualquer lugar onde há um shell — sessões SSH, scripts de CI, containers Docker, splits do tmux. Você envia dados por pipe, o Claude Code raciocina sobre eles e você obtém a saída. Sem nada sofisticado, mas compõe com toda ferramenta Unix que você já conhece.
Ambiente do editor é o canal contextual. Quando o Claude Code roda no terminal integrado do VS Code, ele detecta as variáveis de ambiente VSCODE_ e ganha consciência do arquivo aberto, dos diagnósticos existentes, do diff em revisão. O mesmo binário claude obtém contexto mais rico sem configuração adicional além de uma variável de ambiente.
Hooks é o canal de automação. Hooks são scripts executáveis que rodam em pontos específicos do ciclo de vida do Claude Code — antes de uma ferramenta executar, depois que ela completa, quando uma sessão termina. Eles permitem adicionar portões de segurança, logging e notificações sem modificar nenhum fluxo de trabalho manualmente.
O insight da composição: Você não está escolhendo uma superfície de integração. O terminal lida com composabilidade e automação. A integração com o editor cuida das sessões de desenvolvimento ativo. Os hooks aplicam políticas que devem ser cumpridas em todas as sessões do Claude Code em todos os projetos.
Este módulo cobre as primitivas reais de cada superfície e depois mostra como conectá-las — o padrão que uso em meu harness SDLC agentic e no desenvolvimento do dia a dia.
O pacote é @anthropic-ai/claude-code — note o escopo anthropic-ai, não anthropic:
Erro comum: Buscar no npm por @anthropic/claude-code (sem o -ai) não encontra nada. O escopo correto é @anthropic-ai.
A primitiva mais componível é o modo pipe com -p. Você alimenta o Claude Code com um stream, ele raciocina sobre ele, e a saída vai para onde você redirecionar:
A flag -p mantém o Claude Code não-interativo: lê do stdin, imprime no stdout, encerra. Isso o torna seguro dentro de scripts e pipelines de CI — não vai pausar esperando input do teclado.
Além do modo pipe, o Claude Code aceita prompts em linguagem natural diretamente. Os padrões que uso diariamente:
Quando você inicia o Claude Code a partir do terminal integrado do VS Code, ele detecta as variáveis de ambiente VSCODE_ e pode exibir mudanças propostas como visualizações de diff. Uma variável desbloqueia isso:
Com CLAUDE_EDITOR=code, o Claude Code abre edições propostas diretamente no visualizador de diff do VS Code, em vez de imprimi-las no terminal.
Antes de conectar tudo, raciocine sobre:
claude "pergunta" e echo "dados" | claude -p "pergunta"?-p importa especificamente para pipelines de CI?CLAUDE_EDITOR não estiver definido, como o Claude Code mostrará mudanças de arquivo propostas?Se você está confiante nas três respostas, a próxima seção vai fazer sentido imediatamente.
O modo pipe compõe naturalmente com scripts shell. Aqui está um script que uso para triagem de PRs gerados por agentes antes de revisá-los manualmente:
Padrão: Reunir contexto com primitivas shell, alimentar o Claude Code em um pipe, capturar o código de saída. Este é o padrão completo de integração com CI.
Hooks são scripts shell ou programas registrados em ~/.claude/settings.yaml. Eles se acoplam a seis eventos do ciclo de vida:
| Hook | Quando Dispara |
|---|---|
pre-prompt | Antes do prompt ser processado |
pre-tool-use | Antes de qualquer ferramenta executar |
post-tool-use | Após uma ferramenta completar |
notification | Quando o Claude Code precisa de input do usuário |
stop | Quando a sessão termina |
pre-compact | Antes da compactação de contexto |
Hooks recebem dados de evento como JSON no stdin. Sair com 0 permite; sair com valor não-zero bloqueia (para pre-tool-use).
Este é o hook pre-tool-use que uso em meu harness SDLC para bloquear comandos destrutivos incontroláveis:
Registrar e testar:
O hook stop dispara quando uma sessão termina. Uso-o para escrever um resumo JSON de cada sessão do Claude Code em um log diário — útil para auditar o que o harness SDLC rodou enquanto eu estava longe do computador:
Por que JSONL? Arquivos JSON Lines append-only significam que sessões concorrentes não corrompem o log. Transmita as entradas do dia com cat ~/.claude/logs/$(date +%Y-%m-%d).jsonl | jq .
O hook pre-tool-use roda de forma síncrona — cada chamada de ferramenta bloqueia enquanto o hook executa. Um hook lento (digamos, um que chama uma API externa para validar um comando) torna cada sessão do Claude Code mais lenta.
Reflita sobre esse trade-off antes de continuar: Se você quer tanto um portão de segurança quanto chamadas de observabilidade para um dashboard de monitoramento, como você dividiria o trabalho entre pre-tool-use e post-tool-use? Que garantia de latência isso oferece, e que lacuna de observabilidade isso cria?
Não há uma única resposta certa, mas raciocinar antes de construir é como você evita descobrir a resposta errada em produção.
1. Você roda: git diff --staged | claude -p 'escreva uma mensagem de commit'. O que o Claude Code faz?
Correct Answer: B
A flag -p habilita o modo pipe não-interativo: o Claude Code lê do stdin, processa com o modelo, escreve no stdout e encerra. Nenhum input do teclado é necessário, tornando-o seguro para scripts e pipelines de CI.
2. Um hook pre-tool-use encerra com código 2. O que o Claude Code faz?
Correct Answer: C
Qualquer código de saída não-zero de um hook pre-tool-use bloqueia a ferramenta de executar. Código 1, 2 ou qualquer outro valor não-zero têm o mesmo efeito: bloquear.
3. Você quer que o Claude Code abra edições de arquivo propostas no visualizador de diff do VS Code. Qual configuração está correta?
Correct Answer: B
Definir CLAUDE_EDITOR=code no ambiente do shell instrui o Claude Code a abrir diffs no VS Code. Adicione ao perfil do shell para persistir entre sessões.
4. Você instalou @anthropic/claude-code via npm e falhou. O que deu errado?
Correct Answer: B
O pacote npm correto é @anthropic-ai/claude-code (com -ai no escopo). @anthropic/claude-code não existe no npm e falhará com 'package not found'.
5. Qual hook dispara quando você quer adicionar um resumo a um log de auditoria após o Claude Code terminar uma sessão?
Correct Answer: D
O hook stop dispara quando a sessão do Claude Code termina, tornando-o o lugar certo para resumos no nível de sessão, tarefas de limpeza e escritas de log de auditoria.
6. Um hook pre-tool-use chama uma API externa para validar cada comando. Qual é a consequência mais provável em produção?
Correct Answer: B
Hooks rodam de forma síncrona. Um hook pre-tool-use que chama uma API lenta atrasa cada chamada de ferramenta pela duração dessa chamada. Mantenha hooks pre-tool-use rápidos — valide localmente ou use um cache sub-millisegundo.
7. Você quer adicionar contexto do projeto a cada prompt do Claude Code automaticamente. Qual hook está correto?
Correct Answer: B
O hook pre-prompt dispara antes de cada prompt ser processado, dando a você um lugar para injetar contexto como seções do README do projeto, branch git atual ou convenções da equipe que o Claude Code deve sempre ter.