git-guardrails-claude-code

Visão geral da skill git-guardrails-claude-code

A skill git-guardrails-claude-code ajuda o Claude Code a recusar uma pequena lista de comandos Git destrutivos antes que eles sejam executados. Na prática, a função dela é simples: adicionar uma camada de segurança para que uma sessão de coding com IA não faça, de forma descuidada, git push, git reset --hard, git clean -f, exclua branches com git branch -D ou apague mudanças da working tree com git checkout . ou git restore ..

Quem deve usar git-guardrails-claude-code

Esta skill é mais indicada para quem:

• usa Claude Code diretamente em repositórios reais
• quer ajuda de IA, mas não quer que ela execute ações Git irreversíveis
• trabalha em repos compartilhados, repositórios de produção ou codebases de clientes
• prefere enforcement local em vez de depender de prompts do tipo “tome cuidado”

Se sua principal preocupação é destruição acidental de código ou pushes não autorizados durante uma sessão com agente, git-guardrails-claude-code é uma ótima escolha.

O que diferencia esta skill de um prompt comum

Um prompt comum pode pedir ao Claude que não execute comandos arriscados, mas prompts são apenas orientação leve. git-guardrails-claude-code usa um hook PreToolUse, então a restrição passa a fazer parte do caminho de execução do Claude Code, e não fica só na conversa. Esse é o principal diferencial e o principal motivo para instalar a skill.

O que ela realmente bloqueia

O script shell incluído verifica os comandos Bash recebidos e bloqueia padrões como:

• git push
• git reset --hard
• git clean -f
• git clean -fd
• git branch -D
• git checkout .
• git restore .
• correspondências relacionadas a force-push, como push --force

A mensagem de bloqueio informa ao Claude que ele não tem autoridade para usar aquele comando.

O que esta skill não faz

git-guardrails-claude-code não é um mecanismo completo de políticas Git. Ela não:

• avalia a qualidade de commits
• exige aprovações
• diferencia destinos de push seguros e inseguros
• entende regras de branching específicas do repositório
• protege comandos fora dos padrões listados, a menos que você edite o script

Isso importa na adoção: trata-se de um guardrail focado, não de uma governança abrangente.

Como usar a skill git-guardrails-claude-code

Comece decidindo o escopo

A primeira escolha prática na skill upstream é se você vai instalar o guardrail:

• só neste projeto em .claude/settings.json, ou
• em todos os projetos em ~/.claude/settings.json

Essa decisão muda onde você copia o script e até onde o bloqueio vai valer. Para a maioria das equipes, instalar no nível do projeto é mais seguro para testar. A instalação global faz sentido quando você já sabe que quer as mesmas restrições Git em todo lugar.

Leia estes arquivos primeiro

Você consegue entender quase tudo que importa lendo:

1. SKILL.md
2. scripts/block-dangerous-git.sh

Essa ordem de leitura é útil porque SKILL.md explica como o hook é ligado, enquanto scripts/block-dangerous-git.sh mostra os padrões de comando bloqueados de fato. Se você se preocupa com falsos positivos ou lacunas, o script importa mais do que o texto descritivo.

Contexto de instalação da git-guardrails-claude-code

O processo de git-guardrails-claude-code install é, em grande parte, uma configuração manual dentro do sistema de hooks do Claude Code:

1. copiar o script shell para um diretório de hooks
2. torná-lo executável
3. registrá-lo em PreToolUse para o matcher Bash

O caminho do repositório para o script de origem é:

scripts/block-dangerous-git.sh

Os destinos são:

• escopo de projeto: .claude/hooks/block-dangerous-git.sh
• escopo global: ~/.claude/hooks/block-dangerous-git.sh

Depois, torne-o executável:

chmod +x .claude/hooks/block-dangerous-git.sh

ou, no escopo global:

chmod +x ~/.claude/hooks/block-dangerous-git.sh

Adicione o hook do Claude Code corretamente

No escopo de projeto, a skill mostra um hook PreToolUse em .claude/settings.json que executa o script copiado usando "$CLAUDE_PROJECT_DIR".

Os pontos principais da configuração são:

• evento do hook: PreToolUse
• matcher: Bash
• tipo de hook: command
• comando: caminho para block-dangerous-git.sh

Se esse hook não estiver registrado em PreToolUse, o script vai existir, mas nunca vai interceptar comandos.

Como a skill git-guardrails-claude-code funciona na prática

O script shell lê a entrada da tool a partir da entrada padrão, extrai .tool_input.command com jq e verifica o comando contra um pequeno array de padrões perigosos usando grep -qE.

