Cómo conciliar capas de CLAUDE.md en conflicto antes de que Claude elija una (Guía de 2026)

Comencemos con cuántas superficies hay, porque la mayoría de las personas ejecutan más de las que creen.

La documentación enumera las ubicaciones de CLAUDE.md "en orden de carga, desde el alcance más amplio hasta el más específico". Un archivo de política administrada (managed policy), descrito como contenedor de "instrucciones para toda la organización administradas por TI/DevOps", en una ruta del sistema: /Library/Application Support/ClaudeCode/CLAUDE.md en macOS, /etc/claude-code/CLAUDE.md en Linux y WSL, y una ruta de Program Files en Windows. Instrucciones de usuario en ~/.claude/CLAUDE.md. Instrucciones de proyecto en ./CLAUDE.md o ./.claude/CLAUDE.md.

Luego están las que son fáciles de olvidar. Cada CLAUDE.md en la jerarquía de directorios por encima de tu directorio de trabajo se carga al inicio. Cada CLAUDE.local.md junto a ellos también se carga. También se descubren los archivos en los subdirectorios debajo de ti: "En lugar de cargarse al inicio, se incluyen cuando Claude lee archivos en esos subdirectorios". Y .claude/rules/ contiene tantos archivos markdown como desees.

Seis superficies, más una por nivel de directorio, más una carpeta de reglas. Ahora el mecanismo:

"Todos los archivos descubiertos se concatenan en el contexto en lugar de anularse entre sí."

Concatenados. No fusionados con un ganador, no anulados: añadidos al final. El orden está documentado: "el contenido se ordena desde la raíz del sistema de archivos hacia abajo hasta tu directorio de trabajo", por lo que "las instrucciones más cercanas a donde iniciaste Claude se leen al final", y dentro de un directorio CLAUDE.local.md va después de CLAUDE.md para que "tus notas personales sean lo último que Claude lee en ese nivel", pero el orden no es precedencia. Ser leído al final no significa ganar.

La carpeta de reglas hace esto explícito en lugar de implícito:

"Las reglas sin frontmatter de paths se cargan al inicio con la misma prioridad que .claude/CLAUDE.md."

Misma prioridad. Declarado abiertamente. La documentación no describe un criterio de desempate entre estas capas, y la razón por la que no lo hace está en la frase más importante de todo el documento:

"Claude los trata como contexto, no como configuración obligatoria."

Esa es la raíz de todo. Estos archivos no son configuraciones que resuelve un motor de precedencia; son texto que se coloca en un prompt. La documentación es sincera sobre la consecuencia: "Debido a que son contexto en lugar de configuración obligatoria, la forma en que escribes las instrucciones afecta la confiabilidad con la que Claude las sigue. Las instrucciones específicas, concisas y bien estructuradas funcionan mejor", y sobre la vía de escape: "Para bloquear una acción independientemente de lo que decida Claude, utiliza un hook PreToolUse en su lugar".

Vale la pena valorar esto en lugar de quejarse. Otras herramientas sí publican órdenes de precedencia. GitHub Copilot documenta las instrucciones personales como de máxima prioridad y las de la organización como de mínima. Tabnine documenta que su consola de administración tiene precedencia sobre tu archivo de pautas locales. Cursor documenta que las reglas de equipo superan a las de proyecto y de usuario. Cada una de ellas gana determinismo a costa de perder la capacidad de saber, a partir de un solo archivo, qué verá el modelo. La respuesta de Claude Code es que todo es contexto y nada gana silenciosamente, lo que deja el trabajo de conciliación en tus manos.

La razón por la que esto importa más este año es la capa de política administrada. Ahora una organización puede implementar un CLAUDE.md en cada máquina, y una versión reciente de Claude Code eliminó el diálogo de aprobación de seguridad que solía activar un claudeMd administrado, por lo que llega de forma silenciosa. Ese archivo está escrito por personas que no conocen tu proyecto, se concatena con el tuyo y, cuando contradice al tuyo, nada arbitra. Este es el mecanismo detrás de muchos informes como Claude forgetting house conventions: la convención está en el contexto, y también algo que no está de acuerdo con ella.

