Cómo revisar código con Claude Code

Claude Code se instala con el instalador nativo, no con npm. En macOS, Linux o WSL ejecuta el script de instalación desde la terminal. En Windows nativo usa la variante para PowerShell. Al terminar, cierra y vuelve a abrir la terminal para que el binario `claude` quede en el PATH. Después entra en la raíz de tu repositorio, la carpeta donde está `.git`, y lanza `claude`. La primera vez te pedirá iniciar sesión con tu cuenta de Claude o con una API key de la Console. Es importante arrancarlo desde la raíz: Claude Code usa ese directorio como contexto de trabajo y desde ahí lee el historial de git, la estructura del proyecto y el archivo CLAUDE.md que configuraremos después. Para confirmar qué modelo estás usando, escribe `/model` dentro de la sesión. El modelo por defecto actual, claude-opus-5-5, es el más adecuado para revisiones, porque razona bien sobre cambios repartidos en muchos archivos.

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
# irm https://claude.ai/install.ps1 | iex

# Comprueba la instalación y abre el repo
claude --version
cd ~/proyectos/mi-repo
claude

Si le pides a Claude que revise sin darle criterios, recibirás comentarios genéricos sobre nombres de variables y poco más. La solución es un archivo `CLAUDE.md` en la raíz del repo. Claude Code lo carga automáticamente en cada sesión. Incluye en él lo que tu equipo considera un problema real: convenciones, patrones prohibidos, requisitos de tests y la estructura que esperas en el informe. Pide además que clasifique los hallazgos por severidad. Esto es clave para el paso de automatización, porque te permite distinguir un error bloqueante de una simple sugerencia. Versiona el archivo en git para que todo el equipo revise con las mismas reglas. Si tu proyecto tiene particularidades locales, déjalas por escrito: formatos de fecha dd/mm/aaaa, importes con IVA en España o validación de RFC, CUIT o NIT en LATAM. Claude no las adivinará.

# Guía de revisión de código

## Stack
- Backend: Node.js 22 + TypeScript estricto, Express, PostgreSQL con Prisma
- Tests: Vitest. Toda lógica nueva necesita test.

## Qué revisar (por orden de prioridad)
1. Bugs y errores de lógica (casos límite, null/undefined, async sin await)
2. Seguridad (inyección SQL, secretos en código, validación de entrada)
3. Rendimiento (consultas N+1, bucles sobre datos grandes)
4. Tests ausentes o que no prueban nada
5. Legibilidad y convenciones

## Prohibido
- `any` en TypeScript salvo con comentario justificándolo
- console.log en código de producción
- Consultas SQL concatenando strings

## Formato del informe
Agrupa por severidad: BLOQUEANTE, IMPORTANTE, SUGERENCIA.
Cada hallazgo: archivo:línea, problema, por qué importa, propuesta de cambio.
Termina con una línea: `VEREDICTO: APROBADO` o `VEREDICTO: BLOQUEANTE`.

Para revisar sin riesgo de que Claude edite archivos, activa el modo plan. En la sesión interactiva pulsa Shift+Tab hasta que el indicador inferior muestre que estás en modo plan. En ese modo Claude puede leer archivos y ejecutar comandos de consulta, pero no modifica nada. Después pídele la revisión con un alcance concreto: los cambios sin commitear, los commits de tu rama frente a main o un archivo en particular. Claude ejecutará `git diff` por su cuenta, abrirá los archivos afectados para entender el contexto (no solo las líneas cambiadas) y te devolverá el informe con el formato definido en CLAUDE.md. Este es el gran valor frente a pegar un diff en un chat: Claude puede seguir una función hasta donde se llama y detectar que tu cambio rompe algo que el diff no muestra. Si algún hallazgo te parece dudoso, pídele que lo justifique con el código concreto.

Revisa los cambios de mi rama actual respecto a main (git diff main...HEAD).
Antes de opinar, abre los archivos que llaman a las funciones modificadas
para comprobar que no rompemos nada fuera del diff.
Sigue la guía de revisión de CLAUDE.md.

Escribir el mismo prompt en cada revisión es tedioso y produce resultados irregulares. Claude Code permite crear comandos personalizados con archivos Markdown en `.claude/commands/`. El nombre del archivo se convierte en el comando: `review-pr.md` se invoca como `/review-pr`. El marcador `$ARGUMENTS` recoge lo que escribas detrás del comando, así que puedes pasarle la rama base o un foco concreto. Al guardar el archivo dentro del repo y versionarlo, cualquier compañero que clone el proyecto tendrá el mismo comando disponible. Si quieres comandos personales que funcionen en todos tus proyectos, guárdalos en `~/.claude/commands/`. Tras crear el archivo, escribe `/` en la sesión: deberías ver tu comando en la lista de sugerencias.

