En un equipo grande tienes pull requests con 3 reviewers, un tech lead que conoce cada módulo, y procesos definidos. En un equipo pequeño tienes a ti mismo, quizás un par de personas más, y la presión de entregar rápido sin romper nada.
Ahí es donde Claude Code cambia el juego — pero no de la manera que te venden.
No es magia. Es un reviewer que nunca se cansa, conoce todo tu codebase, y no le importa que sean las 11pm. Pero como cualquier herramienta, funciona bien solo si sabes configurarla. Estas son las 5 prácticas que uso en mi equipo.
1. El CLAUDE.md compartido es tu estándar de equipo
En equipos pequeños el "estilo de código" vive en la cabeza de la persona más senior. Eso es un problema cuando no está disponible, cuando entra alguien nuevo, o cuando quieres que Claude Code revise con los mismos criterios que tú usarías.
La solución es un CLAUDE.md en la raíz del proyecto que todos comparten vía Git. Claude Code lo lee automáticamente en cada sesión — es el contexto base que no tienes que repetir nunca.
Un CLAUDE.md para code review se ve así:
# Estándares del proyecto
## Stack
- TypeScript estricto — sin `any` implícitos
- Hono + Cloudflare Workers
- Node.js para scripts internos
## Reglas de código
- Funciones de máximo 30 líneas
- Sin lógica de negocio en controllers, solo en services
- Manejo explícito de errores — nunca silencioso
- Nombres de variables y funciones en inglés
- Comentarios en español
## En code review, siempre verificar
- Todo endpoint nuevo tiene manejo de error 400/401/500
- Ninguna función async sin try/catch o propagación explícita
- Sin console.log en código que va a producción
- Variables de entorno solo desde `env`, nunca hardcodeadas
Tip: mantenlo bajo 200 líneas. Claude Code lo lee completo en cada sesión — si es muy largo, empieza a ignorar partes.
2. El REVIEW.md para afinar qué te importa en cada PR
Claude Code tiene soporte nativo para un archivo REVIEW.md en la raíz del proyecto. Es separado del CLAUDE.md por una razón: el CLAUDE.md es contexto general del proyecto, el REVIEW.md es instrucciones específicas de cómo revisar PRs.
Lo que puedes controlar con él:
# Instrucciones de review
## Severidad
- 🔴 Importante: bugs que rompen producción, problemas de seguridad,
cualquier violación a las reglas del CLAUDE.md
- 🟡 Nit: mejoras de legibilidad, nombres confusos, comentarios faltantes
## Límites
- Máximo 5 nits por review — el resto menciónalos como conteo en el resumen
- No reportar problemas en archivos generados: `dist/`, `*.lock`, `*.generated.ts`
## Siempre revisar
- Nuevas rutas de API deben tener al menos un test de integración
- Cualquier cambio en middleware de auth requiere verificación de edge cases
## No revisar
- Archivos en `scripts/` a menos que el problema sea crítico y evidente
- Linting — ya lo maneja el CI
Por qué importa: sin esto, Claude Code revisa todo con la misma lupa. Con esto, invierte más atención donde tú decides que importa.
3. El comando /review como parte del flujo, no como extra
Claude Code tiene slash commands. Puedes crear uno en .claude/commands/review.md que estandarice cómo se hace review en tu equipo:
# /review
Eres el reviewer de código de este equipo. Lee el CLAUDE.md y el REVIEW.md
antes de empezar.
Revisa los cambios que te paso y dame:
1. **Problemas críticos** (si los hay): bugs, seguridad, edge cases no manejados.
Para cada uno: archivo, línea, qué falla, con qué input falla.
2. **Violaciones al estándar del equipo**: cualquier regla del CLAUDE.md que
no se respeta. Línea exacta y por qué importa.
3. **Una pregunta** que le harías al autor sobre una decisión de diseño
que no es obvia.
Si no hay problemas críticos, dilo directo. No infles el review.
Uso: dentro de Claude Code, corres /review y pegas el diff o señalas los archivos. El comando ya sabe qué buscar y cómo reportarlo.
Por qué funciona: estandarizas el output del review para que todos en el equipo reciban el mismo nivel de feedback, independiente de quién haga el review.
4. Pídele que encuentre el bug antes de que llegue al PR
Esto es diferente al review: es un chequeo que haces tú mismo antes de abrir el PR. El objetivo no es validar que el código está bien — es asumir que algo falla y encontrarlo.
Asume que este código va a producción mañana y algo va a fallar.
¿Cuál es el escenario más probable de falla?
Dame:
- El input exacto que lo rompe
- Qué línea falla y por qué
- Si el problema es de lógica, seguridad, o manejo de errores
No me expliques qué es el problema en abstracto — muéstrame el caso concreto.
Ejemplo real de lo que esto encuentra: un middleware de autenticación que valida el token pero olvida llamar next() cuando es válido — el request queda colgado. No es un error de sintaxis, no lo atrapa el linter, y es fácil de no ver cuando llevas horas en el mismo código.
Tip: corre esto antes de cada PR en código que toca auth, pagos, o lógica crítica de negocio. En el resto, úsalo cuando algo "se siente raro".
5. Úsala para preparar la conversación con el autor, no para reemplazarla
Esto es lo que menos gente hace y lo que más valor entrega en equipos pequeños. Cuando tienes poco tiempo para revisar el código de un compañero, Claude Code puede leerlo primero y prepararte para la conversación.
Voy a revisar el código de un compañero y tengo 15 minutos.
Lee estos archivos y prepárame para la conversación:
1. Las 2-3 decisiones de diseño más importantes que tomó el autor
2. Las preguntas que YO debería hacerle — no el veredicto, las preguntas
3. Una área donde necesito entender el contexto antes de opinar
No me des el review completo. Dame lo que necesito para tener
una conversación útil con quien escribió el código.
Por qué funciona: la diferencia entre un review útil y uno que genera fricción está en las preguntas. Cuando llegas con preguntas en lugar de veredictos, la conversación es más productiva y el código mejora más.
Extra 1: Dale acceso al gh CLI y cambia todo
Hay un salto de calidad importante cuando Claude Code tiene acceso al GitHub CLI (gh) instalado en tu máquina. En lugar de tener que copiar y pegar diffs manualmente, puede leer el PR directamente, ver los comentarios existentes, y postear sus findings como comentarios inline en GitHub.
Claude Code tiene un plugin oficial de review que aprovecha exactamente esto:
# Primero asegúrate de tener gh instalado y autenticado
brew install gh
gh auth login
# Dentro de Claude Code, en la rama del PR:
/code-review # review local, output en terminal
/code-review --comment # postea los findings directo en el PR de GitHub
Lo que hace internamente es poderoso: lanza 4 agentes de review en paralelo, cada uno buscando una clase diferente de problema, y solo reporta issues con más de 80% de confianza. Eso filtra el ruido considerablemente.
Con gh disponible, Claude también puede leer los comentarios que dejaron otros reviewers antes de hacer el suyo — evita duplicar feedback y puede responder a preguntas abiertas en el PR. Eso lo convierte en un participante del review, no solo en un análisis estático.
Para GitLab: el equivalente es glab. El flujo es el mismo — Claude Code sabe usarlo si está instalado.
Extra 2: Cómo incorporar esto sin romper el proceso actual
El error al introducir AI en el review es presentarlo como un reemplazo. No lo es, y si lo presentas así, el equipo lo va a resistir — y con razón.
El marco que funciona en equipos pequeños es este: Claude revisa primero, los humanos deciden.
Regla base para empezar:
Claude Code puede comentar y analizar
Claude Code nunca aprueba ni mergea
Siempre se requiere al menos un approval humano
En la práctica, la adopción gradual se ve así:
Semana 1-2 — Solo el autor El que abre el PR corre /code-review antes de pedirlo a sus compañeros. Se convierte en un hábito personal, no en un proceso impuesto.
Semana 3-4 — Con --comment activado Los findings de Claude aparecen como comentarios en el PR antes de que llegue el reviewer humano. El reviewer humano ve lo que Claude ya marcó y puede enfocarse en lo que Claude no puede ver: contexto de negocio, decisiones de arquitectura, deuda técnica conocida.
Mes 2 en adelante — CLAUDE.md afinado A medida que el equipo ve qué reporta Claude que es útil y qué es ruido, ajustan el REVIEW.md. El proceso se vuelve más preciso con el tiempo.
Lo que cambia en la práctica: el reviewer humano deja de invertir tiempo en señalar lo obvio y puede concentrarse en la conversación que realmente importa. En un equipo de 2-3 personas, eso es la diferencia entre un review que toma 45 minutos y uno que toma 15.
Lo que Claude Code no reemplaza
El Code Review automático en PRs de GitHub es solo para planes Team y Enterprise, y cuesta entre $15-25 por review. Para equipos pequeños, los comandos manuales con gh CLI y el CLAUDE.md compartido son la alternativa real y sin costo adicional.
Y ninguna de estas prácticas reemplaza la conversación entre personas. Claude Code no sabe por qué el equipo tomó cierta decisión hace 6 meses, no conoce las limitaciones del cliente, y no puede leer entre líneas cuando alguien está sobrecargado.
Lo que sí hace es elevar el nivel base del review: cuando llega el humano, puede enfocarse en lo que realmente importa. En un equipo pequeño, eso marca la diferencia entre entregar con confianza o cruzar los dedos cada vez que haces deploy.
¿Tienes un CLAUDE.md en tu proyecto? Si no lo tienes todavía, este es el mejor momento para empezar.
P.D. Si esto te fue útil, compártelo con alguien de tu equipo que todavía revisa PRs a las 11pm. Y si quieres recibir una práctica así cada domingo, y las noticias más relevantes de IA en español súscríbete a bitneuronal