SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor · Actualizado 2026-10-26

Por qué los agentes de código ignoran instrucciones

Si tu archivo dice que el agente debe parar y no lo hace, descubre si la regla quedó fuera del contexto, era ambigua, fue contradicha o perdió prioridad.

Por qué los agentes de programación ignoran sus instrucciones

Los agentes de programación ignoran sus instrucciones por cuatro motivos, y ninguno es que haya sido demasiado cortés. La regla nunca estuvo en la ventana de contexto. La regla era demasiado imprecisa para comprobar una acción con respecto a ella. Otro elemento del contexto la contradecía, normalmente el código que el agente acababa de leer. O la regla sigue cargada, pero está muy atrás en el turno actual, y el agente trabaja con lo que tiene más cerca.

Cada causa tiene su propia solución, así que el primer trabajo consiste en distinguirlas. Las mayúsculas y la palabra IMPORTANT no permiten establecer un diagnóstico. Los mecanismos siguientes usan Claude Code como ejemplo práctico, porque su comportamiento de carga y compactación está documentado con detalle a fecha de octubre de 2026. Otras herramientas difieren en los detalles, pero en líneas generales se comportan de la misma forma.

Primero, dos términos. La ventana de contexto es el bloque de texto que el modelo ve en un turno determinado: el system prompt, sus archivos de instrucciones, la conversación y todos los archivos que el agente ha leído. El harness es el programa que rodea al modelo, es decir, el componente que lee archivos del disco y ensambla ese bloque. Casi todas las quejas de esta publicación son en realidad quejas sobre el harness, no sobre el modelo.

El archivo de instrucciones es un mensaje, no una configuración

Un archivo de instrucciones no es una configuración. Nada en el entorno de ejecución lee CLAUDE.md y lo aplica. El arnés lee el archivo del disco y pega el texto en la conversación. En Claude Code, ese contenido se entrega como un mensaje de usuario situado después del aviso del sistema. Por tanto, el modelo ve las reglas del mismo modo que ve cualquier otro texto que haya escrito.

Esto tiene una consecuencia incómoda. Las reglas compiten con cualquier otro fragmento de texto de la ventana en igualdad de condiciones. Una regla es una afirmación. El archivo que el agente acaba de abrir es una evidencia. Cuando ambos discrepan, la evidencia suele imponerse. No se genera ningún error, porque desde el punto de vista del modelo no ha ocurrido nada incorrecto.

La documentación oficial lo indica claramente: los archivos de instrucciones se tratan como contexto, no como configuración aplicada. Para bloquear una acción independientemente de lo que decida el modelo, necesita un hook, no una frase. Conserve esa idea. La mayoría de las correcciones del final de este artículo aplican esa idea a un caso concreto.

Qué archivos de instrucciones se cargan y cuándo

Claude Code sube por el árbol de directorios desde el directorio en el que lo inició. Todos los archivos CLAUDE.md y CLAUDE.local.md, desde la raíz del sistema de archivos hasta el directorio de trabajo, se cargan completos al iniciar. Se concatenan en ese orden. Por tanto, el archivo más cercano al directorio desde el que inició se lee en último lugar. Dentro de un mismo directorio, el archivo .local se añade después del archivo principal.

Los archivos de los subdirectorios por debajo del directorio de trabajo se comportan de otra forma. No se cargan al iniciar. Se cargan cuando el agente lee un archivo de ese directorio. Lo mismo ocurre con las reglas limitadas por ruta de .claude/rules/ que incluyen un campo de frontmatter paths:: entran en el contexto cuando se lee un archivo coincidente, no en cada turno. Desde v2.1.309, los archivos que se cargan de esta forma también tienen un límite de tamaño por archivo (40,000 caracteres con una ventana de contexto de 200K). El agente sólo recibe el principio de un archivo más largo, por lo que las reglas situadas cerca del final de un archivo anidado grande quizá nunca lleguen al contexto.

Esta diferencia explica una parte importante de los fallos notificados. Coloca una regla en packages/api/CLAUDE.md, hace una pregunta sobre la API y el agente responde sin abrir ningún archivo de packages/api/. La regla no se ignoró. Nunca estuvo presente. Si el repositorio distribuye las instrucciones entre archivos de instrucciones por paquete en un monorepo, esto es lo primero que debe comprobar, siempre.

