Gestión de contexto de Claude Code

La gestión del contexto es una habilidad fundamental para usar Claude Code de manera eficiente.

La documentación oficial señala claramente:La ventana de contexto es el recurso más importante de Claude Code, y a medida que el contexto se llena, el rendimiento del modelo disminuye gradualmente (lo que se denomina deterioro del contexto, context rot): este es el problema central que hay que combatir activamente al usar Claude Code.

Este capítulo explica en profundidad cómo mantener a Claude en un estado eficiente en sesiones largas y entre sesiones mediante el archivo de instrucciones CLAUDE.md, el sistema de memoria automática, los comandos de optimización de la ventana de contexto y otros medios.


Fundamentos de la ventana de contexto

1. ¿Qué contiene la ventana de contexto?

El tamaño de la ventana de contexto de Claude Code es de1,000,000 tokens (1 millón de tokens). Contiene todo lo que Claude "ve" en la sesión actual:

Fuente de contenido Momento de carga Ocupación de tokens
Prompt del sistema (normas de comportamiento de Claude Code) En cada inicio de sesión Ocupación fija
Archivo CLAUDE.md Carga completa al inicio Depende del tamaño del archivo
Memoria automática (Auto memory) Carga al inicio (primeras 200 líneas o 25 KB) Tiene un límite máximo
Historial de conversación Crecimiento acumulativo Aumenta continuamente con la sesión
Resultados de herramientas (lectura de archivos, salida de comandos, etc.) Se añade después de cada llamada a herramienta Los registros/archivos grandes consumen muy rápido
Nombres de herramientas MCP, descripciones de Skills, etc. Carga al inicio Medio

2. Deterioro del contexto (Context rot)

La documentación oficial señala claramente: a medida que el contexto se llena,el rendimiento del LLM disminuye, porque la atención se dispersa sobre más tokens y el contenido antiguo e irrelevante comienza a interferir con la tarea actual. Los síntomas concretos incluyen:

  • Claude comienza a contradecirse y olvida decisiones previamente tomadas
  • Las respuestas se vuelven vagas, generales y con menos detalles
  • Pregunta repetidamente lo que ya se ha respondido sobre el mismo problema
  • Corrige más de dos veces el mismo problema en una misma sesión

Si aparecen los síntomas anteriores, significa que el contexto está "contaminado"; en ese momento se debe usar activamente/compacto/clearpara solucionarlo, en lugar de seguir corrigiendo en la misma sesión.

Usa el comando/contextpara ver en cualquier momento el análisis detallado del uso del contexto actual:

/context

Este comando enumera la ocupación de tokens por categoría (prompt del sistema, CLAUDE.md, archivos de memoria, historial de sesión, etc.) y ofrece sugerencias de optimización. Se recomienda comprobarlo antes de comenzar tareas importantes.


Archivo de instrucciones CLAUDE.md

CLAUDE.md es el archivo central en Claude Code que registra instrucciones estáticas y normas del proyecto. En cada inicio de sesión, Claude lo carga automáticamente en la ventana de contexto.

1. Ubicación y alcance

CLAUDE.md admite múltiples ubicaciones,y cuanto más específica es la ubicación, mayor es su prioridad.:

Alcance Ruta de archivo Escenario de aplicación ¿Se envía a git?
Nivel de organización macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux/WSL: /etc/claude-code/CLAUDE.md
Estándares de codificación de la empresa, requisitos de cumplimiento Gestionado centralizadamente por TI
Nivel de proyecto ./CLAUDE.mdo./.claude/CLAUDE.md Arquitectura del proyecto, normas de codificación, flujo de trabajo Sí, compartido con el equipo
Nivel de usuario ~/.claude/CLAUDE.md Preferencias de codificación personales, aplicable a todos los proyectos No, privado personal
Privado local ./CLAUDE.local.md(añadir a .gitignore) Configuración personal específica del proyecto, no se envía a git No, añadir a .gitignore

CLAUDE.local.mdEs la forma oficial recomendada para la configuración privada personal: contenido que no debe compartirse, como URL de sandbox, cuentas de prueba locales, hábitos de depuración personales, debe colocarse aquí en lugar de enCLAUDE.md. Al ejecutar/init, selecciona la opción "Personal" y automáticamente añadirá ese archivo a.gitignore。

