CLAUDE.md — el cerebro de tu proyecto

Dale contexto permanente a Claude con un solo archivo markdown

⏱ Estim. ~4 min

01 · Leer

Cada vez que abres una nueva sesión de Claude Code, Claude empieza en blanco. No recuerda tu conversación anterior, tu estilo de código, las convenciones de tu proyecto, ni siquiera qué framework usas. Tienes que volver a explicar todo cada vez.

CLAUDE.md resuelve esto. Es un archivo markdown que Claude lee al inicio de cada sesión — el manual de instrucciones permanente de tu proyecto.

💡 Imagínalo asíPiensa en CLAUDE.md como el documento de onboarding de un nuevo miembro del equipo. En lugar de explicar las convenciones del equipo cada mañana, lo escribes una sola vez. CLAUDE.md es ese documento — Claude lo lee cada vez que se pone a trabajar.

Puntos clave

Cada sesión de Claude Code empieza desde cero — no recuerda conversaciones pasadas
CLAUDE.md se carga automáticamente al inicio de cada sesión
Le dice a Claude las reglas, convenciones y contexto importante de tu proyecto
Es solo un archivo markdown — lo editas igual que cualquier otro

02 · Leer

CLAUDE.md puede vivir en tres lugares, con un alcance distinto en cada uno.

Nivel de proyecto — pon CLAUDE.md en la raíz del repo (o .claude/CLAUDE.md). Se comparte con el equipo vía git. Úsalo para convenciones del proyecto, comandos de build y patrones de arquitectura.

Nivel de usuario — ponlo en ~/.claude/CLAUDE.md. Personal, aplica a todos los proyectos. Úsalo para tus preferencias personales.

Subdirectorios — los archivos CLAUDE.md de subdirectorios se cargan bajo demanda cuando Claude lee archivos de ese directorio. Ideal para instrucciones específicas de un módulo.

Puntos clave

Nivel de proyecto (./CLAUDE.md): se comparte con el equipo, va al commit en git
Nivel de usuario (~/.claude/CLAUDE.md): personal, para todos tus proyectos
CLAUDE.md en subdirectorios: se carga bajo demanda para módulos específicos
Cuando hay conflicto, las reglas del proyecto pesan más que las del usuario

03 · Ejemplo de código

Un buen CLAUDE.md incluye comandos de build, estilo de código, arquitectura y convenciones propias del proyecto. Aquí va un ejemplo real.

Ejemplo de CLAUDE.md

# Build & Test
- `npm run dev` — start frontend dev server
- `npm run build` — TypeScript check + production build
- `npm test` — run tests (Vitest)

# Code Style
- TypeScript strict mode, ES modules (import/export)
- 2-space indentation, single quotes
- Functional React components, no class components

# Architecture
- API routes in `server/src/routes/`
- Database schema in `server/src/db/schema.ts`
- Frontend components in `src/components/`

# Important
- The `--color-purple` CSS variable is actually orange (#FF6B35)
- Auth cookies use sameSite: 'none' for cross-origin

Fíjate qué se incluye: cosas que Claude no descubriría con solo leer el código. Comandos de build, convenciones de nombres poco comunes, peculiaridades entre fuentes. No incluyas lo que Claude puede descubrir explorando — enfócate en lo que no es obvio.

04 · Ejemplo de código

Cuando tu CLAUDE.md crece, puedes dividirlo en archivos enfocados usando imports y un directorio de rules.

CLAUDE.md con @import

# Project Overview
See @README.md for project description
See @specs/ARCHITECTURE.md for system design

# Code Style
@docs/code-style.md

Estructura del directorio rules

.claude/
├── CLAUDE.md          (main instructions)
└── rules/
    ├── api-design.md  (API conventions)
    ├── testing.md     (test patterns)
    └── security.md    (security rules)

El prefijo @ importa el contenido de otro archivo dentro de CLAUDE.md. El directorio .claude/rules/ guarda reglas específicas por tema y Claude las carga automáticamente. Mantén el CLAUDE.md principal corto y dale a Claude acceso a conocimiento detallado por área.

05 · Quiz

Tienes convenciones de proyecto que todos los devs del equipo deben seguir. ¿Dónde va tu CLAUDE.md para que se comparta con el equipo?

Tu directorio personal (~/.claude/CLAUDE.md)
Raíz del repo (./CLAUDE.md), con commit en git
Un Google Doc enlazado desde el README
Un mensaje fijado en un canal de Slack

06 · Completar

Para importar otro archivo dentro de CLAUDE.md, antepón _____ a la ruta

Otras lecciones de este capítulo

⚠ La experiencia interactiva completa necesita JavaScript. Actívalo y vuelve a cargar la página.

※ Este es un proyecto educativo independiente — no es un producto oficial de Anthropic. Claude™ es una marca registrada de Anthropic, PBC.