Isso significa que os obstáculos de adoção são bem objetivos:

• jq precisa estar disponível no ambiente
• o caminho do comando em settings precisa ser válido
• o script precisa estar executável
• o Claude Code precisa realmente passar chamadas da tool Bash pelo sistema de hooks

Se qualquer uma dessas peças falhar, a proteção fica mais fraca do que você imagina — e pode enfraquecer sem chamar atenção.

Que informações a skill precisa de você

A skill upstream em si exige pouco contexto, mas um bom fluxo de git-guardrails-claude-code usage começa com estas decisões:

• projeto apenas ou global
• se a lista padrão de bloqueios é suficiente
• se sua equipe também quer bloquear comandos extras, como git tag -d, git rebase --abort ou pushes específicos para certos remotes
• se os usuários ainda precisam de um caminho manual de escalonamento para pushes legítimos

Sem essas respostas, a instalação é fácil, mas o encaixe com a política real pode ser ruim.

Como transformar um objetivo vago em um prompt forte

Prompt fraco:

• “Set up git guardrails.”

Prompt mais forte:

• “Install git-guardrails-claude-code for this project only. Copy the hook script into .claude/hooks/, make it executable, update .claude/settings.json with a PreToolUse hook for Bash, and then show me the exact blocked Git patterns from the script.”

Por que isso é melhor:

• define o escopo
• especifica o destino
• pede tanto a configuração quanto a verificação
• reduz a chance de o Claude improvisar uma estrutura de hook diferente

Um bom fluxo para a primeira execução

Um git-guardrails-claude-code guide prático fica assim:

1. escolher entre escopo de projeto e global
2. inspecionar scripts/block-dangerous-git.sh
3. copiar o script para o diretório de hooks de destino
4. rodar chmod +x no arquivo copiado
5. ligar o hook PreToolUse no arquivo de settings correto
6. testar com uma simulação inofensiva ou com um comando claramente bloqueado em um repo seguro
7. decidir se vale personalizar os padrões

Essa ordem importa porque permite verificar a lista real de enforcement antes de aplicar a mudança em larga escala.

Como validar a instalação

Não pare em “o arquivo existe”. Valide o comportamento:

• confirme que o caminho do arquivo de settings é o que o Claude Code está usando
• confirme que o comando do hook aponta para o script copiado, e não para o caminho de origem no repositório
• dispare um padrão bloqueado em um repo descartável
• verifique se o Claude recebe uma recusa em vez de executar o comando

Nesta skill, validar o comportamento é mais importante do que validar visualmente.

Melhor encaixe em workflows Git

git-guardrails-claude-code for Git Workflows é especialmente útil quando seu workflow preferido com IA é:

• deixar o Claude editar arquivos livremente
• deixar o Claude inspecionar diffs e status
• manter exclusão de branch, force push, hard reset e comandos de limpeza sob controle humano explícito

Essa divisão funciona bem porque preserva a produtividade da IA nas tarefas de código, enquanto mantém ações irreversíveis no repositório sob controle manual.

Quando personalizar o script

A lista padrão é propositalmente enxuta. Personalize scripts/block-dangerous-git.sh se:

• sua equipe considera git push aceitável, mas quer bloquear apenas --force
• você também quer bloquear git commit --amend
• seu workflow inclui padrões sensíveis de exclusão de branch
• você quer regras diferentes por repositório

O principal tradeoff aqui é simplicidade versus precisão. O script padrão é fácil de auditar; um script muito personalizado exige mais testes.

FAQ da skill git-guardrails-claude-code

A git-guardrails-claude-code é boa para iniciantes?

Sim, desde que o iniciante já esteja usando Claude Code e queira um padrão mais seguro em torno de Git. A configuração é curta, e o conceito é fácil de entender: interceptar chamadas da tool Bash antes da execução. As únicas partes um pouco mais técnicas são a configuração do hook em JSON e as permissões do script shell.

Isso é melhor do que dizer ao Claude “never push”?

Sim, para os comandos específicos que a skill cobre. git-guardrails-claude-code transforma uma regra conversacional em uma verificação no momento da execução. Isso a torna muito mais confiável do que depender apenas da memória do prompt.

A git-guardrails-claude-code bloqueia todos os comandos Git perigosos?

Não. Ela bloqueia os padrões explícitos do script. Se o seu modelo de risco inclui outros comandos, você precisa adicioná-los manualmente. Esse é um limite central da skill.

Posso usar git-guardrails-claude-code globalmente?

