git-guardrails-claude-code

Descripción general de la skill git-guardrails-claude-code

La skill git-guardrails-claude-code ayuda a Claude Code a rechazar una lista breve de comandos destructivos de Git antes de ejecutarlos. Su función real es simple: añadir una capa de seguridad para que una sesión de programación con IA no pueda hacer con ligereza git push, git reset --hard, git clean -f, borrar ramas con git branch -D ni eliminar cambios del árbol de trabajo con git checkout . o git restore ..

Quién debería usar git-guardrails-claude-code

Esta skill encaja mejor con quienes:

• usan Claude Code directamente sobre repositorios reales
• quieren ayuda de IA, pero no quieren que ejecute acciones irreversibles en Git
• trabajan en repos compartidos, repos de producción o codebases de clientes
• prefieren una aplicación local de la política en lugar de confiar en prompts del tipo “ten cuidado”

Si tu principal preocupación es la destrucción accidental de código o los pushes no autorizados durante una sesión con agentes, git-guardrails-claude-code es una opción muy sólida.

Qué la diferencia de un prompt normal

Un prompt normal puede pedirle a Claude que no ejecute comandos arriesgados, pero los prompts son una guía blanda. git-guardrails-claude-code usa un hook PreToolUse, así que la restricción vive en la ruta de ejecución de Claude Code y no solo en la conversación. Ese es su principal factor diferencial y la razón más importante para instalarla.

Qué bloquea realmente

El script shell incluido revisa los comandos Bash entrantes y bloquea patrones como:

• git push
• git reset --hard
• git clean -f
• git clean -fd
• git branch -D
• git checkout .
• git restore .
• coincidencias relacionadas con force-push, como push --force

El mensaje de bloqueo le indica a Claude que no tiene autorización para usar ese comando.

Lo que esta skill no hace

git-guardrails-claude-code no es un motor completo de políticas de Git. No:

• revisa la calidad de los commits
• exige aprobaciones
• distingue entre destinos de push seguros o inseguros
• entiende reglas de branching específicas del repositorio
• protege comandos fuera de los patrones listados, salvo que edites el script

Esto importa al decidir si adoptarla: es una barrera de seguridad enfocada, no una solución integral de gobernanza.

Cómo usar la skill git-guardrails-claude-code

Empieza decidiendo el alcance

La primera decisión práctica en la skill original es si instalar la barrera:

• solo para este proyecto en .claude/settings.json, o
• para todos los proyectos en ~/.claude/settings.json

Esta decisión cambia dónde copias el script y qué tan amplio será el bloqueo. Para la mayoría de los equipos, la instalación a nivel de proyecto es más segura para hacer pruebas. La instalación global tiene sentido cuando ya sabes que quieres las mismas restricciones de Git en todas partes.

Lee primero estos archivos

Puedes entender casi todo lo importante leyendo:

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

Ese orden de lectura conviene porque SKILL.md explica cómo se conecta el hook, mientras que scripts/block-dangerous-git.sh muestra los patrones exactos que se bloquean. Si te preocupan los falsos positivos o los huecos, el script importa más que la prosa.

Contexto de instalación de git-guardrails-claude-code

El proceso de git-guardrails-claude-code install es, en esencia, una configuración manual dentro del sistema de hooks de Claude Code:

1. copiar el script shell a un directorio de hooks
2. darle permisos de ejecución
3. registrarlo bajo PreToolUse para el matcher Bash

La ruta del repositorio para el script fuente es:

scripts/block-dangerous-git.sh

Las ubicaciones de destino son:

• alcance de proyecto: .claude/hooks/block-dangerous-git.sh
• alcance global: ~/.claude/hooks/block-dangerous-git.sh

Después, dale permisos de ejecución:

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

o para alcance global:

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

Añade correctamente el hook de Claude Code

Para el alcance de proyecto, la skill muestra un hook PreToolUse en .claude/settings.json que ejecuta el script copiado usando "$CLAUDE_PROJECT_DIR".

Los puntos clave de la configuración son:

• evento del hook: PreToolUse
• matcher: Bash
• tipo de hook: command
• comando: la ruta a block-dangerous-git.sh

Si este hook no queda registrado bajo PreToolUse, el script existirá, pero nunca interceptará comandos.

Cómo funciona el script en la práctica

El script shell lee la entrada de la herramienta desde la entrada estándar, extrae .tool_input.command con jq y compara el comando con un pequeño array de patrones peligrosos mediante grep -qE.

