Claude Code Rules: Cómo escribir CLAUDE.md y gestionar el contexto de codificación agentiva

Las reglas de Claude Code viven en archivos CLAUDE.md — archivos markdown que colocas en tu repositorio de proyecto, directorio de inicio o configuración de la organización, y que Claude lee al inicio de cada sesión. Combinado con reglas con alcance de ruta en .claude/rules/, un settings.json para permisos y memoria automática para preferencias aprendidas, el sistema de reglas te da un control preciso y persistente sobre cómo se comporta el agente de codificación en cualquier tarea.

¿Qué son las reglas de Claude Code?

Cada sesión de Claude Code comienza con una ventana de contexto vacía. Las reglas son la forma de precargar el contexto que Claude necesita para que no empiece desde cero — o cometa el mismo error dos veces.

Dos sistemas complementarios manejan esto:

Los archivos CLAUDE.md son archivos markdown que escribes y que Claude lee al inicio de cada sesía. Úsalos para instrucciones que siempre deberían aplicarse: comandos de compilación, convenciones de código, decisiones de arquitectura, restricciones estrictas.

La memoria automática son notas que Claude escribe por sí mismo basándose en correcciones y preferencias que le das durante las sesiones. Estas se acumulan automáticamente; Claude decide qué vale la pena guardar y lee esas notas en sesiones futuras.

Ambos se cargan en el contexto al inicio de la sesión, pero no son configuración forzada. Son instrucciones que Claude sigue como contexto. Para un enforcement duro — bloquear un comando específico independientemente de lo que Claude decida hacer — necesitas un hook PreToolUse o una regla deny en settings.json. La distinción importa para ejecuciones autónomas donde quieres un comportamiento predecible, no un cumplimiento probabilístico.

Ubicaciones y alcance de archivos CLAUDE.md

Claude Code carga archivos CLAUDE.md desde varias ubicaciones, cada una cubriendo un alcance diferente. Se cargan en orden de lo más amplio a lo más específico:

Ubicación	Alcance	Para qué sirve
~/.claude/CLAUDE.md	Todos los proyectos en tu máquina	Preferencias personales, hábitos de flujo de trabajo globales
./CLAUDE.md (raíz del repo)	Todas las sesiones en ese proyecto	Convenciones del proyecto, comandos de compilación, reglas compartidas del equipo
./CLAUDE.local.md (raíz del repo)	Solo tus sesiones locales	Preferencias por desarrollador; añadir a .gitignore
./src/CLAUDE.md (subdirectorio)	Sesiones que tocan archivos en ese directorio	Reglas específicas del módulo que no aplican a todo el proyecto

Todos los archivos descubiertos se concatenan en el contexto — no se sobrescriben entre sí. Dentro de esa concatenación, el contenido desde la raíz del sistema de archivos hasta tu directorio de trabajo se ordena con el más específico al final, de modo que una instrucción del proyecto aparece después de una instrucción del usuario. Esto te da una especificidad natural: una regla del proyecto gana cuando entra en conflicto con una a nivel de usuario.

Puedes importar archivos adicionales con referencias @path dentro de cualquier CLAUDE.md:

@./docs/architecture.md
@./CONTRIBUTING.md

Los archivos importados se cargan al inicio de la sesión, igual que el propio CLAUDE.md. Las importaciones son útiles para la organización, pero no ahorran contexto — el contenido importado cuenta para tu presupuesto de tokens.

Para equipos: confirma el CLAUDE.md del proyecto en el control de versiones. Esto asegura que cada sesión de Claude de cualquier desarrollador — y cualquier ejecución de agente basada en CI — comience con el mismo contexto compartido. Trátalo como .eslintrc o pyproject.toml.

Qué poner en CLAUDE.md

El contenido más útil es lo que de otro modo volverías a explicar en cada sesión, o lo que un nuevo miembro del equipo necesitaría saber en su primera hora.

Buenos candidatos:

