Guía

Qué es CLAUDE.md y cómo escribir uno (con 5 ejemplos para diseño)

Qué es el archivo CLAUDE.md de Claude Code, dónde va, cómo se carga y 5 ejemplos cortos para landing, portafolio, app, design system y sitio de cliente.

19 de octubre de 2026 · 9 min de lectura

19 de octubre de 2026

9 min de lectura

Cada sesión de Claude Code empieza de cero. No recuerda que ayer le dijiste «nada de colores sueltos» ni que tu producto tutea. Lo que no está escrito, lo vas a repetir. Y lo que repites cansado a las once de la noche, lo repites mal.

El CLAUDE.md es el archivo donde escribes eso una vez. Aquí va qué es, dónde va, cómo se carga, cinco ejemplos para proyectos de diseño y cuándo conviene usar otra herramienta.

Qué es

Un archivo Markdown con instrucciones que Claude Code lee al empezar cada sesión: comandos, convenciones, estructura y reglas del tipo «siempre haz X». Para quien diseña es el brief permanente del proyecto: el sistema de diseño, la voz y lo que siempre hay que preguntarte.

Un dato que cambia cómo lo escribes: Claude lo trata como contexto, no como una regla forzada. Lo sigue bien si las instrucciones son concretas, pero no es una garantía. Para impedir algo sí o sí existen los hooks.

Dónde va

Archivo	Para qué	¿Se comparte?
`./CLAUDE.md` o `./.claude/CLAUDE.md`	Reglas del proyecto	Sí, va en el repositorio
`./CLAUDE.local.md`	Tus preferencias en este proyecto	No: agrégalo al `.gitignore`
`~/.claude/CLAUDE.md`	Tus preferencias en todos tus proyectos	No
Archivo administrado por la organización	Políticas de la empresa	Lo instala el área de TI

Si tu repositorio ya tiene un AGENTS.md para otras herramientas y no tiene CLAUDE.md, Claude Code puede leer ese archivo directamente desde la v2.1.277.

Cómo se carga

Al arrancar, Claude carga los CLAUDE.md de la carpeta donde abres la sesión y de las carpetas superiores.
Los de subcarpetas se cargan cuando Claude lee, escribe o edita un archivo en esa subcarpeta.
No se pisan: se suman. Las instrucciones más cercanas a donde abriste la sesión se leen al final, y en cada carpeta CLAUDE.local.md va después de CLAUDE.md.
Los comentarios HTML de bloque () se quitan antes de pasarle el contenido a Claude: sirven para dejar notas a otras personas sin gastar contexto.

Tres comandos para trabajar con él:

/init genera un CLAUDE.md inicial leyendo tu proyecto (si ya existe, sugiere mejoras). Tus reglas de diseño las pones tú.
/context muestra qué cargó la sesión, en la lista «Memory files».
/memory abre los archivos de memoria para editarlos.

Cuánto debe medir

La documentación oficial recomienda menos de 200 líneas por archivo: uno más largo consume más contexto y Claude lo sigue peor. Cuando crece:

Saca lo que aplica a una parte del proyecto a .claude/rules/. Una regla con paths: en el encabezado solo se carga cuando Claude trabaja con esos archivos:
```
---
paths:
  - "src/content/casos/**/*.md"
---
# Casos de estudio
- Nunca inventes métricas ni clientes. Si falta un dato, deja «TODO:» visible.
```
Los imports no adelgazan. Puedes importar archivos con @ruta/archivo.md (hasta cuatro saltos), pero lo importado también se carga al inicio. Sirve para ordenar, no para ahorrar.

Cuándo agregar una regla

La documentación propone cuatro señales. Agrega algo cuando:

Claude se equivoca en lo mismo por segunda vez.
Una revisión encuentra algo que Claude debió saber del proyecto.
Escribes en el chat la misma corrección que escribiste la sesión anterior.
Una persona nueva en el equipo necesitaría ese mismo contexto.

La estructura que uso

