Imagina empezar cada conversación con la IA desde cero, volviendo a explicar qué estás construyendo, qué herramientas usas y cómo te gusta recibir las respuestas. Es agotador y costoso en tokens. O CLAUDE.md resuelve esto: es un archivo que se lee automáticamente al inicio de cada sesión, convirtiéndose en el contexto base del agente: tu memoria del proyecto, que no se borra cuando termina la conversación.
Diagrama ilustrativo — el CLAUDE.md se «inyecta» en el contexto del agente cada vez que abres una sesión, así que ya empieza sabiendo quién es, qué está construyendo y cómo actuar.
📌 CLAUDE.md como system prompt persistente
Qué es
O CLAUDE.md es un archivo en Markdown que está en la raíz de tu proyecto y define el papel, o contexto y las preferencias bajo las cuales operará el agente. Cuando abres una sesión de trabajo en esa carpeta, el agente lee ese archivo antes que nada: se convierte en el «system prompt» del proyecto, es decir, la instrucción base que moldea todo el comportamiento de la IA a partir de ahí.
¿Qué es?System prompt — la instrucción de fondo que le dice a la IA quién es y cómo actuar, siempre activa detrás de la conversación. Markdown — una forma simple de escribir texto con títulos (#), listas y énfasis, sin necesidad de programar. Sesión — una «sesión» de trabajo con el agente, desde que la abres hasta que la cierras.
La palabra clave es persistente. Una conversación común se borra: cierra la ventana y el agente lo olvida todo. El CLAUDE.md no: vive en el disco, se versiona junto con el proyecto y se lee de nuevo en cada sesión. Por eso, la mejor analogía es una constitución: un documento breve y estable que establece cómo funciona el proyecto, que el agente siempre obedece, sin importar quién (o cuándo) está conversando con él.
Por qué aprender
Sin CLAUDE.md, cada día empieza desde cero: vuelves a pegar el contexto, repites tus reglas, recuerdas tus preferencias. Con él, el conocimiento del proyecto queda guardado una vez y se reutiliza infinitas veces. Es la diferencia entre capacitar a un empleado nuevo cada mañana y tener a un veterano que ya llega sabiendo.
- •Sin volver a explicar: el contexto se carga solo en cada sesión.
- •Consistencia: todas las sesiones siguen las mismas reglas.
- •La base de todo: los otros temas de este módulo perfeccionan este archivo.
Conceptos clave
Archivo .md en la parte superior del proyecto.
No se borra al cerrar la conversación.
Cargado al inicio de cada sesión.
Rige el comportamiento del agente.
🧱 Anatomía del CLAUDE.md
Qué es
Un buen CLAUDE.md tiene cinco secciones típicas: Rol (quién es el agente; por ejemplo: «eres un asistente de workflows de n8n»), Contexto (lo que se está construyendo y por qué), Reglas operativas (cómo debe trabajar), Estilo (preferencias de comunicación) y Estructura de carpetas (dónde están las cosas). Cada sección responde a una pregunta distinta que se haría la IA si acabara de llegar al proyecto.
Diagrama ilustrativo — las cinco secciones no son compartimentos aislados; juntas forman el «molde» completo a partir del cual actúa el agente.
Por qué aprender
No necesitas escribir esas secciones a mano. El camino del vibe coding es pedir en lenguaje natural: "crea un CLAUDE.md para un proyecto que crea automatizaciones en n8n, con reglas para buscar una herramienta antes de crearla y mantener el archivo conciso". La IA genera el esqueleto con las secciones correctas; tú solo revisas y ajustas. Conocer la anatomía te sirve para saber qué pedir e qué revisar en el resultado.
✓ Secciones que toda anatomía tiene
- ✓Rol: "eres un asistente de workflows de n8n".
- ✓Contexto: qué es el proyecto y cuál es el objetivo principal.
- ✓Reglas + estilo + estructura: cómo actuar, cómo hablar, dónde están las cosas.
✗ Qué ensucia la anatomía
- ✗Tutoriales paso a paso para tareas específicas.
- ✗Documentación extensa de una sola herramienta.
- ✗Historial de conversaciones y decisiones anteriores.
Conceptos clave
Quién es el agente.
Lo que se está construyendo.
Cómo actuar y cómo hablar.
En lenguaje natural, no a mano.
⚙️ Reglas operativas
Qué es
Reglas operativas son instrucciones breves sobre cómo el agente debe trabajar: no qué construir, sino la disciplina del día a día. Tres reglas valen oro en casi cualquier proyecto: buscar una herramienta existente antes de crear una nueva, aprender y adaptarse cuando algo falla, e mantener los workflows y archivos siempre actualizados. Son pocas líneas, pero cambian radicalmente el comportamiento.
¿Qué es?Ciclo de autom mejora — cuando el agente, al equivocarse, ajusta su propia forma de trabajar (e incluso el propio CLAUDE.md) en vez de solo remendar el resultado. Herramienta (tool) — una capacidad que puede usar el agente (leer un archivo, llamar a una API, ejecutar una skill).
Estas reglas son exactamente lo que activa el ciclo de autom mejora. "Busca antes de crear" evita reinventar la rueda y mantiene limpio el proyecto. "Aprende al fallar" hace que el agente trate un error como información, no como un callejón sin salida. "Mantén todo actualizado" garantiza que la documentación y los flujos no queden desactualizados respecto de lo que realmente existe. Juntas, transforman al agente de ejecutor pasivo en colaborador que mejora por su cuenta.
✓ Reglas que activan el ciclo
- ✓"Busca una herramienta existente antes de crear una nueva."
- ✓"Cuando algo falle, aprende y adapta el enfoque."
- ✓"Mantén los workflows y archivos siempre actualizados."
✗ Antipatrones en las reglas
- ✗Crear una tool nueva cada vez, ignorando lo que ya existe.
- ✗Insistir en el mismo enfoque que ya falló.
- ✗Dejar la documentación desactualizada con respecto a la realidad.
🎯 Consejo práctico
Escribe reglas como principios breves y prácticos, no como párrafos. "Busca antes de crear" es mejor que tres frases que explican por qué. La IA sigue las reglas concisas con más fidelidad y, además, es fácil encontrarlas en el archivo.
Conceptos clave
Reutilizar > recrear.
El error se convierte en un ajuste.
La documentación = la realidad.
Las reglas conectan el ciclo.
✂️ Mantenerlo compacto (< ~500 líneas)
Qué es
Cómo encaja CLAUDE.md en el contexto en cada sesión, compite por espacio con el resto de la conversación. La regla práctica: mantenlo conciso, por debajo de ~500 líneas. Un archivo corto hace que cada regla "pese" más; uno largo diluye las instrucciones importantes entre demasiado texto, y el agente termina "perdiendo" justo lo que importa.
¿Qué es?Contexto (ventana de contexto) — el "espacio de memoria de trabajo" del agente durante una sesión; todo lo que entra allí (incluido el CLAUDE.md) ocupa espacio. Token — el fragmento de texto que la IA cuenta; cuantas más líneas tenga el archivo, más tokens se gastan en cada sesión.
Diagrama ilustrativo — cuanto más ocupa el archivo, menos espacio queda para la conversación, y más fácil es que la IA «no vea» una regla importante perdida en medio del texto.
Por qué aprender
Hay un síntoma clásico: si el agente insiste en hacer algo mal aunque haya una regla clara que lo prohíbe, probablemente el archivo sea demasiado largo y la regla se está perdiendo. La solución no es gritar la regla en mayúsculas, sino quitar lo superfluo. Quita lo que no se aplica a todas las sesiones, condensa los párrafos en principios y la regla vuelve a tener peso. Ser conciso es una decisión de ingeniería, no pereza.
🎯 Consejo práctico
Regla práctica: si el CLAUDE.md no cabe en una o dos pantallas de desplazamiento, ya está demasiado grande. Antes de agregar cualquier cosa, pregúntate: "¿esto realmente es de cada ¿sesión?». Si es para una tarea específica, su lugar es una skill (siguiente tema).
Conceptos clave
Siempre ocupa contexto.
Límite práctico.
Las reglas se pierden.
Si falla pese a la regla = recorte.
🔀 CLAUDE.md vs. skills — qué va dónde
Qué es
La regla de enrutamiento más importante de este módulo: el CLAUDE.md guarda solo lo que corresponde a todas las sesiones (propósito del proyecto, framework, objetivo principal, reglas operativas). Instrucciones específicas de una tarea — como «generar una factura en PDF» o «hacer scraping de un sitio» — pertenecen a una skill, cargada bajo demanda, solo cuando surge la tarea.
¿Qué es?Skill — un conjunto de instrucciones especializadas para una tarea, guardado en un archivo separado y cargado solo cuando hace falta. Bajo demanda (on demand) — solo se incorpora al contexto cuando se usa, en vez de estar siempre cargado.
Diagrama ilustrativo — muchas skills (20 a 50) no inflan el contexto, porque se incorporan solo cuando la tarea lo requiere; un CLAUDE.md gigante inflaría cada sesión.
Por qué aprender
Meterlo todo en CLAUDE.md se desborda la ventana de contexto: cada sesión carga toneladas de instrucciones que quizá ni se usen ese día. Las skills resuelven esto mediante ahorro de carga. Puedes tener 20, 30 o 50 skills sin inflar el contexto, porque cada una solo aparece cuando surge la tarea correspondiente, a diferencia de un CLAUDE.md gigante, cuyo costo pagarías en todas las sesiones.
✓ Va en CLAUDE.md
- ✓Propósito del proyecto y objetivo principal.
- ✓Framework y reglas operativas (de toda sesión).
- ✓Estilo de comunicación y estructura de carpetas.
✗ No va ahí (va en una skill)
- ✗Paso a paso de una tarea puntual (p. ej., generar un PDF).
- ✗Instrucciones de una integración que se usa de vez en cuando.
- ✗Recetas largas que solo sirven para un tipo de solicitud.
Conceptos clave
Solo lo que siempre está presente.
Específico, bajo demanda.
20–50 skills caben.
Evita saturar el contexto.
💬 Iterar el archivo conversando
Qué es
El CLAUDE.md es un documento vivo. No necesitas abrir un editor para modificarlo: basta con pedirle al propio agente. "Agrega una sección sobre cómo mantener las explicaciones concisas", "elimina la regla X que ya no usamos", "registra que este proyecto usa Supabase". La IA edita el archivo y el cambio se aplica a partir de la próxima sesión. El archivo evoluciona junto con el proyecto.
¿Qué es?Documento vivo — un archivo que esperas cambiar con frecuencia, no algo escrito una vez y dejado fijo. Iterar — hacer pequeñas mejoras en ciclos, validando cada paso (la misma mentalidad de la Trilha 1).
Cómo evoluciona el archivo
-
1
Sesión inicial: pides un CLAUDE.md básico (rol, contexto, reglas). El agente genera el esqueleto.
-
2
Surge un patrón: notas que siempre pides respuestas breves. "Agrega una sección que indique que las explicaciones deben ser concisas."
-
3
El proyecto crece: entra una nueva herramienta. "Registra que usamos Supabase para los datos." El contexto se mantiene actualizado.
-
4
Hora de podar: el archivo superó las ~500 líneas. "Mueve las instrucciones de la tarea de facturas a una skill y reduce el CLAUDE.md."
Por qué aprender
Tratar el CLAUDE.md como algo que se puede editar en cualquier momento, en lenguaje natural, cierra el ciclo de auto-mejora del módulo: cada vez que el agente comete un error por falta de una regla, tú agregas la regla conversando; cada vez que el archivo crece, lo podas conversando. No es un documento sagrado; es una herramienta de trabajo que afinas continuamente.
🎯 Objetivo: generar un CLAUDE.md conciso para el proyecto
crie um CLAUDE.md na raiz para um projeto que <descreva o que você constrói>. Seções: Papel, Contexto, Regras operacionais, Estilo, Estrutura de pastas. Regras: procurar uma tool existente antes de criar; aprender ao falhar; manter sob ~500 linhas.
✅ Cómo verificar: abre el archivo generado; comprueba las 5 secciones y que quepa en ~1 pantalla de desplazamiento.
📜 Esqueleto: un CLAUDE.md mínimo y conciso
# Papel Você é um assistente de workflows n8n para este projeto. ## Contexto Construímos automações que conectam e-mail, planilhas e um banco Supabase. Objetivo principal: notificar a equipe sobre leads novos em tempo real. ## Regras - Procure uma tool/skill existente antes de criar uma nova. - Quando algo falhar, aprenda e adapte a abordagem. - Mantenha este arquivo sob ~500 linhas (tarefa específica vira skill). ## Estilo - Respostas curtas e diretas, em PT-BR. - Explique o "porquê" das decisões em 1 frase. ## Estrutura - /workflows → fluxos n8n exportados - /skills → instruções de tarefas específicas - /docs → notas e decisões do projeto
✅ Cómo verificar: cada sección tiene 1–3 líneas; aquí no hay instrucciones paso a paso para una tarea específica (eso va en /skills).
¿Dónde deben estar las instrucciones paso a paso para «generar una factura en PDF», una tarea que solo aparece de vez en cuando?
Conceptos clave
Evoluciona con el proyecto.
En lenguaje natural.
¿Te equivocaste? Registra la regla.
¿Se infló? Redúcelo.
📌 Resumen del módulo
Siguiente módulo:
2.2 — El Framework WAT a fondo