¿Qué es CLAUDE.md?

Ahora que sabes lo que es una sesión de agente, la pregunta que sigue sale sola: ¿cómo sabe tu agente que debe portarse como un copiloto de visualización de datos y no como un asistente genérico?

La respuesta es su archivo de instrucciones: CLAUDE.md en Claude Code, AGENTS.md en Codex. Estos archivos cumplen una función parecida de orientación para el proyecto; esta página usa CLAUDE.md.

Las instrucciones del proyecto que carga el agente

Al empezar una sesión, el agente carga las instrucciones del proyecto que correspondan, junto con su otro contexto. En este curso, CLAUDE.md vive en la raíz de tu carpeta de proyecto. Está escrito en texto plano (Markdown, pero no necesitas saber qué es eso: se lee como un correo).

CLAUDE.md son las instrucciones permanentes de tu agente para este proyecto. Responde tres preguntas:

1. ¿Quién soy en este proyecto? ("Eres mi copiloto de visualización de datos en este proyecto.")
2. ¿Qué hago cuando me piden ayuda? ("Antes de hacer un gráfico, pregúntame qué historia debe contar. Haz los gráficos con código. Guarda cada gráfico en outputs/.")
3. ¿Cómo me debo comportar? ("Sé curioso y pregunta antes de suponer. Trata cada revisión como un avance, no como un error.")

Abre el CLAUDE.md que guardaste cuando preparaste tu carpeta de proyecto en la página de bienvenida. Léelo completo. Vas a reconocer cada una de esas tres secciones.

El volante

Si una sesión de agente es el coche, CLAUDE.md es el volante. Todavía puedes dar indicaciones en la conversación, pero el coche arranca apuntando hacia donde lo dejó CLAUDE.md.

Un experimento mental para aterrizarlo:

¿Qué pasaría si abrieras CLAUDE.md y agregaras una línea al final: "Eres un asistente de poesía. Nunca escribas código. Responde solo en haikus."?

Esa instrucción podría orientar una sesión nueva hacia los haikus, incluso si pides un gráfico. También podría entrar en conflicto con otras instrucciones o cumplirse de forma inconsistente.

CLAUDE.md orienta el comportamiento; no es un mecanismo que lo imponga. Escribe instrucciones claras y coherentes, y luego verifica los resultados importantes. Una instrucción bien puesta hace más fácil repetir el comportamiento esperado, pero no lo garantiza.

Qué va en CLAUDE.md

CLAUDE.md es para instrucciones siempre activas: lo que quieres que tu agente haga (o no haga) en cada interacción en este proyecto:

• El nombre que le das a este agente ("Eres un copiloto de visualización de datos")
• Qué herramientas y librerías usar ("genera gráficos con sintaxis de Vega-Lite")
• Cómo manejar la ambigüedad ("pregunta siempre qué historia debe contar el gráfico antes de generarlo")
• Dónde guardar archivos ("guarda los resultados en la carpeta outputs/")
• Pautas generales de comportamiento ("responde con calidez y de forma práctica, sin rollos")

Fíjate en lo que no va en CLAUDE.md: tu paleta de colores, tu estilo personal de gráficos o tu forma preferida de criticarlos. Esos tienen sus propios archivos. Tu paleta y tu estilo van en DATAVIZ.md, que vas a empezar en el Módulo 2. Cómo hacer un gráfico y cómo criticarlo van en skills, que vas a construir en los Módulos 3 y 4, y que tu agente carga solo cuando la tarea las pide. Por ahora, quédate con esto: CLAUDE.md es para lo general y siempre activo; las skills son para lo específico y se activan cuando hacen falta.

La prueba es cambiarlo

La mejor forma de entender CLAUDE.md es cambiarlo y ver qué pasa.

Pruébalo

1. Abre CLAUDE.md en cualquier editor de texto (es solo un archivo de texto).
2. Agrega una línea hasta abajo: Siempre explica en exactamente una oración por qué elegiste ese tipo de gráfico, antes de generarlo.
3. Guarda el archivo.
4. Abre una conversación nueva en la misma carpeta de proyecto. Tu agente lee CLAUDE.md cuando empieza una conversación, así que la conversación que ya tenías abierta tal vez no vea la línea nueva.
5. Pide: "Haz un gráfico de barras rápido de cinco países y su PIB."
6. Revisa la respuesta real: ¿explicó por qué eligió ese tipo de gráfico antes de generarlo, en exactamente una oración? Si no, confirma que cargó el archivo, busca instrucciones que entren en conflicto y vuelve a probar.
7. Guarda el prompt y el resultado que observaste, haya coincidido o no. Luego quita la línea temporal y vuelve a guardar el archivo.

Acabas de probar el ciclo de CLAUDE.md: escribir una instrucción, confirmar que se cargó, revisar la respuesta y ajustar lo que no coincida. Ese mismo ciclo, aplicado a tus preferencias personales de visualización, es de lo que trata todo el Módulo 3.