Repetir la regla con más fuerza en el archivo del proyecto. A veces funciona, porque la documentación sí dice que las instrucciones específicas y bien estructuradas se siguen con mayor confiabilidad. También infla el archivo, y dos instrucciones contradictorias enfáticas siguen siendo dos instrucciones contradictorias.

Colocar la regla en CLAUDE.local.md porque se lee al final. Basado en la suposición de que lo último equivale al ganador. La documentación describe el orden, no la precedencia, y dice explícitamente que los archivos se concatenan en lugar de anularse entre sí.

Eliminar el archivo a nivel de usuario. Efectivo y costoso. Tus preferencias personales no eran el problema; lo era un conflicto real entre ellas y un estándar del proyecto.

Mover todo a un enorme CLAUDE.md de proyecto. Esto elimina los conflictos entre archivos, pero viola la guía de tamaño: la documentación recomienda un objetivo de menos de 200 líneas por archivo, señalando que los archivos más largos "consumen más contexto y reducen la adherencia". Cambiaste un problema de conflicto por un problema de adherencia.

Preguntar a Claude qué regla está siguiendo. Diagnóstico razonable, y /context realmente enumera los archivos de memoria que se cargaron, mientras que /status nombra la fuente administrada vigente. Pero pedirle al modelo que introspeccione sobre una elección arbitraria no hace que la elección sea menos arbitraria.

Usar un hook. La propia recomendación de la documentación para restricciones estrictas, y es correcta para bloquear acciones. Un hook no puede decirle a Claude cuál de las dos convenciones de estilo acordó tu equipo.

El patrón es que los seis intentan ganar el conflicto. Ninguno lo elimina. Y un conflicto entre dos imperativos no se puede eliminar clasificándolos, porque la información necesaria para clasificarlos no está en ninguno de los archivos.

Tres pasos: ver qué está cargado realmente, dar a cada capa un solo trabajo y eliminar la razón por la que se acumulan las contradicciones.

Paso 1: Enumerar qué está realmente en contexto

Ejecuta /context en una sesión y lee la lista bajo Archivos de memoria (Memory files). Esta es la respuesta definitiva, y suele ser sorprendente: un CLAUDE.md tres directorios más arriba que alguien agregó el año pasado, un CLAUDE.local.md que olvidaste, cuatro archivos en .claude/rules/ que se cargan incondicionalmente. Ejecuta /status también y verifica la línea Setting sources, que nombra la fuente administrada que se aplica a ti, para saber si hay un archivo de organización en juego.

Dos peculiaridades documentadas a tener en cuenta durante la auditoría. Las importaciones son contenido real: CLAUDE.md puede incorporar otros archivos con la sintaxis @path/to/import, y estos se "expanden y cargan en el contexto al inicio", por lo que un archivo de una sola línea puede ser grande. Y el análisis de importaciones "omite los intervalos de código Markdown y los bloques de código delimitados": una ruta entre comillas invertidas (backticks) sigue siendo literal, mientras que la misma ruta fuera de comillas invertidas importa el archivo. Si tienes rutas documentadas sin comillas invertidas, es posible que estés importando cosas que solo querías mencionar.

También es útil: los comentarios HTML a nivel de bloque se "eliminan antes de que el contenido se inyecte en el contexto de Claude", lo que los convierte en el lugar adecuado para notas para mantenedores humanos que no deberían costar tokens.

En un monorepo donde se recopilan archivos de otros equipos, claudeMdExcludes los omite. Esa es una solución real para una fuente de conflicto real, y es la única en esta lista que elimina archivos del contexto en lugar de reordenarlos.

Paso 2: Dar a cada capa exactamente un trabajo

Ahora asigna alcances para que no haya dos capas que puedan estar en desacuerdo, porque cada una habla de algo diferente.

La política administrada (Managed policy) contiene restricciones que son genuinamente organizacionales: requisitos de seguridad, reglas de cumplimiento, licencias. Cosas con las que nadie en tu equipo discutiría. Si contiene opiniones sobre frameworks, de ahí provienen tus conflictos, y la conversación debe ser con quien la implemente, no con el archivo de tu proyecto.

