CLAUDE.md: el prompt de sistema de tu proyecto

Módulo: 2. Inicio rápido | Tiempo: ~30 min de teoría + 25 min de práctica

Lo esencial

Imagina que contratas a una persona nueva. Lo primero que haces es explicarle qué es la empresa, cómo funciona todo y cuáles son las reglas de trabajo. CLAUDE.md es justo esa inducción, pero para el agente (un agente es un programa que ejecuta tareas de forma autónoma). La escribes una vez y el agente la lee al inicio de cada sesión.

Conceptos clave

• CLAUDE.md = prompt de sistema (un prompt es la instrucción en texto que le das a la IA) que el agente lee al inicio de cada sesión y mantiene en su contexto
• Tres capas: WHAT (qué hay), WHY (para qué), HOW (cómo trabajar)
• Principio de brevedad: cada palabra cuesta tokens (los tokens son las unidades mínimas de texto para la IA)
• Carga progresiva: punteros en lugar de duplicar información
• /init: genera automáticamente un CLAUDE.md para código que ya existe

Teoría

Qué es CLAUDE.md y para qué sirve

🎨 Imagínalo así: Claude sin CLAUDE.md es como un cirujano nuevo en el quirófano sin el expediente del paciente. Es un profesional, pero tiene que preguntar todo desde cero: "¿Qué alergias tiene? ¿Qué operaciones previas? ¿Qué contraindicaciones?". CLAUDE.md es el expediente que el cirujano revisó de antemano.

Cuando abres una conversación nueva con Claude Code, el agente empieza desde cero. No recuerda lo que construiste la vez pasada. No sabe cómo está organizado tu proyecto. No conoce tus preferencias.

Eso crea un problema: cada vez tienes que volver a explicar el contexto (el contexto es el contenido de la conversación que la IA puede ver). "Este proyecto está en TypeScript (JavaScript con tipos), usamos Supabase como base de datos, tenemos tres servicios..." Son 5 a 10 minutos en cada sesión.

CLAUDE.md resuelve ese problema.

Es un archivo CLAUDE.md en la raíz de la carpeta de tu proyecto (el nombre va en mayúsculas: en Linux importa la diferencia entre mayúsculas y minúsculas). El agente lo lee automáticamente al inicio de cada conversación. Es como una instrucción personal: "Hola, soy este proyecto. Esto es lo que necesitas saber para trabajar conmigo".

En términos técnicos: CLAUDE.md es un archivo Markdown (un lenguaje sencillo para dar formato a texto). El agente lo usa como un contexto que está "siempre encendido" para ese proyecto.

Las tres capas de CLAUDE.md

Un CLAUDE.md bien escrito tiene tres capas. Piensa en ellas como respuestas a tres preguntas.

Capa 1: WHAT, qué hay aquí

La descripción técnica del proyecto. El agente debe entender de qué partes está hecho el sistema.

Qué incluir:

• Stack técnico: lenguaje (Python, JS o TS), frameworks, base de datos
• Estructura de carpetas: qué hay en cada carpeta y para qué
• Paquetes y librerías: qué dependencias externas ya están conectadas
• Entorno de ejecución: local, Docker, Cloudflare Workers, Vercel

Ejemplo:

## Stack técnico
- Python 3.11
- Usamos requests para las solicitudes HTTP
- Supabase como base de datos (SDK: supabase-py)
- Despliegue: Render.com (cron job)

## Estructura del proyecto
/workflows/       — archivos markdown con la descripción de cada workflow
/tools/           — scripts de Python, uno por herramienta
/config/          — configuración (archivos JSON)
/logs/            — registros automáticos de cada ejecución
main.py           — punto de entrada

Capa 2: WHY, para qué sirve cada componente

🎨 Imagínalo así: una fábrica sin instrucciones que expliquen "por qué se hace así". Una persona nueva ve una máquina y se pone a trabajar "con lógica", y rompe una pieza carísima porque no sabía que esa máquina tiene un orden de arranque especial. La capa WHY es la instrucción de "por qué así y no de otra forma", y te protege de los errores bienintencionados.

