Dónde va cada instrucción en Claude Code, CLAUDE.md y settings.json

En un equipo de seis, cada uno le explica a Claude las mismas convenciones con sus palabras, y después de dos meses cada máquina tiene una versión distinta. El problema no es el modelo: las instrucciones están en el lugar equivocado. Casi todas las preguntas de este dominio se resuelven sabiendo en qué archivo va cada cosa y a quién le llega.

La jerarquía de CLAUDE.md

La jerarquía de CLAUDE.md (CLAUDE.md hierarchy) tiene cuatro niveles:

Archivo	A quién le llega	Para qué
CLAUDE.md de política administrada (lo despliega la organización)	Todos en la organización	Estándares y políticas de la empresa
./CLAUDE.md o ./.claude/CLAUDE.md	Al equipo, por git	Arquitectura, comandos de build y test, convenciones
./CLAUDE.local.md	Solo a vos, en este proyecto (va en .gitignore)	Tus URLs de prueba, tus datos de ejemplo
~/.claude/CLAUDE.md	Solo a vos, en todos tus proyectos	Preferencias personales

Tres detalles que suman puntos:

• Los archivos no se pisan: se concatenan en el contexto, y lo más cercano al directorio de trabajo se lee al final.
• Para proyectos grandes, .claude/rules/ divide las instrucciones por tema y puede limitarlas a ciertas rutas, así solo se cargan cuando hacen falta.
• Para inicializar el repositorio (repository initialization), /init analiza el código y genera un CLAUDE.md inicial con comandos y convenciones; después se ajusta a mano.

La jerarquía de settings.json

Con la configuración pasa lo mismo, pero acá hay precedencia: cuando la misma clave aparece en varios archivos, gana el nivel más alto.

1. Configuración administrada por la organización: nadie la sobrescribe.
2. Línea de comandos (--settings), solo para esa sesión.
3. .claude/settings.local.json: la configuración local del proyecto (project local settings), personal y fuera de git.
4. .claude/settings.json: la configuración compartida del proyecto (shared project settings), que se commitea.
5. ~/.claude/settings.json: tu configuración para todos los proyectos.

Las reglas de permisos (permission rules) allow, ask y deny de distintos archivos se combinan en lugar de reemplazarse, y una regla deny bloquea aunque otra regla la permita. Si el equipo necesita reglas comunes y una persona una excepción propia, las comunes van en .claude/settings.json y la excepción en su .claude/settings.local.json.

Contexto o control

La diferencia que más se pregunta:

• CLAUDE.md es contexto. Claude lo sigue casi siempre, pero no está garantizado.
• settings.json es control. Una regla deny o un hook se aplican siempre, decida lo que decida el modelo.

Si el requisito dice “nunca”, la respuesta no es reescribir CLAUDE.md con más énfasis.

Las trampas típicas

• Convenciones del equipo en el ~/.claude/CLAUDE.md de cada uno: no se versionan y se desalinean.
• Notas personales en el CLAUDE.md del proyecto, que le llegan a todos.
• Excepciones personales commiteadas en el .claude/settings.json compartido.
• Dar permisos totales “para que no pregunte” en lugar de reglas allow acotadas.
• Confiar en una prohibición escrita en CLAUDE.md para algo destructivo.

En el examen

Identificá el alcance que pide el escenario: ¿todo el equipo, solo una persona en este proyecto, o una persona en todos sus proyectos? Eso te da el archivo. Después fijate si el requisito es una preferencia (CLAUDE.md alcanza) o una garantía (permisos o hooks en settings.json).