• Comandos de compilación y prueba que difieren de los valores predeterminados obvios (./scripts/test.sh --ci, no solo npm test)
• Convenciones de código que no están capturadas por el linter (“usamos exportaciones con nombre en todas partes; sin exportaciones predeterminadas en utilidades compartidas”)
• Decisiones de arquitectura que no son obvias al leer el código (“el directorio lib/ es compartido entre servicios — no agregues lógica específica de un servicio allí”)
• Problemas conocidos (“el archivo config.ts se genera en tiempo de compilación; no lo edites manualmente”)
• Restricciones de flujo de trabajo (“siempre crea una rama antes de hacer cambios; sube al remoto antes de abrir un PR”)

Cosas que dejar fuera:

• Listados de directorios y árboles de archivos — Claude los lee del repositorio
• Listas de dependencias — disponibles desde package.json, pyproject.toml y similares
• Descripciones en prosa de lo que hace el código existente — Claude lee el código fuente directamente
• Cambios recientes — Claude usa git log y git diff cuando necesita historial

Mantén CLAUDE.md enfocado en lo que no se puede derivar de leer el código base. Los archivos de más de 200 líneas consumen más contexto y reducen la fiabilidad de la adherencia. El comando /doctor en Claude Code audita un CLAUDE.md confirmado y sugiere eliminar contenido que se pueda derivar del código — una forma útil de recortar un archivo inflado.

Escribir reglas efectivas

La especificidad importa. Compara:

# Vago — menos consistente
Sigue los estándares de codificación del proyecto.

# Específico — más consistente
- Usa pnpm, no npm ni yarn
- Ejecuta pnpm test antes de cada commit; no confirmes si las pruebas fallan
- Exporta todos los tipos compartidos desde src/types/index.ts — no definas tipos en línea en archivos de componentes
- El directorio data/ es de solo lectura en las pruebas; usa fixtures de prueba de tests/fixtures/ en su lugar

Cada regla debe ser procesable sin más explicación. Si necesitaras explicar el razonamiento de una regla a alguien, añade el razonamiento en línea — ayuda a Claude a aplicar la regla correctamente en casos límite.

Reglas con alcance de ruta con .claude/rules/

El directorio .claude/rules/ te permite adjuntar reglas a patrones de archivo específicos sin cargarlas en cada sesión. Claude descubre archivos en .claude/rules/ y los carga cuando trabajas con archivos que coinciden.

Una estructura típica para un monorepositorio TypeScript:

.claude/rules/
  api.md             # reglas para src/api/** — validación de solicitudes, formatos de error
  components.md      # reglas para src/components/** — tipos de props, convenciones de estilo
  tests.md           # reglas para tests/** — patrones de fixtures, configuración de mocks
  database.md        # reglas para migrations/ y models/ — nombres de migraciones, patrones de consultas

Cada archivo de regla usa frontmatter YAML con un campo paths para controlar cuándo se carga:

---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.test.ts"
---

# Reglas de Desarrollo de API

- Todos los manejadores de rutas deben validar la entrada con zod antes de cualquier lógica de negocio
- Devuelve errores como `{ error: string; code: string }` — nunca cadenas simples
- La limitación de tasa se aplica en la puerta de enlace; no la agregues dentro de los manejadores

Las reglas sin un campo paths se cargan incondicionalmente al inicio de la sesión, igual que el contenido en el CLAUDE.md del proyecto. Las reglas con paths se cargan solo cuando Claude abre archivos que coinciden con esos patrones.

Esto mantiene conciso el CLAUDE.md raíz del proyecto y asegura que las convenciones detalladas para una capa de la pila no llenen el contexto durante sesiones enfocadas en un área diferente.

settings.json vs CLAUDE.md

CLAUDE.md controla lo que Claude sabe y tiene la intención de hacer. settings.json controla lo que Claude realmente tiene permitido hacer.

	CLAUDE.md	settings.json