Es la capa que más se omite. Y la más importante para entender el proyecto.

El agente ve que existe la carpeta /tools/. Pero no sabe por qué las herramientas están en una carpeta aparte y no en un solo archivo. Sin entender eso, puede romper la arquitectura; por ejemplo, agregar una función nueva directamente en main.py en lugar de crear una herramienta nueva.

Ejemplo:

## Decisiones de arquitectura

**Por qué las herramientas están en una carpeta aparte:**
Cada herramienta es una función independiente. Los workflows llaman a las herramientas por su nombre.
Así una misma herramienta se puede reutilizar en distintos workflows.

**Por qué Supabase y no CSV:**
Necesitamos que los datos persistan entre ejecuciones. Cada ejecución agrega registros a la base, no la sobrescribe.

Capa 3: HOW, cómo debe trabajar el agente

Las reglas de trabajo. Cómo debe tomar decisiones el agente, qué restricciones existen y qué hacer en situaciones típicas.

Ejemplo:

## Reglas de trabajo

- Al agregar una herramienta nueva, crea un archivo aparte en /tools/; no la agregues a main.py
- Todas las claves de API van en el archivo .env; nunca las escribas directamente en el código
- Antes de crear un archivo nuevo, revisa si ya existe uno parecido
- Estilo de código: Python snake_case, comentarios en español
- Si la tarea requiere un paquete nuevo, pregunta antes de agregarlo

Principio de brevedad: los tokens son dinero

🎨 Imagínalo así: CLAUDE.md es como el discurso de apertura de una junta. Si la directora habla 5 minutos, todos escuchan. Si habla una hora, la gente bosteza y deja de prestar atención. El agente "bosteza" de otra forma: simplemente gasta tokens y dinero de más. La brevedad no es una virtud, es economía.

El contenido de CLAUDE.md permanece en el contexto durante toda la sesión y se toma en cuenta en cada solicitud. Si tu CLAUDE.md tiene 2000 palabras, esas 2000 palabras se suman a cada mensaje que envías.

El precio de los tokens depende del modelo (precios vigentes: Lo vigente). Pero con decenas de solicitudes al día, un CLAUDE.md inflado aumenta los gastos de forma notable y llena más rápido la ventana de contexto.

Regla: si algo se puede no escribir, no lo escribas. Si algo está escrito con mucho detalle, pregúntate: "¿de verdad el agente necesita este detalle ahora mismo?"

Qué sí escribir en CLAUDE.md:

• Las decisiones clave de arquitectura
• Convenciones poco comunes que el agente no adivinaría
• La estructura del proyecto (en un párrafo, no como un árbol detallado)
• Las reglas que siempre hay que respetar

Qué NO escribir en CLAUDE.md:

• Cosas obvias ("usar la sintaxis de Python")
• Instrucciones largas que se necesitan una vez al mes
• La documentación completa de una API (Application Programming Interface, la interfaz para que los programas se comuniquen) (mejor un enlace a un archivo)
• La historia del proyecto y la justificación de cada decisión

Carga progresiva: punteros en lugar de duplicar

🎨 Imagínalo así: no pones toda la biblioteca sobre la mesa antes de una reunión; dices "el libro que necesitas está en el estante B, el tercero desde la izquierda". El agente lo tomará cuando lo necesite. La carga progresiva es el catálogo de la biblioteca, no la biblioteca entera sobre la mesa.

Este es un patrón muy útil que ahorra tokens sin perder calidad:

Mal (duplicado dentro de CLAUDE.md):

## API de Perplexity
Endpoint: https://api.perplexity.ai/chat/completions
Método: POST
Headers: Authorization: Bearer {API_KEY}, Content-Type: application/json
Body: {"model": "sonar", "messages": [...]}
Ejemplo de respuesta: {"choices": [{"message": {"content": "..."}}]}
...otras 200 líneas de documentación...