Hay otra trampa de carga en los repositorios que estandarizaron AGENTS.md. Desde v2.1.277, Claude Code lee AGENTS.md como instrucciones del proyecto de forma predeterminada, pero sólo cuando no existe CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo ni en ningún directorio superior (su ~/.claude/CLAUDE.md personal no cuenta). Añada cualquiera de esos archivos, incluso un CLAUDE.local.md para notas personales, y Claude Code leerá en su lugar los archivos CLAUDE.md y omitirá por completo AGENTS.md. Para cargar ambos, establezca Project instructions en claude-md-and-agents-md dentro de /config. En versiones anteriores a v2.1.277, o cuando quiera conservar un CLAUDE.md, el mecanismo de enlace es un CLAUDE.md cuya primera línea es @AGENTS.md. Esto importa el archivo al iniciar, con cualquier nota específica de Claude debajo. Un enlace simbólico también funciona si no necesita añadir nada. Decidir qué debe incluirse en ese archivo es otra cuestión, que se trata en separar las instrucciones del agente de la documentación para personas.

Confirme que el archivo se ha cargado antes de reescribirlo

No modifique el texto hasta tener pruebas de que el agente puede ver el archivo. Hay dos comprobaciones, y la más sencilla se hace primero.

Ejecute /context dentro de la sesión. Muestra la ventana actual desglosada por categoría, y la lista Memory files indica todos los archivos de instrucciones cargados al iniciar. Si un archivo no aparece en esa lista, no se cargó al iniciar. Por tanto, nada de lo que escriba en él tendrá efecto hasta que algo lo cargue. Un archivo anidado en un subdirectorio nunca aparece ahí porque se carga bajo demanda. Cuando se carga, aparece en el terminal una línea Loaded con su ruta. /memory muestra las ubicaciones de los archivos y los abre para editarlos, incluidos los que todavía no existen.

Para obtener una confirmación más detallada, registre las cargas. El evento de hook InstructionsLoaded se ejecuta cada vez que un CLAUDE.md o un archivo de reglas entra en el contexto. Su matcher indica por qué se produjo la carga: session_start, nested_traversal, path_glob_match, include o compact. Coloque esto en .claude/settings.json:

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "matcher": "nested_traversal",
        "hooks": [
          {
            "type": "command",
            "command": "cat >> /tmp/instructions-loaded.log"
          }
        ]
      }
    ]
  }
}

El hook recibe los datos en formato JSON mediante la entrada estándar, por lo que cat añade el registro completo. Supervise el archivo con tail -f /tmp/instructions-loaded.log mientras trabaja. El estado de salida de este evento se ignora. Por tanto, el hook sólo puede observar, no bloquear. Si el archivo anidado nunca aparece en ese registro durante una sesión en la que esperaba que se cargara, deje de reescribir el texto. El problema está en la ubicación. Hay una excepción: un AGENTS.md que Claude Code lee directamente no activa este evento. En ese caso, busque su ruta en /memory. Un AGENTS.md importado desde un CLAUDE.md sí activa el evento con normalidad.

Qué efecto tiene una sesión larga en las reglas

Aquí se aplican dos efectos distintos y requieren respuestas diferentes.

Distancia. Hasta que se ejecuta una compactación, una regla indicada en el turno 1 sigue en la ventana en el turno 90, pero ahora compite con 90 turnos de texto más reciente y más específico de la tarea que está realizando. Después de una compactación, una regla que sólo escribió en el chat puede no estar en la ventana. La documentación de Claude Code advierte que las instrucciones de las primeras partes de la conversación pueden perderse. Este es el segundo efecto que se explica a continuación. No puede eliminar la distancia mediante la configuración, pero sí puede medirla. Ejecute la misma tarea en una sesión nueva. Si la regla se cumple allí y falla en una sesión larga, la causa es la distancia o la compactación.

