Claude Code Routines: semanas ignorándolo y finalmente entendí por qué importa

Configurar el entorno de trabajo es básicamente como preparar la mise en place antes de cocinar. El chef que arranca a cocinar sin tener todo picado, medido y a mano no es más eficiente — es más caótico. Y cuando el servicio explota a las 9pm, se arrepiente de no haber puesto los cinco minutos antes.

Yo era ese chef. Semanas usando Claude Code como si fuera un chat glorificado, sin rutinas, sin contexto persistente, explicando lo mismo una y otra vez en cada sesión. Convenciéndome de que configurar eso era pérdida de tiempo.

Con 611 puntos en Hacker News para un post sobre Claude Code Routines, me di cuenta de que el problema era mío.

Qué son las rutinas en Claude Code y por qué las ignoré

Una rutina en Claude Code es básicamente un archivo de instrucciones persistentes que se ejecutan automáticamente en determinados momentos del workflow — al iniciar una sesión, antes de un commit, después de correr tests, cuando se detecta cierto tipo de archivo.

No son macros. No son scripts de bash disfrazados. Son contexto estructurado que le decís a Claude qué rol tiene en este proyecto, cómo querés que responda, qué convenciones seguís, qué no tiene que romper jamás.

Mi resistencia era puramente irracional: "ya sé lo que hago, no necesito andadores". La misma lógica con la que a los 19 años tiré un servidor de producción con rm -rf convencido de que sabía lo que hacía. La confianza sin estructura es deuda técnica esperando ejecutarse.

El archivo central es CLAUDE.md en la raíz del proyecto. Pero las rutinas van más allá.

# CLAUDE.md — Contexto del proyecto

## Stack actual
- Next.js 15 + React 19
- TypeScript estricto (no any, nunca)
- PostgreSQL en Railway
- Docker para desarrollo local

## Convenciones críticas
- Componentes: PascalCase, un componente por archivo
- API routes: siempre validar con Zod antes de tocar la DB
- Errores: nunca swallowear, siempre loguear con contexto
- Tests: cada función de utilidad tiene su test, sin excepción

## Lo que NO hacer
- No usar `any` en TypeScript — si no sabés el tipo, investigá
- No instalar dependencias sin preguntar primero
- No modificar schema de DB sin migration explícita

## Contexto de negocio
- Es un SaaS B2B, los errores tienen costo real
- Los usuarios son no técnicos, los mensajes de error deben ser humanos

Eso es lo básico. Lo que lo convierte en rutina real es el siguiente nivel.

La arquitectura real de las rutinas: hooks y contexto por tarea

Claude Code permite definir comportamientos específicos por tipo de tarea. No es un solo archivo monolítico — es un sistema de capas.

# Estructura que terminé adoptando
.claude/
  commands/          # Comandos custom reutilizables
    review-pr.md     # Qué revisar en cada PR
    debug-api.md     # Protocolo de debugging para endpoints
    write-test.md    # Cómo escribir tests en este proyecto
  hooks/
    pre-commit.md    # Qué verificar antes de commitear
    post-error.md    # Qué hacer cuando algo rompe
CLAUDE.md            # Contexto global del proyecto

Los comandos custom son donde esto se vuelve poderoso. En vez de escribir "revisá este PR checkeando performance, seguridad y consistencia con las convenciones del proyecto" cada vez, tenés:

# .claude/commands/review-pr.md

Cuando revises un PR en este proyecto, seguí este orden:

1. **Seguridad primero**
   - Inputs del usuario siempre validados con Zod
   - Sin secrets hardcodeados (buscar patrones: key, token, secret, password)
   - SQL queries usando el ORM, nunca string concatenation

2. **Performance**
   - Queries N+1 (buscá loops con llamadas a DB adentro)
   - Imágenes sin optimización next/image
   - Bundle size: imports de librerías completas cuando se necesita una función

