Introducción

Cada vez que abres una nueva sesión de Claude Code, el agente parte de cero — no tiene memoria de las conversaciones de ayer, no sabe qué framework usa tu proyecto, qué convenciones de nomenclatura sigues ni qué directorios contienen el código crítico. Esta es una limitación inherente de los modelos de lenguaje, no un bug.

El archivo CLAUDE.md es el mecanismo oficial para解决这个问题. Cuando Claude Code se inicia en un directorio, lee automáticamente el archivo CLAUDE.md en la raíz y utiliza ese contenido como contexto de fondo para toda la sesión. Así es como "enseñas" al agente una vez y te beneficias indefinidamente.

Qué es CLAUDE.md y cómo funciona

CLAUDE.md es un archivo markdown estándar ubicado en la raíz de tu proyecto (al mismo nivel que package.json, pyproject.toml, o cualquier archivo de configuración que utilices). No hay una sintaxis especial ni un esquema obligatorio — escribes en markdown libre.

Cuando Claude Code ejecuta su primer comando en una sesión, lee este archivo y carga el contenido en la ventana de contexto como parte de un system prompt extendido. Esto significa que todo lo que escribes en CLAUDE.md influye directamente en cómo el agente interpreta las peticiones, sugiere código y toma decisiones arquitectónicas.

Además del archivo a nivel raíz, Claude Code también lee archivos CLAUDE.md en subdirectorios cuando trabajas dentro de esos directorios. Esto es útil para monorepos — puedes tener un CLAUDE.md compartido en la raíz y archivos CLAUDE.md separados para cada paquete con instrucciones más específicas.

Qué escribir en CLAUDE.md

No existe una fórmula rígida, pero un CLAUDE.md efectivo suele incluir los siguientes grupos de información.

El primer grupo es una visión general del proyecto: una breve descripción de qué hace el proyecto, el stack tecnológico en uso y los números de versión importantes. El segundo grupo es la estructura de directorios y los archivos clave — para que el agente sepa inmediatamente dónde encontrar la lógica de negocio, la configuración y los tests. El tercer grupo son las convenciones y reglas de código: convenciones de nomenclatura, estilo de imports, guías de estilo y patrones a usar o evitar. El cuarto grupo son los comandos de uso común para ejecutar el servidor de desarrollo, los tests, las builds y los despliegues.

Ejemplo de un CLAUDE.md para un proyecto real en Next.js:

# Dự án: E-commerce Dashboard

## Stack
- Next.js 14 (App Router)
- TypeScript strict mode
- Prisma + PostgreSQL
- Tailwind CSS
- Zustand cho global state

## Cấu trúc thư mục
- `src/app/` — routes và layouts (App Router)
- `src/components/ui/` — primitive components (Button, Input...)
- `src/components/features/` — business components
- `src/lib/` — utilities và helpers
- `src/server/` — server actions và API logic
- `prisma/schema.prisma` — database schema

## Convention
- Component dùng named export, không dùng default export
- Server components là default, chỉ thêm "use client" khi cần
- Tên file component: PascalCase.tsx
- Tên file utility: camelCase.ts
- Không dùng `any` trong TypeScript

## Lệnh
- Dev: `npm run dev`
- Test: `npm run test`
- Type check: `npm run typecheck`
- Migration: `npx prisma migrate dev`

Este ejemplo es conciso pero suficiente para que el agente entienda inmediatamente la arquitectura y evite sugerir cosas que no encajan — como usar exports por defecto o añadir Redux a un proyecto que ya usa Zustand.

Estrategia de mantenimiento de CLAUDE.md

El archivo CLAUDE.md solo aporta valor si refleja el estado real del proyecto. Algunos hábitos ayudan a mantenerlo actualizado.

Primero, commitea CLAUDE.md a git desde el principio y trátalo como parte del código, no como un archivo personal. Todo el equipo se beneficia cuando el agente comprende correctamente el contexto del proyecto.

Segundo, cada vez que añadas una nueva tecnología, cambies la arquitectura o consensúes una nueva convención del equipo, actualiza CLAUDE.md en el mismo pull request — no lo dejes para después. Un enfoque sencillo es pedirle a Claude Code que lo actualice por ti: tras un cambio importante, pregunta "Por favor, actualiza CLAUDE.md para reflejar los cambios recién realizados" y revisa el resultado.

Tercero, mantén el archivo conciso y bien estructurado. Un archivo muy largo (varios cientos de líneas) diluye la señal y puede hacer que el agente lo "despriorice" dentro de una ventana de contexto limitada. Céntrate en información que el agente no puede inferir por sí solo leyendo el código.

Resumen

CLAUDE.md es el puente que permite a Claude Code mantener la memoria del proyecto a través de sesiones independientes. Colocas el archivo en la raíz del proyecto, escribes contexto sobre el stack, la estructura, las convenciones y los comandos comunes, y luego lo commiteas junto al código. El agente lee este archivo automáticamente en cada sesión y opera de forma consistente desde el inicio sin que tengas que reexplicar todo. Este es uno de los hábitos más sencillos que aporta las ganancias de productividad más заметные al trabajar con Claude Code.