Compactación. Cuando la ventana se llena, el arnés resume la conversación hasta ese momento y continúa a partir de ese resumen. Lo que permanece es lo que el resumidor consideró importante, y no necesariamente lo que usted considera importante. Claude Code documenta el resultado de cada mecanismo, y las diferencias son grandes. La raíz del proyecto CLAUDE.md y las reglas sin ámbito se vuelven a inyectar desde el disco después de una compactación. La memoria automática se vuelve a inyectar desde el disco. Las reglas con frontmatter paths: se pierden hasta que se vuelva a leer un archivo coincidente. Los archivos CLAUDE.md anidados en subdirectorios se pierden hasta que se vuelva a leer un archivo de ese subdirectorio.

Ordene las instrucciones según esa tabla y el orden de fragilidad será evidente. Una regla que sólo escribió en el chat es el elemento más frágil de la sesión: sólo permanece si el resumen la conserva. Una regla en packages/api/CLAUDE.md ocupa el siguiente lugar, porque se cargó una vez, se eliminó al resumir y sólo vuelve a aparecer en la siguiente lectura de ese directorio. Una regla del archivo de la raíz del proyecto es la más duradera, porque se vuelve a leer desde el disco cada vez.

Por tanto, si una instrucción debe mantenerse durante toda la sesión, debe estar en el archivo de la raíz del proyecto sin frontmatter paths:. Todo lo demás implica una decisión de compromiso que debe tomar de forma deliberada. Administrar lo que permanece en la ventana de contexto trata /compact con un argumento de enfoque y /clear entre tareas no relacionadas. Ambos factores cambian la frecuencia con la que el resumidor puede decidir qué contenían sus reglas.

Por qué el código circundante prevalece sobre la regla

Este es el fallo que más se describe y que menos se diagnostica. El archivo indica que el acceso a la base de datos pasa por la capa de repositorios. El agente escribe un controlador que llama directamente al ORM (mapeador objeto-relacional). No ignoró la instrucción por motivos de estilo. La evidencia tenía más peso.

Una regla describe una preferencia. El código demuestra una preferencia. Cuando el agente abre tres archivos del módulo que está a punto de editar y los tres llaman directamente al ORM, el contexto contiene una frase abstracta a un lado y tres ejemplos concretos, recientes y relacionados con la tarea al otro. Copiar el patrón local suele ser el comportamiento correcto. En este caso es incorrecto sólo porque usted sabe algo que el contexto desconoce: esos archivos son código heredado.

Por tanto, escríbalo en la regla. Las reglas que mencionan sus propias contradicciones sobreviven al contacto con un repositorio real. Las reglas que expresan una preferencia sin más no lo hacen.

El acceso nuevo a la base de datos pasa por app/repositories/. Los archivos bajo app/legacy/ siguen llamando directamente al ORM. Es código antiguo, no el patrón que se debe seguir. No lo copie.

La segunda frase es la que cumple la función principal. Indica al agente qué está a punto de encontrar y cómo debe interpretarlo antes de que lo encuentre. La misma corrección se aplica a cualquier regla que el repositorio contradiga de forma visible: un estilo de commits que no sigue el historial, una estructura de pruebas que la mitad de la suite ignora o una convención de imports que sólo se aplica al código nuevo. Cuando el código no coincide con el archivo, indique la discrepancia en el archivo.

Una regla imprecisa no se puede comprobar, por lo que no se puede seguir

"Escriba código limpio." "No haga ingeniería excesiva." "Manténgalo simple." "Tenga cuidado con las migraciones." Ninguna de estas reglas se puede comprobar con una acción concreta, ni por parte del agente ni por su parte. Si un agente recibe una regla que no puede comprobar en su propia salida, está adivinando, y usted evalúa esa suposición según su impresión.

Aplique esta prueba a cada línea de su archivo. Escriba el comando de shell que terminaría con un código distinto de cero cuando se incumpla la regla. Si no puede escribir ese comando, la regla no se puede comprobar. Compare estos pares:

  • No comprobable: "Mantenga las funciones pequeñas." Comprobable: "Una función de más de 60 líneas necesita un comentario encima que explique el motivo."
  • No comprobable: "Pruebe los cambios." Comprobable: "Ejecute npm test y pegue el número de fallos antes de marcar una tarea como terminada."
  • No comprobable: "Mantenga los archivos organizados." Comprobable: "Los manejadores HTTP están en src/api/handlers/. No coloque nada más en ese directorio."
  • No comprobable: "Formatee el código correctamente." Comprobable: "Use una indentación de 2 espacios en los archivos .ts."