Eso significa que los posibles bloqueadores de adopción son bastante claros:

• jq debe estar disponible en el entorno
• la ruta del comando en settings debe ser válida
• el script debe ser ejecutable
• Claude Code debe estar invocando realmente las llamadas a la herramienta Bash a través del sistema de hooks

Si alguna de esas piezas falla, la protección se debilita en silencio más de lo que imaginas.

Qué información necesita la skill de tu parte

La skill original necesita muy poco contexto, pero un buen flujo de git-guardrails-claude-code usage empieza con estas decisiones:

• solo proyecto o global
• si la lista bloqueada por defecto es suficiente
• si tu equipo también quiere bloquear comandos extra como git tag -d, git rebase --abort o pushes específicos por remoto
• si los usuarios seguirán necesitando una vía de escalado manual documentada para pushes legítimos

Sin esas respuestas, la instalación es sencilla, pero el encaje con tu política puede ser pobre.

Cómo convertir un objetivo vago en un prompt sólido

Prompt débil:

• “Set up git guardrails.”

Prompt más sólido:

• “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 qué esto es mejor:

• define el alcance
• especifica el destino
• pide tanto la configuración como la verificación
• reduce la probabilidad de que Claude improvise una estructura de hooks diferente

Un buen flujo de primera ejecución con git-guardrails-claude-code

Una guía práctica de git-guardrails-claude-code guide se ve así:

1. elegir alcance de proyecto o global
2. inspeccionar scripts/block-dangerous-git.sh
3. copiar el script al directorio de hooks de destino
4. ejecutar chmod +x sobre el archivo copiado
5. conectar el hook PreToolUse en el archivo de settings correcto
6. probar con una simulación inocua o con un comando claramente bloqueado en un repo seguro
7. decidir si conviene personalizar los patrones

Este orden importa porque te permite verificar la lista real de enforcement antes de desplegarla de forma amplia.

Cómo validar la instalación

No te quedes en “el archivo existe”. Valida el comportamiento:

• confirma que la ruta del archivo de settings es la que Claude Code está usando
• confirma que el comando del hook apunta al script copiado, no a la ruta fuente del repositorio
• dispara un patrón bloqueado en un repo desechable
• comprueba que Claude reciba una denegación en lugar de ejecutar el comando

En esta skill, la verificación de comportamiento importa más que la verificación visual.

Cuándo encaja mejor en flujos de trabajo con Git

git-guardrails-claude-code for Git Workflows resulta especialmente útil cuando tu flujo de trabajo preferido con IA es:

• dejar que Claude edite archivos con libertad
• dejar que Claude inspeccione diffs y el estado
• mantener el borrado de ramas, el force push, los hard reset y los comandos de limpieza bajo control humano explícito

Esa separación funciona bien porque conserva la productividad de la IA para tareas de programación, mientras deja las acciones irreversibles del repositorio en manos humanas.

Cuándo conviene personalizar el script

La lista por defecto es deliberadamente estrecha. Personaliza scripts/block-dangerous-git.sh si:

• tu equipo considera aceptable git push, pero quiere bloquear solo --force
• también quieres bloquear git commit --amend
• tu flujo incluye patrones sensibles de borrado de ramas
• quieres reglas distintas por repositorio

La principal compensación es simplicidad frente a precisión. El script estándar es fácil de auditar; uno muy personalizado necesita más pruebas.

Preguntas frecuentes sobre la skill git-guardrails-claude-code

Si estoy empezando, ¿git-guardrails-claude-code me conviene?

Sí, si ya usas Claude Code y quieres una configuración más segura alrededor de Git. La puesta en marcha es breve y el concepto se entiende fácil: interceptar llamadas a la herramienta Bash antes de su ejecución. Las únicas partes algo técnicas son la configuración JSON del hook y los permisos del script shell.

¿Es mejor que decirle a Claude “never push”?

Sí, para los comandos concretos que cubre. git-guardrails-claude-code convierte una regla conversacional en una comprobación en tiempo de ejecución. Eso la hace mucho más fiable que depender solo de que recuerde el prompt.

¿git-guardrails-claude-code bloquea todos los comandos peligrosos de Git?

No. Bloquea los patrones explícitos que aparecen en el script. Si tu modelo de riesgo incluye otros comandos, tendrás que añadirlos tú mismo. Ese es un límite clave de la skill.

¿Puedo usar git-guardrails-claude-code de forma global?