Propósito	Instrucciones y contexto	Permisos y configuración
¿Forzado?	No — Claude actúa sobre ello como guía	Sí — las reglas deny bloquean llamadas a herramientas incondicionalmente
Formato	Markdown de forma libre	JSON estructurado
Ubicación	./CLAUDE.md, ~/.claude/CLAUDE.md	.claude/settings.json, ~/.claude/settings.json

Un settings.json de proyecto en .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(pnpm test)",
      "Bash(pnpm build)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

La lista allow preaprueba comandos específicos para que Claude pueda ejecutarlos sin solicitar confirmación. Esto acelera las sesiones interactivas para operaciones de confianza. La lista deny bloquea comandos incondicionalmente — independientemente de lo que Claude decida hacer, independientemente de lo que diga CLAUDE.md. Usa deny para operaciones irreversibles en datos de producción o infraestructura.

La configuración a nivel de usuario en ~/.claude/settings.json aplica a todos los proyectos. La configuración del proyecto en .claude/settings.json aplica solo en ese repositorio. La configuración del proyecto tiene prioridad sobre la configuración del usuario donde se superponen.

Memoria automática: las notas de Claude

La memoria automática es la contraparte de CLAUDE.md. Mientras que CLAUDE.md son instrucciones que tú escribes, la memoria automática son notas que Claude escribe por sí mismo basándose en lo que aprende durante tus sesiones.

Cuando corriges a Claude durante una sesión — “usamos Vitest, no Jest en este proyecto” — puede guardar eso como una nota en ~/.claude/projects/<repo>/memory/. En la siguiente sesión, Claude lee esa nota y aplica la corrección sin que se lo digan de nuevo.

El directorio de memoria contiene:

~/.claude/projects/<repo>/memory/
  MEMORY.md          # índice que Claude usa para encontrar otros archivos; las primeras 200 líneas se cargan cada sesión
  debugging.md       # patrones que Claude descubrió resolviendo problemas en este repositorio
  conventions.md     # convenciones que Claude aprendió de tus correcciones

Esto es local a la máquina y por repositorio. La memoria automática complementa CLAUDE.md en lugar de reemplazarlo: CLAUDE.md es para reglas de proyecto compartidas por el equipo; la memoria automática es para patrones personales que Claude aprendió trabajando contigo.

La memoria automática es markdown legible que puedes editar o eliminar en cualquier momento. Ejecuta /memory dentro de una sesión para navegar y editar los archivos. Si algo está desactualizado o es incorrecto, elimínalo — Claude dejará de aplicar la regla obsoleta.

Buenas prácticas para codificación agentiva

Ejecutar Claude Code de forma autónoma — a través de claude -p, el Agent SDK, o pipelines de CI — aumenta las apuestas para tu configuración de reglas. El agente puede completar docenas de llamadas a herramientas sin pausa, y no hay un intercambio interactivo para corregir malentendidos a mitad de la ejecución.

Escribe restricciones explícitas, no solo preferencias. El Claude interactivo puede pedirte que aclares. Una ejecución autónoma trabaja con lo que encuentra en el contexto. Si “nunca modifiques archivos de migración sin crear primero una instantánea de la base de datos” es importante, debe estar en CLAUDE.md. No asumas que Claude inferirá la restricción de la estructura del código base.

Usa reglas deny para cualquier cosa difícil de revertir. Preaprobar Bash(pnpm build) acelera las sesiones interactivas y es de bajo riesgo. Pero para ejecuciones autónomas, la lista deny es tu red de seguridad para operaciones que tocan infraestructura de producción, confirman permanentemente en el historial de git, o eliminan datos.

Mantén el CLAUDE.md del proyecto en control de versiones. Un CLAUDE.md confirmado en la raíz del repositorio aplica de manera consistente a sesiones interactivas, ejecuciones de CI, y al agente local de cualquier miembro del equipo. Este es el lugar adecuado para las reglas que definen lo que “correcto” significa para tu código base.