2. Crear CLAUDE.md

Ejecuta el siguiente comando y Claude analizará automáticamente el proyecto y generará un CLAUDE.md inicial:

/init

Si ya existe un CLAUDE.md,/initsugerirá mejoras en lugar de sobrescribirlo directamente. Después de la generación, añade manualmente contenido que Claude no puede descubrir automáticamente (como archivos que no deben modificarse, restricciones especiales, etc.).

También puedes usar el atajo#durante la sesión para añadir rápidamente un recordatorio a CLAUDE.md:

# 所有 API 错误响应必须使用 { code, message } 格式

Pulsa#y después de introducir el contenido y pulsar Enter, Claude lo escribirá en el CLAUDE.md del nivel correspondiente y lo guardará como instrucción persistente.

3. Requisitos de contenido de CLAUDE.md

La documentación oficial exige que cada archivo CLAUDE.mdse limite a menos de 200 líneas.Cuanto más grande es el archivo, más tokens de inicio consume y menor es la tasa de cumplimiento de Claude. A continuación se ofrecen sugerencias de contenido:

Se debe escribir:

  • Comandos habituales de compilación, prueba e implementación
  • Normas de código: convenciones de nombres, sangría, patrones prohibidos
  • Restricciones clave: "usar siempre pnpm", "prohibido modificar el directorio migrations/"
  • Descripción de la arquitectura del proyecto: propósito de los directorios principales

No se debe escribir:

  • Procesos de operación de varios pasos (deben colocarse en archivos de Skills)
  • Reglas relacionadas solo con una parte del repositorio (deben usar.claude/rules/limitación por ruta)
  • Información que Claude puede descubrir por sí mismo al leer el código

Ejemplo

# Ejemplo de CLAUDE.md (conciso y específico, cada archivo se limita a menos de 200 líneas)

## Comandos habituales
- Gestión de paquetes: usar siempre pnpm, no usar npm ni yarn
- Ejecutar pruebas: pnpm test:watch
- Compilar: pnpm build

## Normas de código
- Modo estricto de TypeScript, no se permite any
- Los archivos de componentes usan nombres PascalCase (por ejemplo, UserProfile.tsx)
- Las marcas de tiempo de la base de datos usan formato UTC de manera uniforme

## Restricciones
- Prohibido modificar directamente los archivos existentes en el directorio prisma/migrations/
- .env.local contiene claves reales; prohibido leer o mostrar el contenido del archivo
- Las interfaces de API se gestionan de manera uniforme en el directorio src/api/; no realizar solicitudes directamente en otros lugares

4. Reglas limitadas por ruta (.claude/rules/)

Para proyectos grandes, se puede usar.claude/rules/el directorio para dividir las instrucciones en reglas detalladas que se aplican según la ruta del archivo, evitando que todas las reglas se acumulen en el CLAUDE.md raíz y consuman tokens de inicio:

.claude/
└── rules/
    ├── api.md         # 只对 src/api/**/*.ts 文件生效
    ├── frontend.md    # 只对 src/components/**/*.tsx 文件生效
    └── testing.md     # 只对 *.test.ts 文件生效

Las reglas limitadas por ruta solo se cargan cuando Claude lee archivos en el directorio correspondiente, y no ocupan contexto completo al inicio.


Memoria automática (Auto memory)

La memoria automática es un sistema de memoria entre sesiones integrado en Claude Code v2.1.59 y versiones posteriores.Activado por defecto, sin necesidad de configuración. Permite que Claude registre de forma autónoma, durante el trabajo, información como comandos de compilación, experiencias de depuración y preferencias de estilo de código descubiertas.

1. Mecanismo de funcionamiento

  • Claude no escribe memoria en cada sesión; decide si la información merece conservarse (si será útil en conversaciones futuras).
  • La memoria está aislada por ruta de repositorio git y se almacena en~/.claude/projects/<项目路径>/memory/
  • Todos los árboles de trabajo del mismo repositorio comparten una misma memoria automática.
  • Al escribir memoria, la terminal muestra "Writing memory"; en la próxima recuperación, muestra "Recalled memory".

