Saltar al contenido

Contexto para agentes de IA: tu agente no necesita leer todo tu repo

Guía/ 11 min de lectura

Tres reglas para darle a un agente de IA el contexto justo: nombrar los archivos, un CLAUDE.md de menos de 200 líneas y saber cuándo compactar o limpiar.

  • IA
  • Claude Code
En este artículo (8)
  1. Qué es el contexto de un agente y por qué importa lo relevante, no la cantidad
  2. Regla 1: indicar los archivos que importan
  3. Regla 2: un CLAUDE.md corto (qué sí y qué no poner)
  4. Regla 3: compactar o empezar limpio
  5. Señales de un contexto saturado
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

El contexto de un agente de IA es todo lo que tiene a la vista en la sesión: tus instrucciones, los archivos que leyó y la conversación. No mejora por tener más, sino por tener lo relevante: los archivos de la tarea, un CLAUDE.md corto y una sesión limpia cuando cambias de tema.

Aquí lo bajamos a tres reglas con Claude Code, verificadas contra su documentación: indicar los archivos que importan, mantener un CLAUDE.md corto y saber cuándo usar /compact o /clear. Al final, cómo reconocer un contexto saturado. Si vienes de cómo reportarle un bug a la IA, esta es la otra mitad: qué le das al agente además del reporte.

Qué es el contexto de un agente y por qué importa lo relevante, no la cantidad

Según la página de la ventana de contexto de Claude Code, el contexto guarda todo lo que Claude sabe de tu sesión: tus instrucciones, los archivos que lee, sus propias respuestas y contenido que nunca aparece en tu terminal. Antes de que escribas nada ya se cargan el CLAUDE.md, la memoria automática, los nombres de las herramientas MCP y las descripciones de las skills. Después, cada archivo que lee suma.

Dos ideas de la guía de buenas prácticas explican por qué la cantidad no ayuda. La primera: cada petición envía la conversación completa, así que una sesión que acumuló tres tareas sin relación vuelve a leer las tres en cada turno de la cuarta. La segunda: Claude empieza cada tarea leyendo tu código, y los modelos actuales son muy buenos en eso; encuentran la estructura, las convenciones y el framework de tests por su cuenta. Lo que no pueden encontrar es lo que nunca estuvo en el repo: una decisión de una junta, un proceso de despliegue que solo alguien conoce, la variable de entorno que piden los tests.

Eso cambia la pregunta. No es «¿cómo le doy todo el repo?», sino «¿qué necesita que no puede ver?».

lo que el agente necesita para arreglar el carritoapp/checkout/límite: «no toques app/checkout/»productos/layout.tsxcomponents/carrito/CarritoProvider.tsx@ en el prompt: se lee completoproducto/BotonAgregar.tsx@ en el promptlegacy/lib/package.jsonCLAUDE.mdse carga al iniciar cada sesiónel resto: lo busca si lo necesita2 archivos con @, 1 límite, nada másClaude lee el repo por su cuenta: dale lo que no puede ver

Desliza la figura para verla completa

Qué entra en el contextoCuándoCómo lo controlas
CLAUDE.md del proyecto, de usuario y de las carpetas superioresAl iniciar la sesiónLo que escribes en ellos; /memory para abrirlos
CLAUDE.md de subcarpetasCuando Claude lee o edita un archivo en esa carpetaDónde los pones
Reglas de .claude/rules/ con pathsCuando trabaja con un archivo que coincideLos patrones de paths
Archivos que leeEn cada lecturaNombrar los archivos con @ y poner límites
La conversaciónEn cada mensaje/compact, /clear, /rewind

Regla 1: indicar los archivos que importan

La guía de buenas prácticas lo resume así: si nombras el archivo, describes el síntoma y dices cómo se ve «arreglado» desde el principio, normalmente te ahorras una ronda de correcciones. Y si ya tienes el archivo, dáselo en lugar de describirlo: escribe @ y la ruta para incluir su contenido en el mensaje. Este es un prompt para una tienda en Next.js (los nombres de archivo son de ejemplo):

