Blog | Empleados, tecnología, noticias, eventos | Mimacom

No le pidas a tu asistente de IA que recuerde. Haz que cumpla.

Escrito por Raúl Avilés Saltos | 18 nov 2026, 7:00:01

Los asistentes de programación con IA permiten que cualquiera modifique un código base, incluso quien nunca ha visto las convenciones del equipo. Raúl Avilés Saltos, ingeniero de software, explica por qué añadir más instrucciones a CLAUDE.md no resuelve el problema y cómo su equipo usó los hooks y las reglas de Claude Code para que esas convenciones se apliquen a todas las personas que contribuyen, las conozcan o no.

Puntos clave

  • Con los asistentes de programación con IA, más personas pueden contribuir a un código base, pero las instrucciones de CLAUDE.md son contexto, no una obligación, así que Claude solo las sigue a veces.
  • En su proyecto actual, Raúl trasladó las convenciones del equipo al repositorio: los hooks se ejecutan en cada edición para pasar el linter a los archivos, bloquear el acceso a secretos e imponer límites de negocio, y las reglas le dan a Claude las convenciones adecuadas cuando trabaja con un archivo que coincide.
  • El resultado son menos comentarios repetidos en los PR: en los dos meses posteriores al cambio, los comentarios de revisión sobre convenciones en los PR de frontend del equipo bajaron de 12 en 88 PR a tres en 110. Las convenciones se aplican ahora a todas las personas que contribuyen, y las salvaguardas para los datos, la seguridad y el dinero ya no dependen del criterio del modelo.

Es lunes por la mañana y llega un pull request que no es de tu equipo.

Quizá alguien de backend necesitaba un pequeño arreglo en el frontend, o alguien nuevo está en su primera semana, o una persona de otro equipo tocó el código una vez y nunca lo volverá a ver. Todos hicieron lo mismo: abrieron el repositorio, le pidieron el cambio a Claude e hicieron push.

El código funciona, pero el PR llega con archivos sin formatear, un aviso del linter que nadie revisó y un px donde el equipo acordó usar rem hace meses. Ninguno de estos problemas es grave, pero todos acaban en manos de quien revisa.

Esta es la situación que los asistentes de programación con IA han creado sin hacer ruido. Escribir código ya no es cosa exclusiva de quienes conocen el proyecto, porque cualquiera con acceso y un asistente puede contribuir. Eso supone una ganancia real de velocidad y también un riesgo real para la coherencia, porque las convenciones que mantienen sano un código base suelen vivir en una página del wiki que nadie abre, en la cabeza de dos desarrolladores senior y en comentarios repetidos en los PR.

Nuestro proyecto es una app con la que el personal del sector sanitario suizo planifica turnos y registra su jornada. Está desarrollada con Angular, Ionic y Capacitor para web, iOS y Android, dentro de un monorepo más grande de Java/Spring. La app tiene unos 275 componentes, y en los últimos seis meses han hecho commits 13 personas: desarrolladores de frontend, desarrolladores de backend que de vez en cuando arreglan algo en el frontend y desarrolladores de otros equipos. Es el lunes por la mañana del principio, todas las semanas.

Lo resolvimos con dos funciones de Claude Code: los hooks y las reglas (rules). Este artículo explica qué cambió en la práctica, por qué la solución habitual de escribir más instrucciones no funciona y cómo un enfoque basado en barreras de protección hace que las convenciones se apliquen a todo el mundo, las conozca o no.

 

El problema: las instrucciones son sugerencias

El primer instinto siempre es el mismo: si Claude no sigue una convención, se escribe. Se añade una línea a CLAUDE.md, el archivo que Claude Code lee al inicio de cada sesión:

Formatea con Prettier, ejecuta ESLint y comprueba los tipos.

Cuando eso falla, se repite. Luego se escribe en mayúsculas. Más abajo en el archivo, después de 200 líneas de otras instrucciones, aparece algo así:

RECUERDA: NUNCA HAGAS X. EN SERIO, NUNCA.

Escribirlo en mayúsculas no lo hace más obligatorio, solo más ruidoso. No es una crítica al modelo, sino la forma en que está diseñado el mecanismo. La documentación de Claude Code lo deja claro: Claude trata los archivos CLAUDE.md «como contexto, no como configuración obligatoria», y «para bloquear una acción independientemente de lo que decida Claude, usa un hook PreToolUse» (documentación de Claude Code, memoria).