2. Ver y editar memoria (/memory)

Usa/memoryel comando para ver y editar todo el contenido de memoria, incluidos los CLAUDE.md de cada nivel y la memoria automática:

/memory

En el editor puedes eliminar entradas inexactas, o usar el interruptor Auto memory para desactivar la memoria automática. También se puede desactivar temporalmente mediante una variable de entorno:

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

3. Hacer que Claude recuerde contenido activamente

Durante la conversación puedes pedirle directamente a Claude que escriba en la memoria:

记住:我们的 API 测试需要本地运行一个 Redis 实例
以后请记住:处理错误时,统一返回 { code, message } 结构

Si quieres elevarlo a una norma obligatoria en lugar de solo una preferencia recordada, puedes decir: "Escribe esta regla en CLAUDE.md"; Claude la escribirá en el archivo CLAUDE.md correspondiente.


Comandos de optimización de la ventana de contexto

1. Compresión automática (Auto-compaction)

Claude Code, cuando elcontexto se acerca al límite, activa automáticamente la compresión(aproximadamente al 75% de uso), resume el historial de conversación en un resumen y continúa trabajando. Sin embargo, la recomendación oficial es no esperar a la compresión automática, sinoactivarla manualmente de forma proactiva al 60~70%, para evitar ser interrumpido en medio de tareas críticas; además, la compresión proactiva permite controlar con instrucciones qué contenido se conserva.

2. Comprimir contexto (/compact)

Comprime manualmente el historial de conversación, resumiendo sesiones largas en un resumen conciso para continuar trabajando:

/compact

/compactAdmite instrucciones personalizadas para controlar qué contenido se prioriza al comprimir:

/compact Focus on the API changes
/compact 保留认证流程的架构决策,丢弃调试过程中的无效尝试

La compresión es una operación con pérdida. Al comprimir, Claude está en el estado de contexto más lleno y con el menor rendimiento; si no se le dan instrucciones, puede descartar contenido que consideras importante.Comprime proactivamente justo después de una decisión importante e indica con instrucciones los puntos clave a conservar, y es mucho más efectivo que esperar a la compresión automática.

3. Limpiar contexto (/clear)

Al cambiar a una tarea completamente nueva, limpia todo el historial de conversación:

/clear

Después de limpiar, CLAUDE.md y la memoria automática no se ven afectados y se seguirán cargando en la nueva sesión. Recomendación oficial:Si has corregido el mismo problema más de dos veces en la misma sesión, más vale hacer /clear directamente y reiniciar con un prompt más preciso, llevando las restricciones aprendidas.— una sesión limpia y un mejor prompt son casi siempre mejores que seguir corrigiendo en un contexto contaminado.

4. Retroceder a un punto de control (/rewind)

Claude Code crea automáticamente un punto de control antes de cada modificación de archivo. Haz doble clicEsco ejecuta/rewindpara abrir el menú de retroceso y seleccionar el punto de control a restaurar:

/rewind
(或双击 Esc 键)

En el menú de retroceso, puedes elegir las siguientes acciones:

Acción Efecto Cuándo usarlo
Restaurar conversación + código Revierte el historial de conversación y los cambios en archivos, restaurando por completo. Claude se desvió y los cambios tienen problemas; deshacer todo.
Restaurar solo la conversación Revierte el historial de conversación pero conserva los cambios en archivos. Quieres probar un enfoque distinto, pero los cambios de código se pueden conservar.
Restaurar solo el código Restaura los archivos al estado del punto de control, conservando la conversación. El código se ha estropeado, pero el análisis en la conversación tiene valor de referencia.
Resumir desde aquí (Summarize from here) Comprime la conversación posterior a este punto de control en un resumen, conservando el historial completo previo. Solo quieres limpiar la segunda mitad de la conversación que es redundante, conservando el contexto completo de la primera parte.

Los puntos de control se guardan de forma persistente entre sesiones: incluso después de cerrar la terminal, todavía puedes retroceder a puntos de control anteriores. No es un sustituto de git, pero en experimentos exploratorios es más cómodo que hacer git stash manualmente.

5. Pregunta rápida sin contaminar el contexto (/btw)