Al tocar "Agregar al carrito", el contador del header no cambia hasta
recargar la página. El botón está en @components/producto/BotonAgregar.tsx
y el estado del carrito en @components/carrito/CarritoProvider.tsx.
Arréglalo en esos dos archivos y no toques app/checkout/.
Está listo cuando el número cambia sin recargar y npm run lint pasa.
  1. La primera frase es el síntoma, contado como lo vería un cliente: qué haces y qué no pasa.
  2. Las dos rutas con @ meten el contenido de esos archivos en el mensaje. Claude no tiene que buscarlos ni leer los vecinos para adivinar dónde vive el estado.
  3. «no toques app/checkout/» es un límite. Sin él, un arreglo del carrito puede acabar «mejorando» el checkout.
  4. La última línea dice qué cuenta como terminado y con qué comando se comprueba.

¿Y si no sabes qué archivos son? No adivines ni le pidas que lea todo: pídele que los busque y te los diga antes de cambiar nada, o usa plan mode, que explora y propone sin editar. Para búsquedas grandes, la documentación sugiere un subagente: trabaja en su propia ventana de contexto y a la tuya solo vuelve el resumen.

Regla 2: un CLAUDE.md corto (qué sí y qué no poner)

El CLAUDE.md se carga en cada sesión, y la guía advierte que por eso cada línea le quita un poco de atención a Claude en todas las tareas, sea relevante o no. La documentación de memoria pone la cifra: apunta a menos de 200 líneas por archivo, porque los archivos más largos consumen más contexto y reducen el cumplimiento. Partirlo en imports con @ruta ayuda a ordenarlo, pero no reduce su costo: los archivos importados se cargan junto con el que los importa.

Sí va en CLAUDE.mdNo va
Los comandos exactos de lint, tipos y testsLa estructura de carpetas: Claude la lee solo
Partes del código que engañan, como un patrón viejo que no hay que copiarLa lista de dependencias
Decisiones que no están en el repoReglas genéricas como «escribe código limpio»
Lo que ya tuviste que corregir dos vecesProcedimientos de varios pasos: van en una skill
Límites claros sobre qué no tocarReglas que no pueden fallar: van en un hook

Esta es una plantilla para un proyecto de Next.js. Tiene 15 líneas:

@AGENTS.md

# Comandos
- Servidor de desarrollo: npm run dev
- Lint: npm run lint
- Tipos: npx tsc --noEmit
- Build de producción: npm run build, solo si te lo pido.

# Convenciones
- Los precios llegan en centavos; formatéalos con lib/precio.ts.
- components/legacy/ sigue en uso, pero no copies sus patrones.

# Cuidado
- app/checkout/ y app/api/pagos/: primero un plan, nunca un cambio directo.
- No leas ni imprimas .env.local.
  1. @AGENTS.md importa ese archivo si tu proyecto lo tiene; la configuración por defecto de create-next-app lo incluye. Según la documentación, cuando existe un CLAUDE.md, Claude Code lee el CLAUDE.md y no el AGENTS.md, salvo que lo importes así. Si no tienes AGENTS.md, borra la línea.
  2. # Comandos son los scripts que la documentación de instalación de Next.js pone en package.json (dev, build, lint) más la comprobación de tipos de TypeScript. Es lo que Claude necesita para revisar su propio trabajo; la línea del build dice cuándo correrlo.
  3. # Convenciones son dos ejemplos de lo que el código no dice: en qué unidad llegan los precios y qué carpeta sigue viva pero no se debe imitar. Cámbialas por las tuyas.
  4. # Cuidado son límites. El de .env.local es una instrucción, no una protección: la documentación aclara que Claude trata el CLAUDE.md como contexto, no como configuración obligatoria. Para que no pueda leerlo de ninguna forma, usa un hook que proteja el .env.