Una instrucción en un prompt compite con todo lo demás que hay en la ventana de contexto y, en una sesión larga con mucho código de por medio, su peso cambia. A veces el asistente formatea el archivo y a veces no, según el día, el contexto y si alguien se lo recordó tres mensajes antes. Eso es un comportamiento probabilístico, y para una convención de equipo lo que quieres es un comportamiento determinista.

 

El cambio: un disparador en el ciclo de vida del agente

Para entender dónde encajan los hooks, conviene ver qué pasa cuando envías un prompt a Claude Code. No es magia, solo un bucle: escribes algo, el agente decide si necesita una herramienta (leer un archivo, editar un archivo, ejecutar un comando), la usa, mira el resultado y repite hasta que puede responder.

Aquí importan dos momentos de ese bucle: justo antes de que se ejecute una herramienta y justo después. Claude Code expone ambos como eventos, PreToolUse y PostToolUse (documentación de Claude Code, hooks). Si has trabajado con un framework de frontend, ya conoces el concepto. Es un lifecycle hook, como useEffect en React, mounted en Vue o ngOnInit en Angular, aplicado al ciclo de vida del agente en lugar del de un componente.

Un hook es un script con un disparador. Lo registras una vez en .claude/settings.json, que se sube al repositorio con el proyecto, y a partir de ahí se ejecuta cada vez que se produce su evento. No es una sugerencia que el modelo pueda sopesar frente a otro contexto: es código que se ejecuta. La diferencia entre los dos eventos importa. PreToolUse se ejecuta antes de la acción, así que puede bloquearla. PostToolUse se ejecuta después, así que no puede deshacerla, pero sí corregir el resultado o informar sobre él.

 

La aplicación: tres barreras de protección

Contamos cada caso con la misma estructura en cuatro pasos: el problema real, el intento habitual, el hook y el resultado. Uno de los ejemplos viene de nuestro propio proyecto, y los otros dos muestran cómo el mismo patrón se aplica a los secretos y a las reglas de negocio.

 

Ejemplo 1: linting automático después de cada edición

El problema. Nuestro equipo ya tenía una checklist: formatear, pasar el linter y comprobar los tipos. Todo el equipo principal la conocía bien. El problema nunca fue conocer los pasos, sino que no todo el mundo los seguía. Cuando alguien nuevo se incorpora y nadie le explica el proceso, o alguien de otro equipo corrige un solo bug, Prettier y ESLint se quedan sin ejecutar y nadie comprueba los tipos. El resultado son PR llenos de ruido en los que quien revisa no distingue los cambios reales de los de formato.

El intento habitual. Una línea más en CLAUDE.md, fácil de saltarse y fácil de olvidar en cuanto el contexto se alarga.

El hook. En su lugar, registramos un hook PostToolUse que se activa cada vez que Claude edita o crea un archivo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-check-changed-file.sh"
          }
        ]
      }
    ]
  }
}

La configuración tiene tres partes y nada más: el evento (PostToolUse, después de editar o crear), el matcher (Edit|Write, para que solo se active con esas herramientas) y el comando, que apunta a un script del proyecto. El script recibe la ruta del archivo editado como JSON por la entrada estándar. Ejecuta Prettier y eslint --fix solo sobre ese archivo, luego ejecuta tsc y filtra la salida para quedarse con los errores de ese archivo. Si algo no se puede corregir automáticamente, el informe vuelve a Claude, que lo corrige en la misma sesión.

El resultado. Las mismas tres comprobaciones se ejecutan ahora después de cada edición, escriba quien escriba: la persona recién incorporada, el colaborador externo que toca el código una sola vez o tú, un viernes por la tarde. Nadie tiene que acordarse de nada, y de eso se trata.

 

Ejemplo 2: bloquear el acceso a secretos

El problema. La misma historia, otro archivo. Una persona externa recibe acceso para un solo PR, o alguien nuevo está en su primera semana, y Claude lee el archivo .env mientras explora el proyecto. Ni siquiera a propósito, sino porque nadie dijo que estaba prohibido.

El intento habitual. Pedirlo con amabilidad: «Por favor, no leas ni edites el archivo .env». Pero una petición no es un muro. Es una puerta abierta con una nota adhesiva que dice «prohibido el paso».

El hook. La misma estructura, otro evento:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-env.sh"
          }
        ]
      }
    ]
  }
}