Sí. La skill admite explícitamente una instalación global mediante ~/.claude/settings.json y ~/.claude/hooks/block-dangerous-git.sh. La instalación global es cómoda, pero la instalación por proyecto es más fácil de probar y más segura si distintos repos necesitan políticas diferentes.

¿Interferirá con el trabajo normal de desarrollo?

Por lo general, no demasiado, si tu flujo habitual no espera que Claude haga push ni tareas destructivas de limpieza en Git. Es más compatible con un flujo donde Claude edita código, ejecuta tests y prepara cambios, mientras una persona conserva la autoridad final sobre Git.

¿Cuándo no debería usar esta skill?

Omite git-guardrails-claude-code si:

• realmente quieres que Claude gestione Git de extremo a extremo
• tu equipo necesita allowlists matizadas en lugar de simples bloqueos por patrón
• no puedes depender de hooks shell ni de jq
• necesitas enforcement a nivel organizativo más allá de la configuración local de Claude Code

En esos casos, esta skill puede resultarte demasiado limitada o demasiado local.

Cómo mejorar la skill git-guardrails-claude-code

Audita los patrones bloqueados frente a tus riesgos reales

La forma más rápida de mejorar git-guardrails-claude-code es comparar la lista de patrones por defecto con los errores de Git que realmente te preocupan. A muchos equipos les preocupan menos todos los pushes y más cosas como:

• force pushes
• borrado de ramas protegidas
• limpiezas destructivas en monorepos
• resets del árbol de trabajo durante tareas de debugging

Si tu política es distinta, edita el array de patrones en lugar de aceptar la configuración por defecto sin revisarla.

Dale a Claude instrucciones de instalación más precisas

Si le pides a Claude que aplique esta skill, incluye detalles concretos:

• alcance
• ruta exacta de destino
• si debe conservar o fusionar hooks existentes
• si debe mostrar el archivo JSON final para revisión
• si debe probar el hook después de configurarlo

Una solicitud más sólida sería:

• “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.”

Eso evita uno de los fallos más comunes: reemplazar la configuración de hooks que ya existía.

Vigila los errores al fusionar hooks

Un problema realista no suele ser el script shell, sino la actualización del archivo de settings. Si un repositorio ya tiene hooks configurados, una instalación descuidada puede sobrescribirlos. Pide:

• un diff, no una reescritura ciega
• conservar las entradas PreToolUse existentes
• una explicación del orden de los hooks si se ejecutan varios comandos

Para muchos usuarios, esto importa más que la lista de comandos bloqueados.

Prueba falsos positivos y vías de evasión

Como el script usa coincidencia por patrones, deberías probar:

• comandos legítimos que deberían pasar
• comandos bloqueados que deberían fallar
• variantes que asumes que están bloqueadas, pero quizá no lo estén
• cadenas de comandos que contengan texto similar de formas inesperadas

Este es el punto correcto para reforzar la confianza en git-guardrails-claude-code usage, especialmente antes de desplegarlo globalmente.

Endurece el script solo después de detectar fallos reales

Puede resultar tentador añadir muchos patrones de inmediato. Resístete, salvo que tengas evidencia. Una blocklist corta y legible es más fácil de confiar y mantener. Amplíala después de observar:

• comandos que Claude intenta con frecuencia
• comandos que los usuarios consideran arriesgados
• patrones que se colaron
• comandos que se bloquearon, pero no deberían haberse bloqueado

Así la barrera sigue siendo comprensible.

Añade una vía de escalado humana

Una mejora operativa útil es combinar la barrera con una regla clara como:

• Claude puede preparar commits y explicar los pasos para hacer push
• una persona realiza manualmente el push final o la limpieza destructiva

Esto mejora la skill porque los usuarios dejan de pelearse con la barrera y empiezan a diseñar su flujo alrededor de ella.

Revisa si el alcance global o por proyecto sigue siendo el adecuado

Tras el uso inicial, vuelve a evaluar el alcance:

• si la regla funciona bien en todos los repos, pásala a global
• si algunos repos necesitan un comportamiento de Git más flexible, mantenla local al proyecto
• si los equipos varían, mantén versiones separadas del script a nivel de proyecto

Es una de las formas más sencillas de mejorar el encaje sin tocar código.

Mantén el script legible

Si personalizas git-guardrails-claude-code, procura que el script shell siga siendo fácil de auditar. Prioriza una lista clara de patrones y una única ruta de error antes que lógica ingeniosa. En un control de seguridad, la legibilidad también forma parte de la fiabilidad.