"No haga ingeniería excesiva" es la regla que la gente abandona primero, porque la solución no es una frase más corta, sino una más larga: especificar qué significa realmente el cambio mínimo que funciona proporciona al agente criterios con los que puede comparar su propio diff.

El tamaño plantea el mismo problema con otra apariencia. Las directrices de Claude Code recomiendan menos de 200 líneas por archivo de instrucciones y afirman directamente que los archivos más largos reducen el cumplimiento. Un archivo de 700 líneas no contiene instrucciones más firmes. Contiene 700 afirmaciones con más posibilidades de contradecirse, y consume espacio de contexto en cada turno, lo que se refleja directamente en el uso de tokens. Estructurar el archivo para que cada regla aparezca bajo un encabezado que el lector pueda localizar rápidamente se explica en cómo escribir un archivo de instrucciones que el agente pueda ejecutar. Mejor aún, elimine las partes descriptivas que no contienen instrucciones: un recorrido por los directorios donde se encuentran los manejadores y los modelos es información estructural que el agente puede consultar cuando la necesite a partir de un mapa analizado del repositorio, en lugar de conservarla en el contexto en cada turno.

Cómo diagnosticarlo en diez minutos

Ejecute estos comandos en orden. Saltar directamente al último paso suele producir un archivo extenso de reglas enfáticas que sigue sin funcionar.

  1. Confirme que se cargó. Ejecute /context y revise la lista Memory files, o, si se trata de un archivo anidado, busque su línea Loaded en el terminal. Si el archivo no aparece, corrija la ubicación y deténgase. Nada más de esta lista se aplica todavía.
  2. Reproduzca el problema en una sesión nueva. Inicie una sesión nueva y asigne la tarea más pequeña que debería activar la regla. Si funciona al principio pero falla en una sesión larga, el problema apunta a la distancia o a la compactación. Si también falla aquí, el problema está en la propia regla.
  3. Elimine la competencia. Solicite el mismo cambio en un directorio cuyo código existente ya siga la regla. Si vuelve a cumplirse, el código circundante estaba imponiéndose a su instrucción.
  4. Busque un conflicto. Dos archivos que proporcionan indicaciones distintas para el mismo comportamiento constituyen un fallo documentado: el modelo puede elegir uno de forma arbitraria y no le informará de ello.
  5. Haga que se pueda comprobar y vuelva a probar. Reescriba la regla con una ruta concreta y una condición. Un aumento considerable del cumplimiento indica que la causa era la redacción.

El paso 4 consiste en ejecutar un comando. Busque el tema en todas las fuentes de instrucciones, no sólo en el archivo que estaba editando:

grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null

Un resultado en dos archivos con indicaciones distintas es el error. Elimine una de ellas. No intente establecer una prioridad mediante una redacción más contundente, porque no existe ningún motor de prioridades al que recurrir. En Claude Code v2.1.283 o posterior, /doctor prompt-audit ejecuta una versión más amplia de esta búsqueda en los archivos de instrucciones, las reglas y las skills, e informa de las contradicciones con propuestas de edición sin cambiar nada hasta que usted lo solicite.

Las correcciones, en orden de eficacia

