Reglas de Claude Code: Cómo escribir CLAUDE.md y gestionar el contexto de codificación agéntica

Las reglas de Claude Code viven en archivos CLAUDE.md — archivos markdown que colocas en el repositorio de tu proyecto, en tu directorio personal o en la configuración de la organización, y que Claude lee al inicio de cada sesión. Combinado con reglas de alcance por ruta en .claude/rules/, un settings.json para permisos y memoria automática para preferencias aprendidas, el sistema de reglas te brinda 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 no empezar desde cero — ni cometer el mismo error dos veces.

Dos sistemas complementarios se encargan de esto:

Los archivos CLAUDE.md son archivos markdown que escribes y que Claude lee al inicio de cada sesión. Úsalos para instrucciones que siempre deben 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 las correcciones y preferencias que le das durante las sesiones. 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 obligatoria. Son instrucciones que Claude sigue como contexto. Para una aplicación estricta — bloquear un comando específico sin importar lo que Claude decida hacer — necesitas un hook PreToolUse o una regla deny en settings.json. Esta distinción es importante para ejecuciones autónomas donde quieres un comportamiento predecible, no un cumplimiento probabilístico.

Ubicaciones y alcance de los archivos CLAUDE.md

Claude Code carga los 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 de tu máquina	Preferencias personales, hábitos de flujo de trabajo globales
./CLAUDE.md (raíz del repositorio)	Todas las sesiones en ese proyecto	Convenciones del proyecto, comandos de compilación, reglas compartidas por el equipo
./CLAUDE.local.md (raíz del repositorio)	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 de módulos que no aplican a todo el proyecto

Todos los archivos encontrados 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 prevalece cuando entra en conflicto con una de 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: haz commit del CLAUDE.md del proyecto al control de versiones. Esto asegura que las sesiones de Claude de cada desarrollador — y cualquier ejecución de agente basada en CI — comiencen con el mismo contexto compartido. Trátalo como .eslintrc o pyproject.toml.

Qué poner en CLAUDE.md

El contenido más útil es aquel que de otro modo tendrías que reexplicar 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 captura el linter («usamos exportaciones nombradas en todas partes; sin exportaciones por defecto en utilidades compartidas»)
• Decisiones de arquitectura que no son obvias al leer el código («el directorio lib/ se comparte entre servicios — no agregues lógica específica de servicios allí»)
• Errores conocidos («el archivo config.ts se genera en tiempo de compilación; no lo edites manualmente»)
• Restricciones de flujo de trabajo («crea siempre una rama antes de hacer cambios; envía al remoto antes de abrir un PR»)

Cosas que debes omitir:

• 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 deducir leyendo el código. Los archivos de más de 200 líneas consumen más contexto y reducen la fiabilidad del cumplimiento. El comando /doctor en Claude Code audita un CLAUDE.md versionado y sugiere eliminar contenido que se pueda deducir del código — una forma útil de recortar un archivo inflado.

Cómo escribir reglas efectivas

La especificidad importa. Compara:

# Vague — less consistent
Follow project coding standards.

# Specific — more consistent
- Use pnpm, not npm or yarn
- Run pnpm test before every commit; do not commit if tests fail
- Export all shared types from src/types/index.ts — do not define types inline in component files
- The data/ directory is read-only in tests; use test fixtures from tests/fixtures/ instead

Cada regla debe ser accionable 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 de alcance por ruta con .claude/rules/

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

Una estructura típica para un monorepo de TypeScript:

.claude/rules/
  api.md             # rules for src/api/** — request validation, error formats
  components.md      # rules for src/components/** — prop types, styling conventions
  tests.md           # rules for tests/** — fixture patterns, mock setup
  database.md        # rules for migrations/ and models/ — migration naming, query patterns

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

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

# API Development Rules

- All route handlers must validate input with zod before any business logic
- Return errors as `{ error: string; code: string }` — never plain strings
- Rate limiting is applied at the gateway; do not add it inside handlers

Las reglas sin un campo paths se cargan incondicionalmente al inicio de la sesión, igual que el contenido del 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 de la raíz del proyecto y garantiza que las convenciones detalladas de una capa de la pila no llenen el contexto durante sesiones centradas 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
¿Se aplica?	No — Claude actúa sobre ello como guía	Sí — las reglas deny bloquean llamadas a herramientas incondicionalmente
Formato	Markdown de formato 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 preguntar. Esto acelera las sesiones interactivas para operaciones en las que confías. La lista deny bloquea comandos incondicionalmente — sin importar lo que Claude decida hacer, sin importar lo que diga CLAUDE.md. Usa deny para operaciones irreversibles sobre datos o infraestructura de producción.

Los ajustes de nivel de usuario en ~/.claude/settings.json se aplican a todos los proyectos. Los ajustes de proyecto en .claude/settings.json se aplican solo en ese repositorio. Los ajustes de proyecto tienen prioridad sobre los de usuario cuando se superponen.

