claude-git-hooks/README.md

Git hooks con Claude CLI para análisis de código y generación automática de mensajes de commit

# Pre-commit Hook con Claude CLI

🚀 **Transforma tu flujo de desarrollo con IA**: análisis de código instantáneo, mensajes de commit automáticos y generación de PRs perfectas. Claude revisa tu código antes de cada commit, detecta issues críticos al estilo SonarQube, y genera toda la documentación que necesitas. ¿Lo mejor? Se ejecuta localmente sin contaminar tu CI/CD.

## 🎯 Características principales

- 🔍 **Análisis de código pre-commit**: Detecta issues críticos antes de que lleguen al repo
- 💬 **Mensajes de commit automáticos**: Escribe "auto" y Claude genera el mensaje perfecto
- 📋 **Generación de PRs**: Título, descripción y tests sugeridos con un solo comando
- 🎨 **Modo SonarQube**: Métricas de calidad y Quality Gate integrados
- 🚫 **Skip inteligente**: Excluye código legacy con comentarios SKIP-ANALYSIS
- 🔄 **Auto-actualización**: Se mantiene actualizado automáticamente

## 📋 CHEATSHEET

### 🚀 Comandos Frecuentes

```bash
# Commit rápido sin análisis + mensaje automático
git commit --no-verify -m "auto"

# Analizar diferencias con origin de la rama actual
claude-hooks analyze-diff

# Analizar diferencias para PR (comparar con origin/develop)
claude-hooks analyze-diff develop

# Reinstalar durante desarrollo (después de npm link)
claude-hooks install --force --skip-auth
```

### 📦 Instalación y Gestión