anatomía de un CLAUDE.md cortoCLAUDE.md15 líneas@AGENTS.md# Comandos- npm run dev- npm run lint- npx tsc --noEmit# Convenciones- precios en centavos: lib/precio.ts- components/legacy/: no copiar# Cuidado- app/checkout/: plan primero- no leer .env.localel import entra completocómo comprueba su trabajo:comandos exactoslo que leer el códigono le dicelímites; si no puede fallar,es un hook, no una líneamenos de 200 líneas: lo que Claude no puede deducirfuera: estructura de carpetas, dependencias, reglas genéricas

Desliza la figura para verla completa

Dónde vive y cómo se carga, según la documentación:

  • Proyecto: ./CLAUDE.md o ./.claude/CLAUDE.md, compartido con el equipo en git. Usuario: ~/.claude/CLAUDE.md, para todos tus proyectos. Local: CLAUDE.local.md, tus preferencias en este proyecto, agregado a .gitignore.
  • Los de la carpeta donde arrancas y los de las carpetas superiores se cargan al iniciar; los de subcarpetas, cuando Claude trabaja en ellas. No se reemplazan entre sí: se concatenan.
  • /init genera un primer CLAUDE.md a partir de tu código y, si ya existe, sugiere mejoras. La guía dice que desde ahí el trabajo es sobre todo quitar líneas.
  • /memory lista y abre los archivos de memoria; /context te deja confirmar que cargaron, en la lista Memory files.
  • Si una regla solo importa en una parte del código, va en .claude/rules/ con un campo paths: se carga cuando Claude toca archivos que coinciden.

Un detalle que la guía remarca: si Claude ignora una línea que sí está en tu CLAUDE.md, escribir IMPORTANT probablemente no lo arregle. O el archivo creció tanto que la línea se pierde, o es una regla sin excepciones y va en un hook.

Regla 3: compactar o empezar limpio

Claude Code compacta solo cuando la sesión se acerca al límite, así que un contexto lleno no termina tu sesión. Lo que sí puedes hacer es decidir antes qué se queda. Según la referencia de comandos, hay dos comandos para eso y conviene no confundirlos:

  • /compact [instrucciones] resume la conversación para liberar espacio y acepta instrucciones de foco para el resumen. Después de compactar, el CLAUDE.md de la raíz del proyecto se vuelve a leer del disco.
  • /clear empieza una conversación nueva con el contexto vacío (sus alias son /reset y /new). La anterior se puede retomar con /resume.

Un /compact con foco, para una sesión larga en el mismo arreglo del carrito:

/compact conserva los cambios en components/carrito/ y los comandos de prueba; descarta la exploración de app/checkout/
  • «conserva…» dice qué debe sobrevivir al resumen: los cambios del carrito y los comandos de prueba. La documentación explica que así el resumen guarda lo que tú eliges y no lo que adivina la compactación automática.
  • «descarta…» nombra el ruido: la exploración del checkout que ya no hace falta.
qué comando usar según la situaciónsituacióncomandoqué quedamisma tarea, sesión larga/compact <foco>un resumen y elCLAUDE.md del proyectotarea nueva, sin relación/clearconversación vacía;CLAUDE.md se cargacorregiste lo mismodos veces/clearun prompt nuevo conlo que aprendisteuna parte es ruido/rewindresumen desde o hastael mensaje que elijasno sabes qué ocupa espacio/contextnada: solo midelo que está en disco sobrevive; el chat nouna instrucción que solo diste en el chat puede perderse al compactar

Desliza la figura para verla completa

La regla de la guía para /clear es concreta: si corregiste lo mismo dos veces y sigue mal, una tercera corrección solo suma a una conversación que ya tiene dos intentos fallidos que Claude vuelve a leer. Mejor /clear y un prompt nuevo que incluya lo que aprendiste. Y entre tareas sin relación, /clear también: la conversación vieja desplaza a los archivos que necesitas después y cuesta tokens en cada mensaje.

Hay un punto medio: /rewind te deja elegir un mensaje y resumir desde ahí o hasta ahí, cuando solo una parte de la conversación se volvió ruido. Y una advertencia de la documentación: una instrucción que diste solo en el chat puede perderse al compactar. Si importa, va en el CLAUDE.md.