Usa .claude/rules/ para contenido específico de dominio. Si tu proyecto tiene capas distintas — componentes frontend, API backend, esquema de base de datos, scripts de infraestructura — pon las reglas para cada capa en .claude/rules/ con alcance de ruta. Un solo CLAUDE.md de 400 líneas con todo es más difícil de navegar para Claude y cuesta más contexto por sesión.

Mueve el material de referencia a skills. Las skills (.claude/skills/) se cargan bajo demanda, no al inicio de la sesión. Documentación larga de API, procedimientos de despliegue de varios pasos y guías de resolución de problemas pertenecen a skills que invocas con /deploy o /debug — no en CLAUDE.md donde consumen contexto incluso cuando son irrelevantes.

Revisa la memoria automática periódicamente. La memoria automática se acumula con el tiempo. Los comandos de compilación cambian, las convenciones se refactorizan, los patrones de prueba se modifican. Una nota de memoria obsoleta que dice “usa el cliente de API v1” cuando has migrado a v2 causará errores sutiles en ejecuciones autónomas. Audita ~/.claude/projects/<repo>/memory/ cuando hagas cambios significativos en la estructura del proyecto.

Usar modelos de código abierto con tu configuración de reglas

El contexto de CLAUDE.md y .claude/rules/ que has construido funcionan igual independientemente del modelo que maneje la inferencia. Una vez que tus reglas están escritas, cambiar de backend de modelo lo preserva todo — y los modelos de código abierto a través de la API LLM de Novita AI son una opción práctica para trabajo agentivo de alto volumen.

La configuración es una variable de entorno:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<tu-clave-api-novita>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"

Con ANTHROPIC_BASE_URL apuntando a Novita AI, Claude Code envía todas las solicitudes de inferencia al endpoint compatible con Anthropic de Novita en lugar de api.anthropic.com. Tus CLAUDE.md, reglas con alcance de ruta y settings.json aplican exactamente como antes — la capa de reglas está aguas arriba de la selección del modelo.

Novita AI aloja modelos de peso abierto enfocados en codificación, incluyendo Qwen3-Coder, GLM-4.7, MiniMax M2.5 y DeepSeek V4. Estos modelos están optimizados para el uso de herramientas en múltiples pasos y la invocación de funciones, lo que se alinea bien con los patrones de llamada a herramientas que Claude Code usa internamente para ediciones de archivos, comandos de shell y navegación de repositorios.

Para equipos que ejecutan tareas agentivas a escala — pipelines de revisión de código, refactorización automatizada en repositorios grandes, generación de pruebas — los modelos de peso abierto en Novita suelen costar significativamente menos por millón de tokens que las alternativas de código cerrado, mientras siguen leyendo y aplicando tus reglas del proyecto de manera efectiva.

Si estás ejecutando agentes contra un código base de producción y deseas una capa de seguridad adicional más allá de las reglas deny, considera combinar la API LLM de Novita con Novita Agent Sandbox. El sandbox le da al agente un entorno Linux completo para operaciones de archivos y ejecución de comandos, aislado de tu sistema anfitrión. El contexto de tu CLAUDE.md viaja con la tarea; el riesgo de ejecución se mantiene contenido.

Preguntas frecuentes

¿Qué es CLAUDE.md en Claude Code?

CLAUDE.md es un archivo markdown que le da a Claude Code instrucciones persistentes a través de las sesiones. Se carga al inicio de la sesión para que Claude no necesite que se le vuelvan a enseñar las convenciones de tu proyecto cada vez. Puedes tener archivos CLAUDE.md en múltiples alcances: a nivel de usuario (~/.claude/CLAUDE.md) para preferencias personales que aplican en todas partes, a nivel de proyecto (raíz del repositorio) para reglas compartidas por el equipo confirmadas en control de versiones, y a nivel de subdirectorio para reglas específicas de módulo.