⚠️ **IMPORTANTE**: Todo debe ejecutarse desde consola WSL/Ubuntu (no PowerShell ni CMD). Ver [Configuración Previa](#-configuración-previa-importante) antes de comenzar.

Se debe instalar el paquete globalmente, para luego gestionarlo localmente en cada repositorio.

```bash
# En consola WSL/Ubuntu - Instalar globalmente
npm install -g claude-git-hooks

# Luego en cada proyecto (también desde WSL/Ubuntu)
cd /tu/proyecto
claude-hooks install

# Actualizar a última versión
claude-hooks update

# Desinstalar hooks
claude-hooks uninstall

# Ver estado actual
claude-hooks status

# Desactivar temporalmente
claude-hooks disable

# Reactivar hooks
claude-hooks enable
```

### 💻 Flujos de Commit

```bash
# Commit con análisis de código
git commit -m "feat: nueva funcionalidad"

# Generar mensaje de commit automático
git commit -m "auto"

# Saltar análisis (emergencias)
git commit --no-verify -m "hotfix: corrección urgente"

# Modificar último commit
git commit --amend
```

### 🚫 Exclusión de Código del Análisis

```java
// SKIP-ANALYSIS
private String legacyCode = "no analizar siguiente línea";

// SKIP_ANALYSIS_BLOCK
public void methodToIgnore() {
    // Todo este bloque será ignorado
    String oldCode = "legacy";
}
// SKIP_ANALYSIS_BLOCK
```

### 🔧 Configuración Avanzada

```bash
# Archivos de configuración
.claude/
├── CLAUDE_PRE_COMMIT_SONAR.md      # Personalizar criterios
├── CLAUDE_ANALYSIS_PROMPT_SONAR.md # Modificar prompt
└── settings.local.json              # Configuración local

# Variables de entorno
export CLAUDE_ANALYSIS_MODE=sonarqube  # Modo de análisis
export CLAUDE_DEBUG=true               # Debug detallado
```

### 🎯 Casos de Uso Específicos

```bash
# Desarrollo local de claude-hooks
cd /path/to/claude-git-hooks
npm link
cd /path/to/your-project
claude-hooks install --force --skip-auth

# Preparar PR hacia develop
git checkout -b feature/nueva-funcionalidad
# ... hacer cambios ...
git add .
git commit -m "feat: implementar nueva funcionalidad"
claude-hooks analyze-diff develop  # Genera título, descripción y tests

# Resolver issues bloqueantes
git commit -m "fix: resolver issues"
# Si falla, ver claude_resolution_prompt.md generado
# Copiar contenido y pegar en Claude para obtener solución
```

### ⚡ Tips y Trucos

1. **Mensaje automático**: Usa `"auto"` como mensaje para que Claude lo genere
2. **Skip auth**: Usa `--skip-auth` en CI/CD o desarrollo local
3. **Force install**: Usa `--force` para reinstalar sin confirmación
4. **Debug**: Activa `CLAUDE_DEBUG=true` para ver detalles completos
5. **Archivos grandes**: Se omiten automáticamente archivos > 100KB
6. **Límite de archivos**: Máximo 10 archivos por commit

## 🔧 Configuración Previa Importante

### Credenciales Git en WSL

Debes configurar tus credenciales de git nuevamente en WSL:

```bash
# En WSL
git config --global user.name "Tu Nombre"
git config --global user.email "tu.email@ejemplo.com"

# Si usas AWS CodeCommit o similar, reconfigura las credenciales
git config --global credential.helper store
# O configura tu credential helper específico
```

## 🚀 Instalación

**IMPORTANTE**: Claude CLI corre en WSL, por lo que toda la instalación y uso de git debe hacerse desde la terminal WSL.

```bash
# Instalar el paquete globalmente
npm install -g claude-git-hooks

# En cualquier repositorio, instalar los hooks
cd tu-proyecto
claude-hooks install
```

El comando `claude-hooks install` ahora incluye:

- ✅ Verificación completa de dependencias del sistema
- ✅ Instalación automática de paquetes faltantes (jq, curl)
- ✅ Configuración de Git (line endings WSL/Windows)
- ✅ Verificación de autenticación Claude con entretenimiento (omitible con `--skip-auth`)
- ✅ Instalación de hooks y archivos de pautas
- ✅ Actualización automática de .gitignore con archivos de Claude

**Opciones de instalación:**

- `--force`: Reinstala aunque los hooks ya existan
- `--skip-auth`: Omite la verificación de autenticación de Claude (útil para CI/CD)

## 📁 Gestión de Archivos

### Archivos creados durante la instalación

El comando `claude-hooks install` crea los siguientes archivos y directorios:

1. **`.git/hooks/pre-commit`** - Hook de análisis de código
2. **`.git/hooks/prepare-commit-msg`** - Hook de generación de mensajes
3. **`.git/hooks/check-version.sh`** - Script de verificación de versión
4. **`.claude/`** - Directorio para archivos de configuración
   - `CLAUDE_PRE_COMMIT_SONAR.md` - Pautas de evaluación SonarQube
   - `CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template de prompt para análisis SonarQube
   - `CLAUDE_RESOLUTION_PROMPT.md` - Template para prompt de resolución AI

### Actualización automática de .gitignore

Durante la instalación, Claude Hooks actualiza automáticamente tu `.gitignore` para incluir:

```gitignore
# Claude Git Hooks
.claude/
debug-claude-response.json
claude_resolution_prompt.md
.claude-pr-analysis.json
```

Esto asegura que:

- Los archivos de configuración de Claude específicos del proyecto no se suban al repositorio
- Los archivos de debug temporales se ignoren
- Cada desarrollador pueda tener sus propias preferencias de análisis

Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas se agregarán al final solo si no están presentes.

## 🎯 Funcionamiento

### Hook pre-commit (Análisis de código)

1. **Intercepta cada intento de commit** (en WSL)
2. **Extrae y filtra archivos modificados**:
   - Solo analiza: Java, XML, properties, yml, yaml
   - Omite archivos mayores a 100KB
   - Límite de 10 archivos por commit
3. **Construye prompt inteligente**:
   - Usa template de prompt desde `.claude/CLAUDE_ANALYSIS_PROMPT*.md`
   - Lee las pautas desde `.claude/CLAUDE_PRE_COMMIT*.md`
   - Incluye el diff completo para archivos nuevos
   - Muestra solo cambios para archivos existentes
4. **Envía a Claude CLI para revisión**
5. **Procesa respuesta JSON estructurada**:
   - blockingIssues siempre como objetos con localización precisa
   - verifica `QUALITY_GATE`, muestra métricas y issues por severidad
6. **Decisión final**:
   - Si hay problemas críticos → genera prompt AI de resolución y bloquea commit
   - Si todo está bien → commit procede
7. **Generación de Prompt de Resolución AI** (opcional): Cuando se detectan problemas críticos:

- Se genera automáticamente un archivo `claude_resolution_prompt.md`
- Contiene información estructurada y AI-friendly de todos los issues
- Incluye localización precisa (archivo, línea, método)
- Puede copiarse a otra instancia de Claude para resolución automática

### Hook prepare-commit-msg (Generación automática de mensajes)

1. **Se activa cuando el mensaje es**:
   - `"auto"`
2. **Analiza los cambios del staging area**:
   - Lista archivos modificados con estadísticas
   - Incluye diffs completos para archivos < 100KB
3. **Genera mensaje en formato Conventional Commits**:
   - Determina tipo: feat, fix, docs, style, refactor, test, chore
   - Crea título conciso y descriptivo
   - Añade body con detalles si es necesario
4. **Manejo de errores**:
   - Si falla la generación → cancela el commit completamente
   - No usa mensajes genéricos de fallback

### Características adicionales

- **Generación de información para Pull Requests**: `claude-hooks analyze-diff [branch]` para comparar rama local con rama origin, propone nombre para rama actual, título y detalles para pull request, da tips para verificar trabajo. Si se especifica branch, compara con origin/branch. Si no, compara con origin de la rama actual. Este comando genera automáticamente:
  - 📝 Título de PR conciso (máx. 72 caracteres)
  - 📄 Descripción detallada con markdown
  - 🌿 Nombre de rama sugerido (formato: tipo/descripcion)
  - 📋 Tipo de cambio (feature/fix/refactor/docs/test/chore)
  - ⚠️ Indicador de breaking changes
  - 🧪 Notas de testing recomendado
  - 📝 Archivo `.claude-pr-analysis.json`
- **Auto-actualización**: Verificación automática de versiones antes de cada commit con prompt interactivo para actualizar
- **Comando update**: `claude-hooks update` para actualizar manualmente a la última versión
- **Modo debug**: `DEBUG=1 git commit` guarda respuestas en `debug-claude-response.json`
- **Análisis de PR**: Nuevo comando `analyze-diff` para generar información de Pull Requests
- **Validación de dependencias**: Verifica que Claude CLI esté autenticado antes de ejecutar
- **Exclusión de código del análisis con SKIP-ANALYSIS**: Puedes excluir código específico del análisis usando comentarios `// SKIP-ANALYSIS`:

```java
// Excluir una sola línea
// SKIP-ANALYSIS
@Autowired private LegacyService legacyService;  // Esta línea no será analizada

// Excluir un bloque de código
// SKIP-ANALYSIS_BLOCK
@Deprecated
public void methodWithKnownIssues() {
    // Código legacy que no queremos que sea analizado
    System.out.println("Debug temporal");
}
// SKIP-ANALYSIS_BLOCK
```

### Desactivar/Activar hooks

```bash
# Desactivar todos los hooks
claude-hooks disable

# Desactivar un hook específico
claude-hooks disable pre-commit
claude-hooks disable prepare-commit-msg

# Habilitar todos los hooks
claude-hooks enable

# Habilitar un hook específico
claude-hooks enable pre-commit
claude-hooks enable prepare-commit-msg

# Ver estado actual
claude-hooks status
```

## ⚙️ Configuración

### Scripts

En el archivo `pre-commit`:

- **`MAX_FILE_SIZE`**: Tamaño máximo de archivo a analizar (default: 100KB)
- **`MAX_FILES`**: Número máximo de archivos por commit (default: 10)
- **`CLAUDE_CLI`**: Comando de Claude CLI (default: "claude")
- **`GUIDELINES_FILE`**: Archivo de pautas (default: ".claude/CLAUDE_PRE_COMMIT_SONAR.md")

En el archivo `prepare-commit-msg`:

- **`MAX_FILE_SIZE`**: Tamaño máximo para incluir diff completo (default: 100KB)
- **`CLAUDE_CLI`**: Comando de Claude CLI (default: "claude")

### Pautas de Evaluación

- **`CLAUDE_PRE_COMMIT_SONAR.md`** - Criterios para modo SonarQube

### Templates de Prompts

- **`CLAUDE_ANALYSIS_PROMPT_SONAR.md`** - Estructura del prompt SonarQube
- **`CLAUDE_RESOLUTION_PROMPT.md`** - Template para generar prompts de resolución

Todos estos archivos son personalizables y específicos de tu proyecto. Puedes:

- Modificar los criterios de evaluación según estándares del equipo
- Ajustar la estructura de los prompts para obtener respuestas más precisas
- Personalizar el formato de salida del prompt de resolución

## 🐛 Troubleshooting

No hay... esto es la perfección hecha código.

## 🔧 Desarrollo y Contribución

### Estructura del Proyecto

```
claude-git-hooks/
├── bin/
│   └── claude-hooks                          # CLI principal con verificación completa
├── templates/
│   ├── pre-commit                            # Hook de análisis de código
│   ├── prepare-commit-msg                    # Hook de generación de mensajes
│   ├── check-version.sh                      # Script de verificación de versión
│   ├── CLAUDE_PRE_COMMIT_SONAR.md            # Pautas SonarQube para pre commit
│   ├── CLAUDE_ANALYSIS_PROMPT_SONAR.md       # Template de prompt para análisis
│   └── CLAUDE_RESOLUTION_PROMPT.md           # Template para resolución de issues
├── .claude/                                  # Directorio de configuración local (gitignore)
│   └── settings.local.json                   # Configuración local del usuario
├── package.json                              # Configuración NPM
├── package-lock.json                         # Lock file de NPM
├── README.md                                 # Este archivo
├── README-NPM.md                             # Documentación para publicación NPM
├── CHANGELOG.md                              # Historial de versiones
├── PUBLISH.md                                # Guía de publicación
├── CLAUDE_PRE_COMMIT_SONAR.md                # Pautas de evaluación (legacy)
├── pre-commit                                # Hook principal (legacy)
└── .gitignore                                # Archivos ignorados por git
```

### Configuración del Entorno de Desarrollo

```bash
# 1. Clonar el repositorio
git clone https://github.com/pablorovito/claude-git-hooks.git
cd claude-git-hooks

# 2. Instalar dependencias (si las hubiera)
npm install

# 3. Enlazar para desarrollo local
npm link

# 4. Probar en un repositorio de prueba
cd /path/to/test-repo
claude-hooks install
```

### Workflow de Desarrollo

#### 1. Modificar Hooks

Los hooks están en `templates/`:

- `templates/pre-commit` - Lógica de análisis de código
- `templates/prepare-commit-msg` - Lógica de generación de mensajes

#### 2. Probar Localmente

```bash
# Después de modificar archivos, repo de claude-hooks
npm link

# En un repo de prueba
claude-hooks install --force  # Fuerza reinstalación, luego probar lo que se desee
```

#### 3. Actualizar Documentación

- `README.md` - Documentación principal
- `CHANGELOG.md` - Documentación principal
- `README-NPM.md` - Para usuarios de NPM

#### 4. Versioning y Publicación

```bash
# Actualizar versión
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# Publicar nueva versión
npm publish
```