Señales de un contexto saturado

Ninguna es una métrica exacta; son situaciones que la documentación describe y que vale la pena vigilar:

  • Corriges lo mismo por segunda vez. Es el punto en que la guía recomienda /clear y un prompt mejor.
  • Olvidó una instrucción que diste en el chat, sobre todo después de una compactación. Llévala al CLAUDE.md.
  • Mezcla detalles de la tarea anterior con la actual: acumulaste tareas sin relación en la misma sesión.
  • Ignora una línea de tu CLAUDE.md. Revisa su largo y busca instrucciones que se contradigan: la documentación avisa que, ante dos instrucciones opuestas, Claude puede elegir cualquiera de las dos.
  • /context muestra avisos. El comando dibuja el uso del contexto como una cuadrícula de colores y da sugerencias para herramientas que ocupan mucho, memoria inflada y avisos de capacidad.

Errores comunes

  • Pedir «lee todo el proyecto» antes de empezar. Llena el contexto de archivos que la tarea no usa. Nombra los que importan o pide que los busque.
  • Describir la arquitectura y las carpetas en el CLAUDE.md. La guía lo pone en su lista de consejos que ya puedes dejar: Claude lee el repo por su cuenta.
  • Usar mayúsculas e IMPORTANT para que te haga caso. Si una línea se pierde, el archivo necesita ser más corto.
  • Confiar en el CLAUDE.md para algo que no puede fallar. Es contexto; para bloquear, un hook.
  • Encadenar tareas sin /clear. Cada tarea nueva arrastra y paga la historia de las anteriores.
  • Dar instrucciones importantes solo en el chat. Pueden perderse al compactar.

Preguntas frecuentes

¿/compact o /clear borran mi CLAUDE.md?

No. El CLAUDE.md vive en disco. Después de /compact, el de la raíz del proyecto se vuelve a inyectar; después de /clear, la conversación nueva lo carga al empezar, como cualquier otra.

¿Cuántas líneas debe tener mi CLAUDE.md?

La documentación recomienda menos de 200 por archivo. Las plantillas de este artículo y de la guía tienen 15 y 14. Lo importante no es el número, sino que cada línea sea algo que Claude no podría deducir leyendo el código.

¿Esto sirve para otros agentes, como Cursor o Codex?

Los comandos de este artículo son de Claude Code. La idea de nombrar archivos, poner límites y mantener un archivo de instrucciones corto no depende de la herramienta, y varios agentes leen AGENTS.md; con el import @AGENTS.md compartes ese mismo archivo con Claude Code.

¿Cómo sé qué tiene cargado ahora?

Con /context: muestra el uso por categoría y la lista de archivos de memoria que cargaron. Con /memory abres y editas esos archivos.

Checklist

  • El prompt nombra los archivos de la tarea con @ y dice qué no tocar.
  • El prompt dice cómo se ve «terminado» y con qué comando se comprueba.
  • Tu CLAUDE.md tiene menos de 200 líneas y solo lo que Claude no puede deducir.
  • Los comandos del CLAUDE.md existen en tu package.json o en tu CLI.
  • Lo que no puede fallar está en un hook, no en una línea del CLAUDE.md.
  • Usas /clear entre tareas sin relación y después de dos correcciones fallidas.
  • Usas /compact con foco cuando sigues en la misma tarea.
  • /context muestra tu CLAUDE.md en la lista de archivos de memoria.

Un agente con el contexto justo se equivoca menos y te cuesta menos. Para el método completo, sigue mi flujo de 4 pasos con Claude Code; para revisar antes de editar, plan mode en Claude Code; para reportar un fallo con todo lo que hace falta, cómo reportarle un bug a la IA; y para poder deshacer lo que haga el agente, git para trabajar con agentes de IA.

¿Viste esto en Instagram? Comenta CONTEXTO en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 30 de octubre de 2026 · actualizado el 1 de noviembre de 2026

← Blog