Cada paso siguiente ofrece más eficacia que el anterior y requiere más trabajo de configuración. Empiece por arriba cuando sea barato reformular una regla. Baje al siguiente nivel en cuanto la regla sea lo bastante importante como para que no se acepten omisiones ocasionales.

  1. Haga concreta la regla. Indique una ruta, un comando o una condición. Añada las pruebas en sentido contrario que el agente encontrará en el repositorio, como se mostró antes. No cuesta nada y resuelve una proporción sorprendente de casos.
  2. Acérquela a aquello que regula. Puede usar un CLAUDE.md anidado, una regla limitada a una ruta en .claude/rules/ o un comentario al principio del propio archivo. La regla se carga junto con el código al que se aplica. Acepte la contrapartida: todo lo que se cargue de ese modo se pierde en la siguiente compactación y vuelve a aparecer en la siguiente lectura coincidente.
  3. Traslade la aplicación de la regla a un hook. La prosa solicita. Un hook decide. Los hooks se ejecutan como código en eventos fijos del ciclo de vida y se aplican independientemente de la conclusión del modelo.
  4. Asigne la regla a una herramienta determinista y elimine la prosa. Formato, orden de imports, longitud de línea, imports prohibidos y formato de los mensajes de commit. ruff format, prettier --write, eslint o un hook de pre-commit. El formateador acierta siempre y no consume tokens. La frase acierta la mayoría de las veces y consume tokens en cada turno.

Paso 3 completo. Suponga que el agente no debe editar nunca los archivos de migración. Añada esto a .claude/settings.json:

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

Y esto a .claude/hooks/guard-migrations.sh:

#!/usr/bin/env bash
set -euo pipefail

path=$(jq -r '.tool_input.file_path // empty')