Mis CLAUDE.md de diseño tienen estas secciones, en este orden: qué es y para quién, comandos, estructura, reglas de diseño, accesibilidad, voz, «terminado significa» y «pregúntame antes de». La última es la que casi nadie escribe y la más importante: Claude decide bien, y tu trabajo es dejar claro qué decisiones no le corresponden.

5 ejemplos cortos

Ejemplos de 10 a 15 líneas para ver qué cambia según el proyecto. Los nombres son inventados.

Landing

# CLAUDE.md · Landing de Pausa, app de meditación
Objetivo: que descarguen la app. Público: adultos que nunca meditaron.

## Comandos
- `npm run dev` · `npm run build` · `npm test`
- Nunca corras el deploy: lo hago yo.

## Reglas
- Una sola acción principal: «Descargar la app». Ningún otro botón primario.
- Solo tokens de `src/styles/tokens.css`. Nada de hex ni `text-[#...]`.
- Nada de testimonios, logos ni cifras inventadas.
- Revisa a 375 y 1440 px antes de decir que terminaste.

## Pregúntame antes de
Cambiar el orden de las secciones o cualquier texto de venta.

Portafolio

# CLAUDE.md · Portafolio de Ana Pérez, diseñadora UX
Casos en `src/content/casos/*.md`. Imágenes en `src/assets/casos/`.

## Casos de estudio
- Estructura: contexto, problema, mi rol, proceso, solución, resultado.
- Nunca inventes métricas, clientes ni fechas. Si falta un dato, deja `TODO:`.
- Clientes con acuerdo de confidencialidad: «una fintech de Latinoamérica».
- Texto real en HTML, nunca texto dentro de imágenes.

## Imágenes
- Formato moderno, al tamaño de uso, con `width`, `height` y un `alt` que describa la pantalla.

## Terminado significa
`npm run build` sin errores, axe sin violaciones y revisado a 375 y 1440 px.

App

# CLAUDE.md · Turnos, app web para reservar horas en una peluquería
Astro + Tailwind v4. Los datos vienen de una API (`src/lib/api.ts`).

## Pantallas
- Cada pantalla tiene 4 estados: cargando, vacío, error y con datos. Ninguno se omite.
- Los errores dicen qué pasó y cómo seguir: «No pudimos guardar tu hora.
  Revisa tu conexión e inténtalo otra vez».

## Formularios
- Label visible, `autocomplete` y el error junto al campo con `aria-describedby`.

## Datos y claves
- Las claves viven en `.env`. Nunca las escribas en el código ni en la conversación.

## Pregúntame antes de
Instalar dependencias, crear servicios o tocar datos de clientes.

Design system

# CLAUDE.md · Design system Brisa
Tokens en `src/tokens/` (primitivos → semánticos → componente). Catálogo en `/componentes`.

## Tokens
- Componentes y pantallas usan tokens semánticos (`--color-texto`), nunca primitivos.
- Un token nuevo necesita mi aprobación. Nunca borres uno: márcalo como obsoleto.

## Componentes
- Props explícitas (`variant`, `size`). Nada de estilos sueltos por fuera.
- Cada componente entra al catálogo con todas sus variantes y estados:
  hover, foco visible y deshabilitado.
- Contraste mínimo 4,5:1 en texto y 3:1 en bordes de controles y foco.

## Versiones
- Todo cambio visible va al `CHANGELOG.md`. Un cambio de API sube la versión mayor.

Sitio de cliente

# CLAUDE.md · Sitio de Ferretería Los Robles (cliente)
La marca del cliente manda: el manual está en `docs/marca.pdf`.

## Contenido
- Usa solo textos de `docs/textos-aprobados.md`. Si falta uno, deja `[TEXTO PENDIENTE]`.
- Precios, horarios y direcciones salen solo de ese archivo.

## Publicación
- Se publica en la cuenta de Cloudflare del cliente, nunca en la mía.
- Nunca corras `npm run deploy`. Para ensayar: `npm run deploy:prueba`.