Bien (un puntero):

## APIs externas
Documentación de todas las APIs: ver /docs/api-reference.md
Si necesitas ejemplos de solicitudes, también están ahí.

El agente leerá /docs/api-reference.md solo cuando de verdad lo necesite, es decir, cuando trabaje con esa API. No en cada solicitud.

A esto se le llama carga progresiva: cargas solo lo que hace falta en este momento.

/init: generar CLAUDE.md automáticamente

Si ya tienes código (por ejemplo, tomaste una plantilla lista o heredaste el proyecto de alguien más), Claude Code puede generar CLAUDE.md por sí mismo analizando el código.

Comando:

/init

El agente:

1. Revisa toda la estructura de la carpeta
2. Lee los archivos clave (package.json, requirements.txt, los scripts principales)
3. Arma un borrador de CLAUDE.md con las tres capas
4. Tú lo editas y lo afinas

Esto no sustituye escribir CLAUDE.md desde cero en un proyecto nuevo, porque ahí todavía no hay nada que analizar. Pero en proyectos existentes te ahorra 20 a 30 minutos.

Qué más lee Claude Code (a octubre de 2026)

CLAUDE.md no es la única forma de darle al agente un contexto permanente:

• AGENTS.md: Claude Code también lo lee si tu proyecto ya tiene ese archivo (lo usan otras herramientas de agentes).
• .claude/rules/: reglas ligadas a tipos de archivo; por ejemplo, reglas aparte para las pruebas o para la carpeta del frontend. Así el CLAUDE.md principal se mantiene corto.
• Auto memory (memoria automática): Claude anota por su cuenta lo que aprende de tus correcciones entre sesiones. Se administra con el comando /memory.

Plantilla mínima de CLAUDE.md (acordeón)

Copia esta plantilla como punto de partida para cualquier proyecto nuevo:

# [Nombre del proyecto] — CLAUDE.md

## Qué es (WHAT)
[1-2 oraciones: qué hace el proyecto y para quién]

## Stack
- Lenguaje: [Python / JavaScript / TypeScript]
- Frameworks: [si hay]
- Base de datos: [si hay]
- APIs: [qué servicios externos]
- Despliegue: [dónde se publica]

## Estructura del proyecto
/workflows/   — workflows (instrucciones en markdown)
/tools/       — herramientas (un archivo por función)
/config/      — configuración (JSON, formato de datos clave-valor / YAML, formato de archivos de configuración)
/docs/        — documentación de APIs y referencia
/logs/        — registros automáticos
.env          — claves de API (NUNCA hagas commit en git, el sistema de control de versiones)

## Por qué así (WHY)
- [Decisión de arquitectura 1: por qué así y no de otra forma]
- [Decisión de arquitectura 2]

## Reglas de trabajo (HOW)
- Herramienta nueva = archivo nuevo en /tools/, sin modificar los existentes
- Claves de API solo en .env, nunca escritas en el código
- Antes de desplegar, prueba con datos de prueba
- Estilo de código: [snake_case / camelCase], comentarios en [español/inglés]
- Si la tarea requiere un paquete nuevo, pregunta antes de agregarlo

Ejemplo de un CLAUDE.md real para un workflow de newsletter

# Newsletter Automation — CLAUDE.md

## Qué es
Newsletter semanal automático con noticias de bienes raíces para los clientes de una agencia.
Se ejecuta según un horario, reúne noticias, genera el HTML y lo envía con la Gmail API.

## Stack
- Python 3.11
- Perplexity API — búsqueda de noticias
- Anthropic API — generación de texto
- Gmail API — envío
- Google Sheets API — lista de destinatarios
- Ejecución: cron (programador de tareas automáticas) a través de trigger.dev

## Estructura
/workflows/weekly_newsletter.md  — workflow principal (léelo antes de cambiar cualquier cosa)
/tools/                          — un archivo por herramienta
/config/newsletter_style.json    — estilo y parámetros del newsletter
/config/recipients.json          — lista de destinatarios (actualiza solo este archivo)
.env                             — claves de API (nunca hagas commit)