3. **Consistencia con el proyecto**
   - Naming conventions del CLAUDE.md
   - Manejo de errores según el estándar definido
   - Tests incluidos si aplica

4. **Resumen final**
   - Bloqueantes (no se mergea sin fix)
   - Sugerencias (nice to have)
   - Lo que está bien (importante para el equipo)

Llamás esto con /project:review-pr y Claude tiene todo el contexto necesario sin que vos lo repitas. El ahorro no es de caracteres — es cognitivo. Cada vez que explicás el mismo contexto, gastás energía mental que podrías usar en el problema real.

Trabajando en proyectos como el experimento de sonificación de colectivos — donde el stack combina procesamiento de GTFS-RT en tiempo real con síntesis de audio — tener el contexto del proyecto persistente fue la diferencia entre sesiones productivas y sesiones de onboarding eterno.

Los errores que cometí antes de entenderlo

Error 1: Tratar CLAUDE.md como documentación para humanos

Mi primer intento fue copiar el README del proyecto. Tiene sentido intuitivo pero es el enfoque equivocado. La documentación para humanos explica qué hace el sistema. Las instrucciones para Claude deben explicar cómo querés que él trabaje con vos. Son cosas distintas.

Un README dice: "Este servicio procesa webhooks de Stripe".
Un buen CLAUDE.md dice: "Cuando trabajes con el módulo de pagos, siempre verificar idempotency keys, siempre logear el webhook ID, nunca modificar el estado del pago sin pasar por la state machine en /lib/payments/state.ts".

Error 2: Rutinas genéricas que no dicen nada

# ❌ Esto no sirve para nada
Escribí código limpio y bien documentado.
Seguí las mejores prácticas.
Sé consistente.

# ✅ Esto sí funciona
Cada función que escribas necesita:
- JSDoc con @param y @returns tipados
- Al menos un test unitario en __tests__/[nombre].test.ts
- Manejo de error explícito — si puede fallar, tiene que tirar un Error con mensaje descriptivo

Vaguedad en las instrucciones genera vaguedad en los resultados. Lo mismo que pasa cuando describís mal un requerimiento a un junior — y lo sé de primera mano liderando equipos desde 2023.

Error 3: No separar contexto global de contexto específico

Todo en un solo CLAUDE.md enorme se vuelve ruido. Claude lee todo el contexto en cada operación. Si metés las instrucciones de cómo escribir migraciones de DB junto con las convenciones de naming de componentes React, estás contaminando contexto que no es relevante para la tarea actual.

La separación por subdirectorios resuelve esto. Las instrucciones en .claude/commands/ solo se activan cuando las llamás explícitamente.

Error 4: No versionar las rutinas

Esto me costó caro. Actualicé unas instrucciones, rompí el comportamiento que tenía funcionando, no recordaba qué había cambiado. Las rutinas son código — van al repositorio, tienen history, tienen commits descriptivos. "chore: actualizar instrucciones de review para incluir check de accesibilidad" es un commit tan válido como cualquier otro.

Lo mismo que con sistemas distribuidos donde el estado compartido sin control de versiones genera condiciones de carrera — algo que analicé en detalle en el post sobre desarrollo multi-agente como problema de sistemas distribuidos.

Lo que cambió concretamente en mi workflow

Antes: cada sesión empezaba con cinco minutos de "este proyecto usa TypeScript estricto, la DB está en Railway, los componentes van en /components, si hay validación usá Zod". Repetición pura.

Después: Claude ya sabe todo eso. La sesión empieza en el problema.

El cambio más inesperado fue en code review. Tengo un equipo y los PRs son donde más tiempo se gasta. Con la rutina de review definida, Claude revisa con consistencia real — no depende de mi humor ni de si es viernes a las 6pm. Los criterios son los mismos siempre.

Sobre consistencia en herramientas de análisis: trabajando con benchmarks de seguridad como N-Day-Bench para vulnerabilidades, el contexto persistente sobre qué tipo de análisis querés — y qué no — es crítico para no perder tiempo en falsos positivos.