Esta vez el evento es PreToolUse, así que el script se ejecuta antes de la acción y puede ser muy corto:

#!/usr/bin/env bash
file_path="$(jq -r '.tool_input.file_path // empty')"

if [[ "$(basename "$file_path")" == .env* ]]; then
  echo "El acceso a los archivos .env está bloqueado por la política del proyecto." >&2
  exit 2
fi

exit 0

El resultado. El código de salida 2 bloquea la llamada a la herramienta, así que la lectura nunca ocurre, y el mensaje de la salida de error estándar vuelve a Claude como motivo (documentación de Claude Code, hooks). Claude recibe una explicación clara y sigue adelante. Para un simple bloqueo de rutas, Claude Code también ofrece reglas permissions.deny en la configuración. Un hook es la mejor opción cuando la decisión necesita lógica, como en el siguiente ejemplo.

 

Ejemplo 3: el muro de los 100 $

El contexto. Los hooks no se limitan al estilo del código: el mismo patrón sirve para las reglas de negocio de cualquier agente que llame a herramientas. Imagina un agente que gestiona los reembolsos de una tienda online. La regla de negocio es sencilla: hasta 100 $, el agente resuelve el reembolso por su cuenta; por encima de 100 $, primero tiene que aprobarlo una persona.

El intento habitual. Poner la regla en el prompt del agente, luego repetirla y luego escribirla en mayúsculas. Sigue siendo un prompt, no una regla, y esta vez hablamos de dinero real, no de un px.

El hook. Un hook PreToolUse sobre la herramienta de reembolsos. Si la herramienta se expone a través de un servidor MCP llamado shop, Claude Code la llama mcp__shop__process_refund, y a eso apunta el matcher:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__shop__process_refund",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-refund.sh"
          }
        ]
      }
    ]
  }
}

El script decide, no sugiere:

#!/usr/bin/env bash
input="$(cat)"

if jq -e '.tool_input.amount > 100' >/dev/null <<<"$input"; then
  cat <<'EOF'
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Los reembolsos de más de 100 $ requieren revisión humana."
  }
}
EOF
fi

exit 0

El resultado. Por debajo del umbral, el hook no interviene y el reembolso sigue el flujo normal. Por encima, la llamada se rechaza con un motivo que el agente puede trasladar al cliente y al proceso de escalado. No le pidas al agente con educación que no se salga del presupuesto: pon un muro en los 100 $.

 

Una regla práctica para saber cuándo necesitas un hook

Si has escrito «IMPORTANTE» dos veces en CLAUDE.md, esa es la señal. Las mayúsculas indican que quieres determinismo, no un prompt más convincente, así que lo que necesitas es un hook, no otro párrafo.

 

Reglas: las convenciones que antes vivían en la cabeza de alguien

Los hooks obligan, pero mucho de lo que hace coherente un código base no se puede reducir a un script: la nomenclatura, la arquitectura de componentes, las convenciones de las API y los design tokens. Ese conocimiento hay que explicarlo en el momento adecuado, y para eso están las reglas. Una regla es un archivo Markdown en .claude/rules/. Con un campo paths en su frontmatter, solo se carga en el contexto cuando Claude trabaja con un archivo que coincide (documentación de Claude Code, reglas por ruta):

---
paths:
  - 'src/**/*.scss'
---

Usa rem para width, height, font-size y otras propiedades de tamaño.
Excepciones: border y box-shadow se quedan en px.
Usa los tokens de color de la guía de estilo en lugar de valores hexadecimales fijos.

A diferencia de CLAUDE.md, una regla no se carga al inicio de cada sesión. Aparece cuando el archivo que estás tocando coincide con el patrón, así que las convenciones de SCSS aparecen cuando Claude abre una hoja de estilos, no cuando está escribiendo un test unitario.

Un ejemplo real. Cuando me incorporé al proyecto, mi primer PR recibió un comentario: «usa rem, no px». Lo corregí, y en mi segundo PR recibí el mismo comentario. La convención no vivía en el proyecto, sino en la cabeza de quien revisaba. Cuando se convirtió en una regla, el comentario dejó de aparecer. No porque yo lo hubiera aprendido, sino porque ya no dependía de que me acordara. Es un ejemplo trivial, pero real.

