🍔 El problema: CLAUDE.md inflado
¿Eres nuevo aquí? Ya viste en la Trilha 0 que el CLAUDE.md es el «cerebro» que el agente lee al inicio de cada sesión. El problema: si empiezas a pegar allí instrucciones detalladas de cada herramienta MCP que instales, se convierte en un archivo enorme: leerlo entero cada vez cuesta más y es difícil de mantener.
¿Eres nuevo aquí? Cuando decimos que un archivo grande «cuesta más», es literal: todo agente de código lee el CLAUDE.md completo al inicio de cada conversación, y ese texto pasa a formar parte de lo que llamamos contexto — la «memoria a corto plazo» que el modelo mantiene mientras trabaja contigo. Un contexto más grande implica dos cosas negativas: pagas por más texto procesado en cada mensaje, y es más probable que el agente «pierda el hilo» entre una regla y otra porque compite por su atención con el resto de la conversación.
El patrón habitual es predecible: instalas un servidor MCP y pegas en el CLAUDE.md un párrafo que explica cuándo usar cada una de tus herramientas. La semana siguiente, instalas otro servidor y pegas otro párrafo. Después de instalar 4 o 5 servidores, el archivo que debía caber en una pantalla se convirtió en un documento de desplazamiento infinito — y la mayor parte se lee en cada mensaje, incluso cuando el tema de esa conversación no tiene nada que ver con scraping, bases de datos o correo electrónico.
Leyenda: cuanto más servidores MCP instalas sin separar las instrucciones en archivos aparte, más crece el CLAUDE.md, hasta convertirse en un archivo costoso de leer y difícil de mantener.
💡 Consejo práctico
Antes de pegar cualquier explicación de una herramienta nueva en CLAUDE.md, pregúntate: «¿es una regla general del proyecto o un detalle de UNA herramienta específica?». Si es un detalle de una herramienta, corresponde a una cheat sheet, no a CLAUDE.md; eso es precisamente lo que resuelve el siguiente tema.
✗ CLAUDE.md sobrecargado
- • 5 servidores MCP, cada uno con un párrafo pegado
- • Cada mensaje lee reglas que no tienen nada que ver con el tema
- • Encontrar una regla específica se convierte en una búsqueda en texto corrido
✓ CLAUDE.md conciso
- • Solo reglas generales del proyecto, cabe en una pantalla
- • Cada servidor MCP tiene su propia guía rápida
- • El agente solo abre la cheat sheet cuando surge el tema
📋 La solución: un archivo cheat sheet aparte
Leyenda: CLAUDE.md es breve y solo apunta a la hoja de referencia; es la hoja la que explica, con ejemplos, qué herramienta elegir en cada situación. Así, el agente acierta sin que tengas que repetir la explicación cada vez.
¿Eres nuevo aquí? Cheat sheet — en
portugués, "acordeón para el examen" — es un archivo markdown aparte, dedicado solo a enseñar al agente a elegir la
herramienta adecuada dentro de un dominio (por ejemplo, scraping). El CLAUDE.md se queda con una sola línea: "para
dudas sobre scraping, consulta cheat-sheet.md". El agente solo abre este archivo cuando surge el tema,
para mantener todo conciso en el día a día.
🔍 Mira por dentro: por qué funciona
No ocurre nada mágico: solo es una cuestión de lectura bajo demanda. CLAUDE.md se carga en toda mensaje; el cheat sheet solo se abre cuando el agente decide que lo necesita, generalmente cuando tú pides algo relacionado (por ejemplo, «descarga esta página»). En las conversaciones en las que no mencionas el scraping, el cheat sheet permanece en el disco, sin consumir nada de contexto. Es el mismo principio de carga bajo demanda que el Módulo 3 llamará carga progresiva — cargar primero lo esencial; los detalles, solo cuando surja el tema.
Esto también significa que la hoja de referencia puede crecer bastante sin problema: solo "cuesta" cuando se lee, y se lee pocas veces, siempre en el momento adecuado.
🧱 Anatomía de una buena cheat sheet
Un cheat sheet eficaz tiene tres partes: una tabla que compara las opciones, una regla de decisión en una frase («si X, usa Y») y ejemplos reales de solicitud → herramienta elegida. Nada de párrafos largos: el objetivo es consultar rápidamente, no leer de corrido.
Tabla comparativa
Las opciones una al lado de la otra — cuándo usar cada una, en una frase por línea.
Regla para decidir
Una frase corta como "si la solicitud menciona solo 1 página, usa scrape; si menciona 'todo el sitio', usa crawl".
Ejemplos reales
2-3 pares "pedido del usuario → herramienta elegida", para fijar el patrón.
La diferencia entre una cheat sheet que funciona y una que solo existe en el papel está en los detalles de redacción. Compara los dos ejemplos a continuación para el mismo servidor de scraping:
✗ Cheat sheet deficiente
- ✗"Usa la herramienta adecuada para cada tipo de scraping" — es vago, no dice cuál corresponde a cada uno
- ✗Párrafo de 8 líneas que explica la filosofía detrás de cada herramienta
- ✗Ningún ejemplo de una solicitud real del usuario
✓ Hoja de referencia completa
- ✓"1 página → scrape · lista de páginas → map · sitio entero → crawl"
- ✓Tabla de 3 filas, cada una con la herramienta y cuándo usarla
- ✓"quiero el texto de esta página" → scrape (ejemplo real)
✍️ Escribir tu primer cheat sheet
Puedes pedirle al propio agente que escriba un borrador de la cheat sheet y luego revisarlo. Empieza pidiéndole que documente las herramientas de un servidor MCP que acabas de instalar, en formato de tabla + regla de decisión.
Objetivo: tener una cheat sheet real en tu proyecto. Cómo verificar: el archivo cheat-sheet.md aparece en la carpeta con una tabla y el CLAUDE.md recibe una línea nueva que lo señala.
⚠️ Errores comunes al pedir la cheat sheet
- El agente inventa herramientas que no existen: si nunca
«conversó» con el servidor MCP antes (nunca llamó a ninguna herramienta), puede inventarse nombres. Pídele que
primero enumere las herramientas disponibles, generalmente con un comando como
/mcp— antes de documentar. - La cheat sheet se convierte en una copia de la documentación oficial: pegar toda la documentación del servidor no ayuda: ya es demasiado larga para ser una «consulta rápida». Pide explícitamente el formato de tabla + regla de decisión + ejemplos, no un resumen genérico.
- CLAUDE.md no se actualiza: a veces el agente crea la hoja de referencia, pero olvida agregar la línea de referencia en CLAUDE.md. Revisa ambos archivos, no solo el nuevo.
🔗 CLAUDE.md apunta, no repite
La regla de oro: el CLAUDE.md señala para los archivos de referencia, nunca los repite. Esto se aplica a las cheat sheets de MCP y se aplicará a las skills en la Trilha 3: es el mismo principio de carga progresiva; solo carga el detalle cuando el tema realmente aparece.
🔍 Por dentro
Es la misma razón por la que se organizan las carpetas en vez de usar un único archivo gigante: la información está disponible, pero solo ocupa «espacio» cuando realmente se lee.
Leyenda: CLAUDE.md es pequeño y está en el centro, con enlaces a archivos separados por tema; cada uno solo se lee cuando el tema correspondiente aparece en la conversación.
✗ Se repite
- • Pega toda la lista de herramientas MCP dentro del CLAUDE.md
- • Cada mensaje lee todo el contenido, lo uses o no
- • Actualizar significa editar un archivo enorme
✓ Apunta
- • Una sola línea: "para MCP, ver cheat-sheet.md"
- • El contenido detallado solo se lee cuando surge el tema
- • Actualizar significa editar el archivo pequeño y específico
🔄 Manteniendo viva la hoja de referencia
Cada vez que instales un servidor MCP nuevo o notes que el agente eligió la herramienta equivocada más de una vez, es señal de que debes actualizar la cheat sheet: agregar una fila a la tabla o dejar más clara la regla de decisión. Es un documento vivo, no un archivo que se escribe una vez y se olvida.
Piensa en la cheat sheet como una planta que necesita agua de vez en cuando, no como un monumento que se construye una vez y queda listo para siempre. Los tres motivos más comunes para revisarla son: instalar un servidor MCP nuevo, notar que se repite una elección equivocada de herramienta y que el propio servidor cambie (herramientas renombradas, parámetros nuevos).
Nuevo servidor MCP instalado
Pídele al agente que documente sus herramientas en una nueva cheat sheet o en una nueva sección de una existente.
Elección equivocada, más de una vez
Si ya corregiste dos veces «no, usa X» para el mismo tipo de pedido, la regla de decisión del cheat sheet es débil: reescríbela de forma más explícita.
El servidor cambió
Si renombras una herramienta o agregas un parámetro, el ejemplo anterior deja de funcionar: conviene revisar la cheat sheet después de actualizar cualquier servidor MCP.
💡 Consejo práctico
Siempre que corrijas al agente en la conversación ("no, usa crawl aquí, no scrape"), pídele que actualice por sí mismo la cheat sheet con ese aprendizaje.
✗ Dejar que se apague
- • Guía rápida escrita una vez, nunca más consultada
- • Las herramientas nuevas del servidor no aparecen ahí
- • El agente sigue tomando la misma decisión equivocada desde hace semanas
✓ Manteniéndolo vivo
- • Revisado con cada servidor nuevo o error repetido
- • El propio agente ya sugiere la actualización cuando se le corrige
- • La regla de decisión se vuelve más clara en cada ronda