¿Qué debería poner en los archivos de reglas de claude md?

Escribe lo que de otro modo volverías a explicar en cada sesión: comandos de compilación y prueba, convenciones de codificación que difieren de los valores predeterminados del framework, restricciones de arquitectura y problemas conocidos del código base. Deja fuera el contenido que Claude puede derivar del código base mismo — árboles de archivos, listas de dependencias y descripciones de lo que hace el código existente. Mantén los archivos por debajo de 200 líneas para una adherencia consistente.

¿Cuál es la diferencia entre CLAUDE.md y settings.json en Claude Code?

CLAUDE.md son instrucciones que Claude sigue como guía. settings.json es una configuración que Claude Code fuerza a nivel de sistema. Una regla en CLAUDE.md da forma a lo que Claude tiene la intención de hacer; una entrada deny en settings.json bloquea una llamada a herramienta incondicionalmente. Para cualquier cosa que no deba suceder independientemente de lo que Claude decida — eliminaciones irreversibles, push forzados, operaciones en entornos de producción — usa settings.json, no CLAUDE.md.

¿Qué es el directorio .claude/rules/?

.claude/rules/ contiene archivos de reglas con alcance de ruta que se cargan solo cuando Claude está trabajando con archivos que coinciden con el alcance de la regla. Esto te permite escribir reglas detalladas y específicas de dominio sin cargarlas en cada sesión. Las reglas son archivos markdown con frontmatter YAML opcional que especifica patrones glob paths. Las reglas sin frontmatter paths se cargan incondicionalmente al inicio de la sesión, como contenido adicional de CLAUDE.md.

¿Funciona CLAUDE.md en CI y tareas automatizadas de claude code?

Sí. Cualquier invocación de claude -p, llamada al Agent SDK, o pipeline de CI que se ejecute en un directorio de repositorio carga el CLAUDE.md del proyecto. Esto hace que CLAUDE.md sea efectivo para forzar un comportamiento consistente tanto en contextos interactivos como automatizados. Confirmarlo en control de versiones asegura que cada ejecución — local y de CI — comience con el mismo contexto compartido.

¿Cómo funciona el contexto de claude code y cómo lo gestiono?

El contexto es el presupuesto de tokens para la sesión actual. Los archivos CLAUDE.md, las referencias importadas, la memoria automática y el historial de la conversación cuentan para él. Gestionarlo manteniendo CLAUDE.md conciso, usando .claude/rules/ para cargar contenido de dominio solo cuando sea relevante, y usando /compact para resumir sesiones largas sin perder continuidad. Después de /compact, Claude vuelve a leer el CLAUDE.md raíz del proyecto desde el disco y lo reinyecta en la sesión automáticamente.

¿Cómo uso las mejores prácticas de claude code para codificación agentiva en un equipo?

Confirma el CLAUDE.md del proyecto en tu repositorio para que todos los miembros del equipo y los agentes de CI compartan las mismas reglas. Usa .claude/rules/ con alcance de ruta para contenido específico de dominio. Añade reglas deny a .claude/settings.json para operaciones que nunca deberían ejecutarse en contextos automatizados. Mantén la memoria automática fuera de CI — es local a la máquina y por desarrollador; el CLAUDE.md confirmado es la fuente de verdad para el comportamiento compartido.

Novita AI es una plataforma cloud de IA que ofrece a los desarrolladores una forma sencilla de implementar modelos de IA mediante nuestra API simple, al mismo tiempo que proporciona GPU cloud asequible y confiable para construir y escalar.

Artículos recomendados

• Documentación de la CLI de Claude Code: Configuración, comandos slash e integración con API LLM
• Claude Code SDK: Construye agentes autónomos con Python y TypeScript
• Construyendo un agente de codificación con Novita Agent Sandbox

---

Fuentes consultadas el 21 de julio de 2026: Documentación de memoria de Claude Code, Resumen de características de Claude Code, API LLM de Novita AI