El mismo mecanismo sirve para cualquier convención. Ahora tenemos reglas separadas para SCSS, TypeScript y plantillas HTML, creadas en parte a partir de comentarios recurrentes en los PR y de hallazgos del análisis estático, y cada una solo se carga cuando es relevante. Quien llega de otro equipo o acaba de incorporarse no conoce estas reglas, pero las sigue igualmente, sin sesión de onboarding ni página del wiki. La regla vive en el repositorio, y el repositorio no olvida.

Una advertencia honesta: una regla sigue siendo contexto, no una obligación. Hace mucho más probable el comportamiento correcto porque pone la convención delante del modelo en el momento adecuado. Cuando «mucho más probable» no basta, es trabajo para un hook.

 

En resumen: las reglas explican, los hooks obligan

Los dos mecanismos resuelven mitades distintas del mismo problema. Las reglas convierten una convención en texto que Claude lee justo cuando importa, y los hooks la convierten en código que se ejecuta pase lo que pase. Ninguno sustituye al otro. Una forma útil de decidir: si saltarse la convención es una molestia, una regla suele bastar. Si cuesta dinero, expone datos o bloquea una release, necesita un hook.

El cambio de fondo está en dónde viven las convenciones. Antes vivían en las personas: en quienes revisan, en los desarrolladores senior y en las sesiones de onboarding. Ahora viven en el repositorio, versionadas y revisadas como cualquier otro código. Los equipos dieron este mismo paso hace años con los pipelines de CI y los linters, y esto lo aplica a un nuevo tipo de colaborador.

 

Qué significa esto para los equipos

Para quienes desarrollan, el trabajo diario cambia en detalles pequeños pero notables. Dejas de perseguir al asistente para que corrija los tipos, pase el linter y formatee el archivo, y las revisiones se centran en la lógica en lugar del estilo. Además, dejas de escribir el mismo comentario en un PR por quinta vez.

Para tech leads y arquitectos, la pregunta ya no es «¿cómo nos aseguramos de que todo el mundo conoce las convenciones?», sino «¿qué convenciones están codificadas en el repositorio?». La segunda pregunta es mucho más fácil de responder y de auditar. Las barreras de protección son visibles en .claude/, se revisan en los PR y se aplican igual a todas las personas que contribuyen, internas o externas.

Para quienes toman decisiones, esto es lo que hace seguro abrir un código base a más colaboradores. Los asistentes de IA reducen la barrera para contribuir, algo útil cuando los equipos comparten código entre productos o incorporan apoyo temporal. Los hooks y las reglas garantizan que esa barrera más baja no se pague en calidad, seguridad o reglas de negocio, porque las reglas que más importan no quedan a criterio del modelo.

Lo que ha cambiado en nuestro proyecto es que hay menos ruido. Las reglas y los hooks entraron juntos en el repositorio el 26 de agosto. En los 66 días anteriores hubo 12 comentarios de revisión sobre convenciones en 88 PR de frontend, como px en lugar de rem, inject() en lugar del constructor, la nomenclatura o la estructura de carpetas. Eso es aproximadamente uno cada siete PR. En los 66 días posteriores hubo tres en 110 PR, aproximadamente uno cada 37. No se cuentan los comentarios de bots de revisión. La muestra es pequeña y en el mismo periodo cambiaron otras cosas, como quién revisaba y la incorporación de un bot de revisión automática, así que no es un resultado controlado. Pero coincide con lo que el equipo ha notado: menos comentarios repetidos en los PR, convenciones que ya no hace falta explicar y errores que nunca llegan a revisión porque nunca se producen.

 

Por dónde empezar: convierte las instrucciones en barreras de protección

Lo más fácil es empezar por tu propio CLAUDE.md. Cada «NUNCA» y cada «SIEMPRE» que contiene es candidato a un hook, porque las mayúsculas muestran dónde quieres una garantía y no un recordatorio. Un único hook PostToolUse que formatee y pase el linter al archivo editado es un primer paso de bajo riesgo. PreToolUse es el evento adecuado para todo lo que no debe ocurrir, como leer secretos o superar un umbral de negocio.

Para las convenciones que no se pueden convertir en script, mira los comentarios de tus PR. Si has escrito el mismo comentario dos veces en una revisión, escríbelo una sola vez como regla por ruta en .claude/rules/. Y luego haz commit de todo, porque las barreras de protección solo funcionan para todas las personas que contribuyen si viven en el repositorio.

No le pidas que recuerde. Haz que cumpla.