## Pregúntame antes de
Cambiar colores, tipografías, el logo o cualquier texto aprobado.

Fíjate en lo que tienen en común: cada línea se puede comprobar. «Solo tokens de tokens.css» se verifica con una búsqueda; «respeta el diseño», no.

Instrucciones buenas y malas

No funciona	Funciona	Por qué
Respeta el design system	Usa solo tokens de `src/styles/tokens.css`; nada de hex	Se comprueba con una búsqueda
Haz que sea accesible	WCAG 2.2 AA: contraste 4,5:1, foco visible, todo con teclado	Tiene números
Escribe bien	Tuteo; botones con verbo; errores con qué pasó y cómo seguir	Son patrones, no gustos
Prueba tus cambios	Corre `npm test` y revisa a 375 y 1440 px antes de terminar	Es un paso, no un deseo
Ten cuidado con producción	Nunca corras `npm run deploy` salvo que te lo pida	Nombra el comando exacto
Sé creativo con el copy	Pregúntame antes de cambiar textos de venta	Dice quién decide

Ojo con las contradicciones: si dos instrucciones chocan, Claude puede elegir una al azar. Desde la v2.1.283, /doctor prompt-audit revisa tus archivos de instrucciones y propone cambios, sin tocar nada hasta que lo apruebes.

Cuándo usar otra cosa en vez de CLAUDE.md

El CLAUDE.md es para lo que debe estar presente en cada sesión. Para el resto, Claude Code tiene otras piezas:

Si quieres…	Usa	Ejemplo
Que siga un procedimiento de varios pasos cuando haga falta	Un skill (`.claude/skills/<nombre>/SKILL.md`)	Un QA visual con capturas en tres anchos
Una segunda opinión sin contaminar la conversación	Un subagente (`.claude/agents/`)	Un crítico de diseño que revisa capturas sin haber escrito el código
Que algo se cumpla sí o sí	Un hook	Formatear cada archivo editado; bloquear un deploy sin confirmación
Reglas que solo aplican a ciertos archivos	`.claude/rules/` con `paths:`	Reglas de los casos de estudio
Que Claude vea una herramienta externa	Un MCP	El servidor oficial de Figma

Un hook es un comando que Claude Code ejecuta siempre en un momento del ciclo. Este ejemplo de la documentación oficial formatea con Prettier cada archivo que Claude edita (va en .claude/settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Un hook que corre antes de una acción (PreToolUse) puede impedirla: si su comando termina con código de salida 2, la acción se bloquea y Claude recibe el motivo. Así se construye, por ejemplo, una confirmación obligatoria antes de publicar.

Errores comunes

Un archivo de 400 líneas. Claude lo sigue peor. Recorta, mueve a reglas por carpeta o a skills.
Procedimientos completos en el CLAUDE.md. Ocupan contexto en cada mensaje aunque no se usen. Van en un skill.
Secretos en el archivo. El CLAUDE.md del proyecto va al repositorio. Nunca pongas claves ni contraseñas ahí.
Escribirlo una vez y olvidarlo. Una regla vieja que contradice una nueva hace más daño que ninguna.

Fuentes oficiales

Cómo recuerda Claude tu proyecto (CLAUDE.md, reglas, imports): https://code.claude.com/docs/en/memory
Skills: https://code.claude.com/docs/en/skills
Subagentes: https://code.claude.com/docs/en/sub-agents
Hooks: https://code.claude.com/docs/en/hooks-guide

Plantillas listas

Mi kit «Del Figma a producción con Claude Code» trae cinco plantillas completas de CLAUDE.md (landing, portafolio, app, design system y sitio de cliente) y un skill, crear-claude-md, que mira tu proyecto, te hace como máximo seis preguntas y arma el archivo con TODO: donde falte un dato en vez de inventarlo. Es de pago; aquí está todo lo que incluye.

Si quieres probar antes, hay 3 skills del kit gratis en un repositorio público de GitHub. El kit no está afiliado a Anthropic.