Si necesitas consultar rápidamente un pequeño detalle, pero no quieres que esa pregunta y respuesta entren en el historial de conversación (consumiendo contexto), usa/btw:

/btw 这个项目的 TypeScript 版本是多少?

La respuesta se muestra como superposición; ni la pregunta ni la respuesta entran en el historial de conversación. Es adecuado para consultar configuraciones, números de versión y otra información puntual que no requiere conservarse.


Comandos de gestión de sesión

Comando Función Cuándo usarlo
/context Ver el análisis detallado del uso de tokens de cada parte del contexto. Investigar qué parte consume demasiados tokens.
/compact [指令] Comprimir el historial de conversación en un resumen, con opción de especificar qué conservar como prioridad. Comprimir proactivamente cuando el contexto esté al 60~70%.
/clear Limpiar todo el historial de conversación, conservando CLAUDE.md y la memoria. Cambiar a una tarea nueva, o cuando el contexto está gravemente contaminado.
/rewind(o doble clic en Esc) Abrir el menú de puntos de control; se puede elegir restaurar conversación/código/ambos, o resumir desde un punto determinado. Claude se desvió; hay que retroceder y volver a intentar.
/memory Ver y editar el contenido de CLAUDE.md y de la memoria automática. Comprobar si la memoria es precisa y eliminar entradas obsoletas.
/btw Hacer una pregunta rápida; la respuesta no entra en el historial de conversación. Consultar pequeños detalles sin querer contaminar el contexto.
/init Analizar el proyecto y generar o mejorar CLAUDE.md. Primer uso en un proyecto nuevo, o cuando el proyecto ha tenido cambios importantes.
#(atajo de teclado) Añadir rápidamente una instrucción persistente a CLAUDE.md. Registrar normas o convenciones en cualquier momento.
claude --continue Continuar la sesión más reciente. Para seguir trabajando después de reabrir la terminal.
claude --resume Seleccionar una sesión de la lista de historial para continuar. Retomar una tarea específica de hace unos días.

Preguntas frecuentes y soluciones

Problema 1: Claude no respeta las reglas de CLAUDE.md

  • Comprueba si CLAUDE.md es demasiado grande (la tasa de cumplimiento disminuye cuando supera las 200 líneas).
  • Convierte las expresiones vagas en instrucciones concretas: no digas "escribe código limpio", sino "usa sangría de 2 espacios".
  • usar/memoryComprueba si hay entradas contradictorias en la memoria automática.
  • Considera usar.claude/rules/para dividir las reglas por ruta de archivo, reduciendo así la cantidad que se carga cada vez.

Problema 2: Claude empieza a contradecirse y "olvida" las decisiones anteriores.

  • Es un síntoma típico de degradación del contexto; no sigas corrigiendo en la misma sesión.
  • Ejecuta/compact 保留关键决策, o directamente/cleary luego reinicia con un resumen.
  • Las conclusiones importantes, usa#el atajo de teclado para escribirlas en CLAUDE.md, asegurando que sigan siendo válidas en la próxima sesión.

Problema 3: pérdida de información clave después de /compact

  • Al comprimir, pasa instrucciones concretas:/compact 保留认证流程的架构决策和已确认的 API 格式
  • Escribe las conclusiones más importantes en CLAUDE.md antes de comprimir.
  • Los intentos de depuración fallidos no merecen conservarse; puedes comprimir de forma más agresiva o usar /clear.

Problema 4: cómo continuar el trabajo anterior después de cerrar la terminal

  • Usaclaude --continuepara continuar la sesión más reciente.
  • Usaclaude --resumepara seleccionar una sesión específica de la lista de historial.
  • usar/renameAsigna a las sesiones importantes un nombre descriptivo (por ejemplo, "oauth-migration") para encontrarlas más adelante.

Problema 5: una tarea grande genera muchas salidas de herramientas, ¿cómo evitar que el contexto se llene?

  • Usa subagentes (subagent) para delegar la ejecución: el diálogo principal solo recibe el resumen, y las salidas intermedias permanecen en el contexto independiente del subagente.
  • Por ejemplo:Usa sub-agentes para analizar todos los archivos de registro, identifica los cuellos de botella de rendimiento y solo dime las conclusiones.
Otras extensiones