git-guardrails-claude-code

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

O que a git-guardrails-claude-code faz

A skill git-guardrails-claude-code adiciona hooks ao Claude Code que bloqueiam comandos perigosos de git antes que eles sejam executados. Ela é voltada para times ou usuários individuais que querem uma camada de imposição — e não apenas um aviso educado — para ações destrutivas como git push --force, git reset --hard, git clean -f e git branch -D.

Quem deve instalar

Use a skill git-guardrails-claude-code se você trabalha em repositórios em que perda acidental de dados, pushes indevidos ou reescrita do histórico local são riscos reais. Ela é especialmente útil quando você quer que o Claude Code opere dentro de limites mais seguros de controle de acesso e precisa que esses limites sejam aplicados de forma consistente.

O que a diferencia

Diferente de um lembrete de segurança só no prompt, esta skill instala um hook PreToolUse que interrompe o comando antes da execução. Isso significa que a proteção é operacional, não apenas consultiva. O principal trade-off é que ela protege apenas os comandos que correspondem ao padrão definido, então funciona melhor para ações de git claramente perigosas e já conhecidas do que para aplicação genérica de políticas.

Como usar a skill git-guardrails-claude-code

Instale a skill e escolha o escopo

Instale com:
npx skills add mattpocock/skills --skill git-guardrails-claude-code

A primeira decisão é o escopo: instalar só neste projeto ou em todos os projetos. O escopo de projeto é mais seguro quando você quer testar o hook primeiro em um único repo; o escopo global é melhor se o seu fluxo de trabalho precisar bloquear esses comandos em qualquer uso do Claude Code.

Leia primeiro os arquivos certos

Comece com SKILL.md para entender o fluxo de configuração e depois inspecione scripts/block-dangerous-git.sh, porque ali fica a lógica de bloqueio. Se você estiver adaptando o comportamento, o script importa mais do que a explicação textual. Esse é o caminho mais rápido para um guia prático da git-guardrails-claude-code.

Como formular um bom pedido

A skill funciona melhor quando você especifica onde ela deve agir e o que considera perigoso. Um pedido forte seria: “Instale a git-guardrails-claude-code só para este projeto e bloqueie push, reset --hard, clean -fd e branch -D.” Um pedido mais fraco, como “tornar o git mais seguro”, deixa escopo e política vagos demais para uma instalação limpa.

Verifique e personalize o hook

Depois de copiar o hook para .claude/hooks/block-dangerous-git.sh ou ~/.claude/hooks/block-dangerous-git.sh, torne-o executável e registre-o no settings.json correspondente. Em seguida, teste um comando bloqueado em um repo seguro para confirmar que o Claude recebe a mensagem de recusa. Se o seu time usar outros comandos arriscados, amplie a lista de padrões no script em vez de depender do texto do prompt.

Perguntas frequentes sobre a skill git-guardrails-claude-code

Isso substitui permissões de git?

Não. A git-guardrails-claude-code é uma proteção local do Claude Code, não um sistema de controle de acesso no servidor. Ela pode impedir que o Claude execute comandos correspondentes, mas não substitui proteção de branch, permissões de repo, regras de revisão ou políticas do remoto.

Quando ela não é uma boa escolha?

Evite-a se você precisa de automação irrestrita de git ou se seu fluxo depende legitimamente de scripts que usam comandos como git clean -fd ou git branch -D. Nesses casos, um bloqueio amplo pode gerar mais atrito do que valor, e um conjunto de regras mais específico pode ser melhor.

Ela é amigável para iniciantes?

Sim, se você consegue seguir uma sequência curta de instalação e editar JSON. O conceito é simples, mas os melhores resultados vêm de entender exatamente quais comandos você quer bloquear e onde o hook deve ficar. Iniciantes normalmente tropeçam mais na escolha do escopo do que no hook em si.

Prompt engineering comum faz a mesma coisa?

Não. Um prompt pode pedir que o Claude aja com cautela, mas não consegue impor com confiabilidade o bloqueio de comandos. A skill git-guardrails-claude-code é útil quando a decisão de interromper um comando precisa acontecer mesmo se o modelo, de outra forma, fosse obedecer.

Como melhorar a skill git-guardrails-claude-code

Refine a lista de comandos bloqueados

O maior ganho de qualidade vem de alinhar a lista ao seu perfil real de risco. Avalie se o seu time precisa bloquear só git push e git reset --hard, ou se git clean -f, git checkout . e git restore . também devem entrar no bloqueio. Entradas melhores geram menos falso positivo e menos lacunas.

Mantenha o escopo intencional

Use o escopo de projeto para testes, onboarding em repositório compartilhado ou proteção pontual em uma base de código sensível. Use o escopo global apenas quando tiver certeza de que a mesma política deve acompanhá-lo em qualquer lugar. Essa é a principal decisão que muda o sucesso de adoção da instalação da git-guardrails-claude-code.

Teste o modo de falha

Depois da instalação, tente um comando que deveria ser bloqueado e confirme se a recusa é clara e imediata. Se o hook estiver permissivo demais, endureça a lista de padrões; se bloquear coisas demais, restrinja os padrões ou separe regras específicas do projeto das regras pessoais. Trate a primeira execução como validação, não como estado final.