## Reglas
- Si cambias la lógica, primero actualiza weekly_newsletter.md y después el código
- Herramienta nueva = archivo nuevo en /tools/, sin modificar los existentes
- Pruebas: siempre envía primero a test@agency.example antes del envío principal
- Los registros de cada ejecución se escriben automáticamente en /logs/ (no cambies ese formato)

Corto, concreto y cubre todo lo que el agente necesita saber.

Práctica

Tarea: crear un CLAUDE.md con las tres capas para un proyecto de práctica.

Paso 1. Elige tu proyecto (5 min):

Elige una de las automatizaciones que quieras construir (o usa el ejemplo de práctica: "enviar un resumen semanal a los clientes").

Paso 2. Escribe la capa WHAT (8 min):

Crea el archivo CLAUDE.md en la carpeta del proyecto. Escribe el stack técnico y la estructura de carpetas que planeas.

Paso 3. Escribe la capa WHY (7 min):

Agrega una sección "Decisiones de arquitectura" que explique por qué el stack y la estructura son así.

Paso 4. Escribe la capa HOW (5 min):

Agrega una sección "Reglas de trabajo" con 3 a 5 reglas.

Paso 5. Verificación (5 min):

Pregúntale a Claude Code: "Lee CLAUDE.md y explícame qué entendiste del proyecto y cómo hay que trabajar con él". Si el agente no entendió algo importante, aclara tu CLAUDE.md.

Errores comunes

❌ Error: escribir un CLAUDE.md de 3000 palabras con la documentación completa de todas las APIs.

✅ Lo correcto: CLAUDE.md se toma en cuenta en CADA solicitud = cada palabra cuesta tokens. Mantenlo corto (200 a 500 palabras). Saca la documentación detallada a archivos aparte y deja enlaces: "ver /docs/api-reference.md".

❌ Error: no escribir la capa WHY, solo WHAT y HOW.

✅ Lo correcto: sin WHY, el agente no entiende las decisiones de arquitectura y puede romper la estructura. ¿Por qué las herramientas van en archivos aparte? ¿Por qué Supabase y no CSV? Explícalo en pocas palabras.

❌ Error: olvidar actualizar CLAUDE.md cuando el proyecto cambia.

✅ Lo correcto: cuando agregues una herramienta, cambies el stack o las reglas, actualiza CLAUDE.md. Un prompt de sistema desactualizado es peor que no tener ninguno: el agente seguirá instrucciones equivocadas.

Herramientas y recursos

• Claude Code: la herramienta principal
• Markdown: el formato en el que se escribe CLAUDE.md (títulos con #, listas con -)
• Claude Code: memoria y CLAUDE.md: documentación oficial sobre CLAUDE.md, reglas y auto memory
• Anthropic Prompt Engineering: principios generales para escribir prompts
• Comando /init: genera CLAUDE.md automáticamente a partir del código existente

→ Ver la lección Four C's Framework: CLAUDE.md como portador de las cuatro C

→ Ver la lección Fundamentos de prompting: principios para escribir buenos prompts

→ Ver la lección Framework WAT: la estructura de carpetas del proyecto

→ Ver la lección Qué son los Skills: cómo agregar Capabilities a CLAUDE.md

Conclusiones clave

CLAUDE.md = el prompt de sistema del proyecto. El agente lo lee al inicio de cada sesión. Lo configuras una vez y funciona siempre.

Tres capas: WHAT (qué hay), WHY (para qué), HOW (cómo trabajar). Sin WHY, el agente romperá la arquitectura sin mala intención.

La brevedad importa: cada palabra de más son tokens de más en cada solicitud. Usa punteros en lugar de duplicar.

Siguiente lección

→ Framework WAT: Workflow (flujo de trabajo, cadena de tareas), Agente, Herramientas