Las instrucciones de usuario contienen cómo te gusta trabajar personalmente: estilo de respuesta, tus preferencias de terminal, tus atajos. Nada sobre el proyecto pertenece aquí; esa es la fuente más común de una regla que no coincide silenciosamente con la de un compañero de equipo, y es el mismo error de ubicación que hace que making Claude stick to your coding style sea más difícil de lo que debería.

Las instrucciones del proyecto contienen lo que es cierto sobre este repositorio: comandos, convenciones, datos de arquitectura. Este es el archivo que debe compartirse y revisarse.

.claude/rules/ con frontmatter de paths contiene cualquier cosa condicional. Este es el importante, porque una regla con alcance de ruta no puede entrar en conflicto con una regla para una ruta diferente; nunca son relevantes ambas al mismo tiempo. Mover una regla de un archivo incondicional a una regla con alcance de paths convierte una contradicción potencial en dos declaraciones que no se superponen. Las reglas sin paths se cargan incondicionalmente con la misma prioridad que el archivo de tu proyecto, así que usa el frontmatter siempre que la regla sea genuinamente específica de un archivo.

Las habilidades (Skills) contienen procedimientos específicos de tareas. La documentación hace que la división sea clara: las reglas "se cargan en el contexto en cada sesión o cuando se abren archivos coincidentes", mientras que para "instrucciones específicas de tareas que no necesitan estar en el contexto todo el tiempo, usa habilidades en su lugar".

Una nota fáctica que ahorra una tarde: "Claude Code lee CLAUDE.md, no AGENTS.md". Si tu repositorio ya tiene un AGENTS.md para otras herramientas, el enfoque documentado es un CLAUDE.md que lo importe, de modo que ambos lean el mismo contenido en lugar de que dos archivos se desvíen. Dos archivos que se desvían es el problema del conflicto en su forma más pura.

Paso 3: Registrar la decisión, no solo la regla

Después del Paso 2, te quedará una pequeña cantidad de contradicciones reales: casos en los que dos capas realmente no están de acuerdo sobre lo mismo y ambos autores tenían una razón.

No puedes resolver eso clasificando capas. "Usar el cliente HTTP interno" frente a "usar el cliente de la biblioteca estándar" es irresoluble como dos imperativos. Se resuelve instantáneamente si sabes que uno se escribió cuando el cliente interno era el único con el soporte de proxy requerido, y la biblioteca estándar lo obtuvo en una versión posterior.

Esa información nunca estuvo en ninguno de los archivos, porque un CLAUDE.md es un lugar para imperativos. Lo que significa que cada conflicto que resuelvas hoy se volverá a crear la próxima vez que alguien escriba un imperativo sin su causa. La memoria automática ayuda un poco aquí: Claude mantiene su propio almacén de aprendizajes y correcciones por repositorio, inyectado en cada sesión hasta un límite documentado de las primeras 200 líneas o 25 KB, pero ese almacén lo escribe Claude a partir de tus correcciones, no es un registro de las decisiones que tomó tu equipo y por qué.

MemoryLake guarda las decisiones y sus razones fuera de cada archivo de instrucciones, y responde preguntas sobre ellas a través de MCP o la API. Tus archivos CLAUDE.md se mantienen cortos e imperativos y se cargan exactamente como está documentado; cuando dos de ellos no están de acuerdo, la razón por la que existe cada uno está en un lugar donde puedes consultarla en lugar de adivinar qué capa debería ganar.

Step 1: Create an API key

Genera una clave y realiza tu primera solicitud en unos treinta segundos. Haz esto antes del Paso 2 anterior, para tener un lugar donde registrar cada conflicto a medida que ordenas las capas.

Step 2: Upload your first memories

Trabaja en los conflictos del Paso 2 y las reglas que heredaste. Para cada uno, escribe qué se decidió, qué se rechazó y por qué. Las reglas cuya razón nadie recuerda son las entradas de mayor valor, porque esas son las que se volverán a discutir. Los documentos y archivos de soporte van en el mismo lugar.

Step 3: Connect your AI & agents