El otro cambio fue en proyectos complejos con decisiones de arquitectura no obvias. Cuando estaba explorando opciones de runtime de Rust para TypeScript, tener documentado en las rutinas por qué ciertas decisiones se tomaron previene que Claude — o cualquier colaborador — las revierta por refactoring bien intencionado.

FAQ: lo que más me preguntaron cuando compartí esto

¿Las rutinas de Claude Code funcionan en todos los proyectos o solo en los grandes?

Funcionan especialmente bien en proyectos que duran más de una semana o donde trabajás con un equipo. Para un script de un día, es overhead real. Para cualquier cosa con más de 20 archivos y convenciones propias, el ROI es positivo desde la primera semana. El threshold bajó cuando entendí que el setup inicial son 30 minutos, no horas.

¿CLAUDE.md reemplaza al README del proyecto?

No, son documentos con propósitos distintos. El README explica el proyecto para humanos que llegan nuevos. CLAUDE.md le explica a Claude cómo trabajar con vos en ese proyecto. Pueden tener superposición pero no son intercambiables. Yo mantengo ambos separados.

¿Qué pasa si varios devs del equipo tienen estilos distintos en las rutinas?

Las rutinas que van al repositorio (.claude/ y CLAUDE.md) son decisiones del equipo, como cualquier configuración de linter o prettier. Se discuten, se acuerdan, se versionen. Las preferencias personales van en configuración local que no se commitea. El mismo principio que con .gitignore.

¿Las rutinas afectan el consumo de tokens/costo?

Sí, agregan tokens en cada request porque el contexto se incluye. En la práctica el costo es menor que el ahorro de no tener que re-explicar contexto en cada sesión. Eso también consume tokens. La diferencia es que con rutinas el contexto es preciso y relevante — sin rutinas, tu explicación informal probablemente es más larga y menos útil.

¿Puedo usar rutinas para proyectos con hardware o cosas no convencionales?

Absolutamente. El contexto no tiene que ser solo sobre código. Para proyectos como displays de hardware con aire comprimido, podés documentar las restricciones físicas del sistema, los rangos de operación seguros, qué no tocar porque implica consecuencias en el mundo físico. Claude necesita ese contexto tanto como lo necesita para un proyecto de software puro.

¿Hay algún límite en el tamaño de CLAUDE.md?

Técnicamente no hay un límite duro documentado, pero pragmáticamente: si tu CLAUDE.md supera las 500 líneas, algo está mal. O estás documentando todo en un solo archivo cuando deberías separar en comandos específicos, o estás incluyendo información que no es instruccional sino documental. Yo mantengo el CLAUDE.md global bajo 150 líneas y el resto en archivos específicos por tarea.

La resistencia era mía — y eso es el punto

Hay una trampa cognitiva en la que caemos los que llevamos muchos años haciendo esto: confundir experiencia con eficiencia. Saber hacer algo rápido no significa que no pueda hacerse mejor.

Me pasó a los 16 en el cyber — diagnosticaba cortes de conexión de memoria, sin documentación, sin proceso. Funcionaba. Hasta que a las 11pm con el local lleno y tres máquinas caídas me di cuenta de que un checklist de 10 minutos preparado de antemano me hubiera salvado 40 minutos de caos.

Las rutinas de Claude Code son ese checklist. No son para principiantes que no saben lo que hacen. Son para cualquiera que quiera que su herramienta trabaje con el contexto correcto desde el primer mensaje, no desde el quinto.

El overhead que temía resultó ser 30 minutos de setup inicial y 5 minutos de mantenimiento por semana. Lo que recupero es tiempo real en cada sesión de trabajo.

¿Ya configuraste rutinas en tu workflow con Claude Code? ¿O también estabas en modo resistencia como yo? Contame en los comentarios qué instrucciones resultaron ser las más útiles — me interesa especialmente si trabajás con stacks no convencionales.