Si tu equipo también necesita una referencia de empaquetado para herramientas MCP, no solo reglas para gobernarlas, combina estas protecciones con la guía de documentación de plugins de Claude Code. Explica dónde encaja un plugin MCP en relación con las reglas, los hooks y la configuración independiente.

Memoria automática: las notas de Claude

La memoria automática es la contraparte de CLAUDE.md. Mientras que CLAUDE.md son instrucciones que escribes tú, 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 guardarlo 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 digas de nuevo.

El directorio de memoria contiene:

~/.claude/projects/<repo>/memory/
  MEMORY.md          # index Claude uses to find other files; first 200 lines load each session
  debugging.md       # patterns Claude discovered solving problems in this repo
  conventions.md     # conventions Claude learned from your corrections

Esto es local a la máquina y por repositorio. La memoria automática complementa a 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 explorar y editar los archivos. Si algo está desactualizado o es incorrecto, elimínalo — Claude dejará de aplicar la regla obsoleta.

Mejores prácticas para la codificación agéntica

Ejecutar Claude Code de forma autónoma — mediante claude -p, el Agent SDK o pipelines de CI — eleva la importancia de tu configuración de reglas. El agente puede completar docenas de llamadas a herramientas sin pausarse, y no hay ida y vuelta interactivo para detectar malentendidos a mitad de la ejecución.

Escribe restricciones explícitas, no solo preferencias. Claude interactivo puede pedirte aclaraciones. 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 a partir de la estructura del código.

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, hacen commits permanentes en el historial de git o eliminan datos.

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

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 — coloca las reglas de cada capa en .claude/rules/ con alcance por ruta. Un único CLAUDE.md de 400 líneas con todo dentro 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. La documentación larga de API, los procedimientos de despliegue de varios pasos y los manuales 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 diga «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.

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

El contexto 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 agéntico de alto volumen.

La configuración es una variable de entorno:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-novita-api-key>"
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. Tu CLAUDE.md, reglas de alcance por ruta y settings.json se aplican exactamente igual que antes — la capa de reglas está por encima de la selección del modelo.

Novita AI aloja modelos de pesos abiertos centrados en codificación, incluyendo Qwen3-Coder, GLM-4.7, MiniMax M2.5 y DeepSeek V4. Estos modelos están optimizados para uso de herramientas en varios pasos y llamadas a funciones, lo que encaja bien con los patrones de llamada a herramientas que Claude Code usa internamente para ediciones de archivos, comandos de shell y navegación del repositorio.

Para equipos que ejecutan tareas agénticas a escala — pipelines de revisión de código, refactorización automatizada en repositorios grandes, generación de pruebas — los modelos de pesos abiertos en Novita suelen costar significativamente menos por millón de tokens que las alternativas de código cerrado, mientras siguen leyendo y aplicando eficazmente las reglas de tu proyecto.

Si estás ejecutando agentes contra un código de producción y quieres una capa de seguridad adicional más allá de las reglas deny, considera combinar la API LLM de Novita con el Agent Sandbox de Novita. 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 permanece contenido.

Preguntas frecuentes

¿Qué es CLAUDE.md en Claude Code?

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

¿Qué debería poner en los archivos de reglas de Claude (md)?

Escribe lo que de otro modo tendrías que reexplicar en cada sesión: comandos de compilación y prueba, convenciones de código que difieren de los valores predeterminados del framework, restricciones de arquitectura y errores conocidos del código. Omite el contenido que Claude puede deducir del propio código: á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 un cumplimiento consistente.

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

CLAUDE.md es instrucciones que Claude sigue como guía. settings.json es configuración que Claude Code aplica a nivel de sistema. Una regla en CLAUDE.md moldea 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 sin importar lo que Claude decida — eliminaciones irreversibles, fuerza de push, 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 por ruta que se cargan solo cuando Claude trabaja 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 eficaz para imponer un comportamiento consistente tanto en contextos interactivos como automatizados. Hacer commit en control de versiones garantiza que cada ejecución — local y 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. Gestiona el contexto manteniendo CLAUDE.md conciso, usando .claude/rules/ para cargar contenido de dominio solo cuando es relevante, y usando /compact para resumir sesiones largas sin perder continuidad. Después de /compact, Claude vuelve a leer el CLAUDE.md de la 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 agéntica en un equipo?

Haz commit del 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 por 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 del CI — es local a la máquina y por desarrollador; el CLAUDE.md versionado es la fuente de verdad para el comportamiento compartido.

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

Artículos recomendados

• Cómo usar los agentes de Claude Code: configuración, herramientas, permisos y flujo de trabajo con sandbox
• Plugins de Claude Code: cómo las herramientas MCP extienden Claude Code con capacidades externas
• Documentación de la CLI de Claude Code: configuración, comandos slash e integración de la API LLM
• SDK de Claude Code: crea agentes autónomos con Python y TypeScript
• Creación de un agente de codificación con el Agent Sandbox de Novita

---

Fuentes consultadas el 21 de julio de 2026: documentación de memoria de Claude Code, resumen de funciones de Claude Code, API LLM de Novita AI