mkdir -p .claude/commands
cat > .claude/commands/review-pr.md << 'EOF'
---
description: Revisa los cambios de la rama actual frente a una rama base
---
Revisa el código de la rama actual.

Rama base y foco opcional: $ARGUMENTS
(si no se indica rama base, usa main)

Pasos:
1. Ejecuta `git diff <base>...HEAD --stat` para ver el alcance.
2. Ejecuta `git diff <base>...HEAD` y lee el diff completo.
3. Abre los archivos afectados y sus llamadores para entender el contexto.
4. Comprueba si existen tests para la lógica nueva o modificada.
5. Redacta el informe siguiendo la guía de CLAUDE.md.

No modifiques ningún archivo. Solo informa.
EOF

git add .claude/commands/review-pr.md
git commit -m "chore: añade comando /review-pr para Claude Code"

Para revisiones especializadas conviene un subagente: un asistente con su propio prompt de sistema, sus propias herramientas y una ventana de contexto separada. Así la revisión de seguridad no se contamina con la conversación principal, y puedes limitar sus herramientas a lectura. Los subagentes se definen en `.claude/agents/` como Markdown con frontmatter. El campo `description` es importante: Claude lo usa para decidir cuándo delegar automáticamente. También puedes invocarlo de forma explícita pidiéndole a Claude que use el subagente por su nombre. Si prefieres crearlo de forma guiada, el comando `/agents` abre un asistente interactivo. Al darle solo herramientas de lectura y búsqueda (Read, Grep, Glob), el revisor no puede editar código aunque se lo pidas por error.

mkdir -p .claude/agents
cat > .claude/agents/security-reviewer.md << 'EOF'
---
name: security-reviewer
description: Revisor de seguridad. Úsalo para auditar cambios que toquen autenticación, pagos, datos personales o entradas de usuario.
tools: Read, Grep, Glob
---
Eres un revisor de seguridad de aplicaciones con experiencia en OWASP Top 10.

Analiza el código indicado buscando:
- Inyección (SQL, comandos, plantillas)
- Autenticación y control de acceso rotos
- Secretos, tokens o claves en el código
- Exposición de datos personales (relevante para RGPD en España y leyes de protección de datos en LATAM)
- Validación de entrada ausente o insuficiente
- Dependencias o patrones criptográficos inseguros

Para cada hallazgo indica archivo:línea, severidad (BLOQUEANTE/IMPORTANTE/SUGERENCIA),
escenario de explotación concreto y corrección propuesta.
Si no encuentras nada, dilo explícitamente. No inventes problemas.
EOF

El último paso es que la revisión ocurra sin que tengas que acordarte. Claude Code tiene un modo no interactivo con la opción `-p`: recibe el prompt, imprime la respuesta y termina, así que encaja en scripts. Lo usaremos en un hook `pre-push` de git que envía el diff de tu rama a Claude y bloquea el push si el veredicto es BLOQUEANTE. El script se apoya en la línea de veredicto que definimos en CLAUDE.md, porque el modo `-p` también carga ese archivo cuando se ejecuta desde el repo. Guarda el informe en un archivo temporal para leerlo con calma si el push se bloquea. Para casos urgentes puedes saltarte el hook con `git push --no-verify`, aunque conviene que el equipo acuerde cuándo es aceptable hacerlo.

cat > .git/hooks/pre-push << 'EOF'
#!/usr/bin/env bash
set -euo pipefail

BASE="origin/main"
DIFF=$(git diff "$BASE"...HEAD)

if [ -z "$DIFF" ]; then
  exit 0
fi

echo "🔍 Revisando cambios con Claude Code..."
REPORT=$(mktemp)

echo "$DIFF" | claude -p "Revisa este diff siguiendo la guía de CLAUDE.md. Sé estricto solo con problemas reales. Termina con la línea VEREDICTO." > "$REPORT"

cat "$REPORT"

if grep -q "VEREDICTO: BLOQUEANTE" "$REPORT"; then
  echo "❌ Push bloqueado. Informe completo en: $REPORT"
  exit 1
fi

echo "✅ Revisión superada"
EOF

chmod +x .git/hooks/pre-push