Sim. A skill oferece suporte explícito para instalação global via ~/.claude/settings.json e ~/.claude/hooks/block-dangerous-git.sh. A instalação global é conveniente, mas a instalação por projeto é mais fácil de testar e mais segura quando repos diferentes precisam de políticas diferentes.

Isso atrapalha o trabalho normal de coding?

Em geral, pouco — desde que o seu workflow normal não espere que o Claude faça push nem execute limpeza destrutiva em Git. A skill é mais compatível com um fluxo em que o Claude edita código, roda testes e prepara mudanças, enquanto um humano mantém a autoridade final sobre Git.

Quando eu não deveria usar esta skill?

Evite git-guardrails-claude-code se:

• você realmente quer que o Claude gerencie Git de ponta a ponta
• sua equipe precisa de allowlists mais refinadas, e não de bloqueios simples por padrão
• você não pode contar com hooks shell ou com jq
• você precisa de enforcement em nível organizacional, além da configuração local do Claude Code

Nesses casos, a skill pode parecer limitada demais ou local demais.

Como melhorar a skill git-guardrails-claude-code

Audite os padrões bloqueados com base nos seus riscos reais

A forma mais rápida de melhorar git-guardrails-claude-code é comparar a lista padrão de padrões com os erros de Git que realmente preocupam sua equipe. Muitas equipes se preocupam menos com todo e qualquer push e mais com:

• force pushes
• exclusão de branch em branches protegidas
• limpezas destrutivas em monorepos
• resets da working tree durante debugging

Se sua política for diferente, edite o array de padrões em vez de aceitar o padrão no automático.

Dê instruções de instalação mais fortes ao Claude

Se você pedir ao Claude para aplicar esta skill, inclua detalhes concretos:

• escopo
• caminho exato de destino
• se deve preservar ou mesclar hooks existentes
• se deve imprimir o arquivo JSON final para revisão
• se deve testar o hook depois da configuração

Um pedido melhor seria:

• “Install git-guardrails-claude-code only in this repo, merge with any existing .claude/settings.json hooks instead of overwriting them, and show the final settings diff.”

Isso evita um dos modos de falha mais comuns: substituir a configuração de hooks já existente.

Fique atento a erros ao mesclar hooks

Um problema realista não está no script shell, e sim na atualização do arquivo de settings. Se um repositório já tiver hooks configurados, uma instalação descuidada pode sobrescrevê-los. Peça:

• um diff, não uma reescrita cega
• preservação das entradas existentes de PreToolUse
• explicação da ordem dos hooks se vários comandos forem executados

Para muitos usuários, isso importa mais do que a lista de comandos bloqueados.

Teste falsos positivos e formas de contorno

Como o script usa pattern matching, você deveria testar:

• comandos legítimos que devem passar
• comandos bloqueados que devem falhar
• variações que você presume estarem bloqueadas, mas talvez não estejam
• strings de comando que contenham texto parecido de formas inesperadas

Esse é o ponto certo para aumentar a confiança em git-guardrails-claude-code usage, especialmente antes de um rollout global.

Aperte o script só depois de ver falhas reais

É tentador sair adicionando muitos padrões de imediato. Resista a isso, a menos que tenha evidência. Uma blocklist curta e legível é mais fácil de confiar e manter. Expanda-a depois de observar:

• comandos que o Claude tenta com frequência
• comandos que os usuários consideram arriscados
• padrões que passaram sem bloqueio
• comandos que foram bloqueados, mas não deveriam ter sido

Isso mantém o guardrail compreensível.

Crie um caminho de escalonamento humano

Uma boa melhoria operacional é combinar o guardrail com uma regra clara, como:

• o Claude pode preparar commits e explicar os passos de push
• um humano executa manualmente o push final ou a limpeza destrutiva

Isso melhora a skill porque os usuários param de brigar com o guardrail e passam a desenhar o processo em torno dele.

Reavalie se o escopo global ou por projeto ainda faz sentido

Depois do uso inicial, reavalie o escopo:

• se a regra funciona em todos os repos, mova para global
• se alguns repos precisam de um comportamento Git mais flexível, mantenha local ao projeto
• se as equipes variam, mantenha versões separadas do script por projeto

Essa é uma das maneiras mais simples de melhorar o encaixe sem alterar código.

Mantenha o script legível

Se você personalizar git-guardrails-claude-code, mantenha o script shell fácil de auditar. Prefira uma lista clara de padrões e um único caminho de erro em vez de lógica engenhosa demais. Em um controle de segurança, legibilidade também faz parte da confiabilidade.