case "$path" in
  */migrations/*)
    echo "Files under migrations/ are written by hand. Stop and ask first." >&2
    exit 2
    ;;
esac

exit 0

Ejecute chmod +x .claude/hooks/guard-migrations.sh, inicie una sesión nueva y pida al agente que edite un archivo bajo migrations/. La edición se rechaza y el mensaje vuelve con el motivo. Un estado de salida 2 en PreToolUse bloquea la llamada a la herramienta antes de su ejecución, y el texto de stderr se entrega al modelo como mensaje de bloqueo. ${CLAUDE_PROJECT_DIR} se resuelve en la raíz del proyecto, por lo que el hook funciona independientemente del directorio en el que se encuentre el agente. El agente no tiene que estar de acuerdo con la regla, recordarla ni conservarla en el contexto. La edición no se realiza.

Para una prohibición simple sin lógica, permissions.deny en la configuración hace el mismo trabajo sin necesidad de mantener un script, y los modos de permisos determinan qué se ejecuta sin pedirle confirmación primero. Si una instrucción debe estar realmente en el nivel del system prompt y no en un mensaje del usuario, --append-system-prompt la coloca allí. Sin embargo, es un flag de lanzamiento que debe volver a pasarse en cada sesión nueva, por lo que resulta más adecuado para scripts que para el trabajo interactivo.

Lo que no puede corregirse con instrucciones

Defina con claridad qué parte depende de usted. La ubicación, la redacción, los conflictos entre archivos y el tamaño del archivo son problemas del autor, y el autor debe corregirlos. El resto corresponde al comportamiento del modelo, y una redacción mejor no lo eliminará.

Aceptar no significa cumplir. Un agente confirmará una regla, la repetirá correctamente y la incumplirá dos llamadas de herramienta después. La confirmación no cuesta nada y no permite predecir nada. No la considere una corrección ni la cuente como una prueba.

Algunos hábitos son persistentes. Añadir comentarios, incorporar gestión preventiva de errores, escribir un resumen final o ejecutar el siguiente comando obvio. Estos comportamientos reaparecen cuando una regla los prohíbe, aunque con una frecuencia menor, no nula. Puede medir su propia frecuencia: ejecute la misma tarea diez veces en sesiones nuevas y cuente las infracciones. Cuando ese número deba ser cero, la regla debe salir del prompt. Dar por terminado un trabajo cuando aún queda una parte pendiente tiene la misma forma de hábito, y la corrección debe ser estructural, no verbal: la habilidad unlazy sustituye la frase por un árbol de profundidad y archivos de control que el agente debe superar antes de poder declarar que ha terminado.

La sesión actual se convierte en un ejemplo. Si el agente incumplió la regla en el turno 12 y usted lo dejó pasar, esa infracción queda en el contexto como demostración y es mucho más reciente que la regla. Corrija la infracción en cuanto la detecte. Una infracción no corregida enseña al resto de la sesión.

Un archivo de instrucciones no es un límite de seguridad. Da forma al comportamiento, pero no lo impone. Todo aquello cuyo incumplimiento resulte costoso, como las credenciales o los comandos destructivos, debe gestionarse mediante permisos o un hook. Mantener los secretos fuera del alcance de un agente aplica el mismo principio a los datos: no pida al agente que no lea un archivo; configure el sistema para que el archivo no se pueda leer.

La versión breve: demuestre que el archivo se cargó, haga que la regla se pueda comprobar, colóquela junto al elemento que regula y, cuando la tasa de incumplimiento siga siendo importante, sáquela de la prosa. Una regla que un agente no puede ignorar es una regla que nunca se le pidió seguir.

FAQ

¿Por qué Claude Code ignora mi CLAUDE.md?

Compruebe que se haya cargado antes de asumir que se ignoró. Ejecute /context y revise la lista Memory files; si un archivo no aparece allí, no se cargó al iniciar. Los archivos de instrucciones se entregan como un mensaje de usuario después del prompt del sistema y se tratan como contexto, no como configuración obligatoria. Por tanto, no existe una garantía estricta de cumplimiento. En la mayoría de los casos, se debe a uno de cuatro motivos: el archivo está en un subdirectorio que el agente nunca leyó, dos archivos contienen instrucciones contradictorias y el modelo eligió una de forma arbitraria, la regla es demasiado imprecisa para comprobarla frente a una acción o el código circundante muestra lo contrario de lo que indica la regla.

¿Editar el archivo de instrucciones durante la sesión cambia algo?

No cambia la copia que ya está en la conversación. Los archivos situados por encima del directorio de trabajo se cargan completos al iniciar, por lo que el texto que conserva el modelo corresponde al momento del inicio. Para incorporar una edición, inicie una sesión nueva o pida al agente que lea el archivo con sus herramientas habituales de archivos. Esto incorpora la versión actual a la conversación como un mensaje nuevo. Después de una compactación, el archivo de la raíz del proyecto se vuelve a leer del disco, por lo que la nueva versión también llega en ese momento.

¿Qué archivo prevalece si un CLAUDE.md de la raíz y otro anidado contienen instrucciones contradictorias?

Ninguno de forma fiable. Los archivos descubiertos se concatenan en el contexto en lugar de sobrescribirse. Se ordenan desde la raíz del sistema de archivos hasta el directorio de trabajo, de modo que el archivo más cercano simplemente se lee en último lugar. No existe un motor de precedencia que resuelva las contradicciones, y la documentación de Claude Code indica que las reglas contradictorias pueden resolverse de forma arbitraria. Escriba los archivos anidados como ampliaciones que indiquen la ruta que gobiernan y elimine la contradicción en lugar de intentar hacer que una regla prevalezca sobre otra.

¿Mis instrucciones sobreviven a /compact?

Depende de cómo se hayan cargado. CLAUDE.md de la raíz del proyecto, las reglas sin ámbito y la memoria automática se vuelven a insertar desde el disco después de una compactación. Las reglas con frontmatter paths: y los archivos CLAUDE.md anidados en subdirectorios se pierden hasta que se vuelva a leer un archivo coincidente. Todo lo que haya escrito únicamente en el chat sobrevive sólo si el resumidor decidió conservarlo. Si una regla debe mantenerse durante toda la sesión, colóquela en el archivo de la raíz del proyecto sin frontmatter paths:.

¿Cuándo debe convertirse una regla en un hook en lugar de permanecer como texto?

Cuando la comprobación sea determinista y el coste de omitirla sea mayor que el de escribir un script pequeño. Las restricciones de rutas de archivos, los comandos obligatorios antes de un commit y las llamadas a herramientas prohibidas cumplen este criterio. Un hook PreToolUse que termina con el estado 2 bloquea directamente la llamada a la herramienta y devuelve el texto de stderr al modelo como motivo. Por tanto, la regla se mantiene aunque ya no esté en el contexto. Todo lo que pueda decidir un formateador o un linter debe quedar bajo responsabilidad de esa herramienta y eliminarse por completo del archivo de instrucciones.

¿Te resultó útil este artículo?