Dale acceso a Claude Code, Codex, Devin y tus otros agentes a través de MCP o la API. Cuando una regla parezca incorrecta, la respuesta a "por qué está esto aquí" llegará con su razonamiento en lugar de como una reafirmación más ruidosa.

El primer cambio es que tus archivos se vuelven más cortos. Una vez que las razones viven en otro lugar, un CLAUDE.md es una lista de imperativos, que es lo que pide la guía de menos de 200 líneas y lo que la documentación dice que mejora la adherencia.

El segundo es que la mayoría de los conflictos dejan de existir en lugar de resolverse. Una regla con alcance de paths y una regla con alcance de una ruta diferente nunca están ambas en contexto. Esa es una solución estructural, no una clasificación.

El tercero es que la capa de política administrada deja de dar miedo. Cuando el archivo de la organización contiene solo restricciones organizacionales reales y el archivo de tu proyecto contiene datos del proyecto, la concatenación es exactamente lo que deseas: dos conjuntos de declaraciones que no se superponen.

El cuarto es que la frase sobre la elección arbitraria deja de aplicarse a cualquier cosa que te importe. Claude aún puede elegir arbitrariamente entre dos reglas contradictorias; simplemente has dejado de enviar reglas contradictorias. Esta es la solución real para el tipo de queja detrás de Claude Code forgetting project context y detrás de agents ignoring your instruction files: la instrucción no fue ignorada, fue superada en votos por una vecina.

Ejecuta /context antes de depurar cualquier cosa. La lista de archivos de memoria cargados es la verdad absoluta, y generalmente es más larga de lo que esperas.

Un trabajo por capa. Restricciones organizacionales, preferencias personales, datos del proyecto, reglas condicionales, procedimientos de tareas. Si dos capas pueden hablar sobre el mismo tema, eventualmente lo harán.

Usa el frontmatter de paths de forma agresiva. Una regla con alcance no puede contradecir una regla para otros archivos. Esta es la eliminación de conflictos más económica disponible.

Mantén los archivos del proyecto por debajo del tamaño recomendado. La documentación apunta a menos de 200 líneas y señala que los archivos más largos reducen la adherencia. Divide por tema en .claude/rules/ en lugar de hacer crecer un solo archivo.

Nunca pongas datos del proyecto en tu archivo de usuario. Es la fuente más común de una regla que no coincide con la de un compañero de equipo y que no se puede revisar.

Envuelve las rutas entre comillas invertidas a menos que quieras importar. El análisis de importaciones omite los intervalos de código, por lo que las comillas invertidas son la diferencia entre mencionar un archivo y cargarlo.

Importa AGENTS.md en lugar de duplicarlo. Claude Code lee CLAUDE.md, no AGENTS.md, y dos copias mantenidas a mano de las mismas convenciones terminarán divergiendo.

Usa hooks para restricciones estrictas. La documentación es explícita en que estos archivos son contexto en lugar de configuración obligatoria, y que un hook PreToolUse es la forma de bloquear una acción independientemente de lo que decida Claude.

Claude Code documenta sus archivos de instrucciones con honestidad: todos los archivos descubiertos se concatenan en el contexto en lugar de anularse entre sí, las reglas sin frontmatter de paths se cargan con la misma prioridad que el archivo de tu proyecto, todo el conjunto se trata como contexto en lugar de configuración obligatoria y, si dos reglas se contradicen entre sí, Claude puede elegir una de forma arbitraria. No hay un motor de precedencia oculto que aprender, lo que también significa que no hay nada a lo que apelar cuando dos de tus archivos no están de acuerdo.

Así que deja de intentar ganar esos conflictos y, en su lugar, deja de enviarlos. Enumera lo que realmente se carga, dale a cada capa un tema para que las capas no se superpongan, define el alcance de todo lo condicional con paths y mantén los archivos lo suficientemente cortos como para que se puedan seguir. Luego, registra por qué existe cada regla en algún lugar fuera de todos ellos, porque la capa que decide los conflictos no es una ruta de archivo ni un orden de carga. Es si alguien todavía recuerda para qué servía la regla.