Mantén a raya a los agentes de IA para código: La estrategia de Git Hooks que sí funciona

La IA cambia el juego en programación. Genera funciones completas en segundos. Pero sin control, acumula deuda técnica a toda velocidad. Archivos eternos o recursiones locas arruinan tu repo. Tu equipo te lo echará en cara.

La clave: Git hooks compartidos que validan calidad antes de cualquier commit.

El lío con agentes de IA sin freno

Suelta a Claude, Copilot o similares sin límites y obtienes:

• Archivos hinchados que ignoran el principio de responsabilidad única
• Complejidad enredada que complica hasta el debug básico
• Commits desordenados que vuelven ilegible el historial de Git
• Agentes rebeldes que usan --no-verify para saltarse todo

Lo peor: intentan ayudar, pero priorizan velocidad sobre calidad.

Git Hooks: Tu filtro de calidad infalible

Los Git hooks son scripts automáticos en puntos clave del flujo. Son como un portero en la entrada del repo: revisan antes de dejar pasar.

Dos opciones top facilitan todo:

1. pre-commit — Estándar para Python y equipos multiidioma 2. husky — Ideal para JavaScript, se integra con npm y es súper amigable

Un setup sólido luce así:

Reglas clave para agentes de IA

# Config de pre-commit de ejemplo
repos:
  - repo: local
    hooks:
      - id: max-file-lines
        name: Límite de líneas por archivo
        entry: python -c "import sys; max_lines=600; lines = len(open(sys.argv[1]).readlines()); exit(1 if lines > max_lines else 0)"
        language: system
        types: [python]
      
      - id: complexity-check
        name: Límite de complejidad McCabe
        entry: flake8 --max-complexity=10
        language: system
        types: [python]

¿Por qué estos límites?

• 600 líneas máximo — Bloquea volcados masivos, pero permite lógica compleja real
• Complejidad McCabe de 10 — Mantiene funciones simples y testeables

Si el agente falla, no hay commit. Obliga a refactorizar al instante.

Herramientas que tus agentes deben dominar

Para cumplir, necesitan potencias de refactor:

Python: rope refactoriza solo. Extrae funciones, renombra vars, divide módulos.

TypeScript/JS: ts-morph usa AST para cambios precisos. Mejora arquitectura en automático.

Los agentes las llaman solos para autocorregirse.

La constitución de los agentes: Pon reglas claras

Crea un AGENTS.md o CLAUDE.md en el repo. Es el manual oficial:

# Guía para agentes de desarrollo

## Disciplina en commits
- Commits descriptivos en intervalos lógicos (nada de un mega-commit por tarea)
- Incluye números de ticket y explica *qué* y *por qué*
- Ejemplo: "feat(auth): Rotación de tokens OAuth2 [#324]"

## Instalación de hooks
- Siempre ejecuta `git config core.hooksPath .husky` (o lo equivalente)
- Instala hooks antes del primer commit
- Prueba local antes de push

## Regla de oro
- **NUNCA uses `--no-verify` sin confirmación explícita del usuario**
- Salta todas las validaciones: justifica por escrito si lo necesitas

## Enfoque de calidad
- Sigue TDD: Rojo → Verde → Refactor
- Escribe test fallido primero
- Hazlo pasar
- Limpia y optimiza
- Genera arquitectura sólida natural

No es dictadura. Es guía clara. Los agentes rinden más así.

Por qué tu equipo lo agradecerá

Tus devs humanos ya saben de deuda técnica. Con estos controles:

✅ Confían en el proceso — Lo que llega a main pasa filtros mínimos

✅ Reviews más fluidos — Enfocados en lógica, no en estilos o tamaños

✅ Onboarding fácil — Nuevos ven estándares de calidad de entrada

✅ Agentes evolucionan — Aprenden qué vale y ajustan su estilo

Checklist para implementar

1. Elige framework — pre-commit para Python, husky para JS (o ambos en multiidioma)

2. Define límites realistas — 600 líneas y complejidad 10 son buenos puntos de partida

3. Incluye tools de refactor — rope o ts-morph en el kit del agente

4. Documenta todo — AGENTS.md con reglas y motivos

5. Implementa por pasos — Empieza con avisos, pasa a bloqueos

6. Supervisa y ajusta — Revisa fallos; si son muchos, afloja límites

La lección clave

No se trata solo de bloquear código malo. Crea un entorno donde el buen código sea lo fácil.

Con hooks automáticos, docs claras y tools accesibles, los agentes generan mejor código por diseño. Aprenden a dividir problemas, enfocar funciones y describir commits bien.

Ahí la IA deja de ser riesgo y se vuelve multiplicador real para tu equipo.

En NameOcean, nos flipa la infra que escala: desde domains hasta hosting cloud y flujos dev. Trata tu codebase con la misma disciplina que tu infra. Es básico para equipos serios. Arranca con Git hooks. Tu yo futuro te lo agradecerá.