Claude Code — Instrucciones de proyecto (CLAUDE.md) · Agentes de IA para programar

Los archivos CLAUDE.md son la memoria de Claude Code: markdown que se carga automáticamente en el contexto al arrancar. Úsalos para convenciones, notas de arquitectura y comandos que Claude debería conocer sin que se los digas.

Ubicaciones y precedencia

Tipo	Ubicación	Notas
Política de empresa	macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`; Linux/WSL `/etc/claude-code/CLAUDE.md`; Windows `C:\ProgramData\ClaudeCode\CLAUDE.md`	Instrucciones para toda la organización
Proyecto	`./CLAUDE.md` o `./.claude/CLAUDE.md`	Súbelo a git — se comparte con el equipo
Usuario	`~/.claude/CLAUDE.md`	Preferencias personales para todos tus proyectos
Proyecto, local	`./CLAUDE.local.md`	Obsoleto — usa importaciones con `@` en su lugar

Las entradas de arriba se cargan primero y tienen prioridad. Todos los archivos de memoria se cargan en el contexto al arrancar.

Cómo se buscan

Claude Code sube hacia arriba desde el directorio actual hasta / (sin incluirlo), leyendo cada CLAUDE.md / CLAUDE.local.md que encuentra — así que una sesión abierta en repo/services/api/ también recoge la memoria de la raíz del repositorio.
Los CLAUDE.md anidados en subdirectorios se cargan bajo demanda, cuando Claude lee archivos de esos subdirectorios.

Importaciones: `@ruta/al/archivo`

Puedes traer otros archivos a la memoria con importaciones @:

Mira @docs/architecture.md para una visión general del sistema.
Sigue las convenciones de @~/.claude/my-project-instructions.md.

Funcionan tanto las rutas relativas como las absolutas, incluidas las de tipo @~/....
Las importaciones se anidan hasta 5 saltos.
@ no se evalúa dentro de código en línea ni de bloques de código.
Con /memory ves todo lo que hay cargado en ese momento.

Editar la memoria

/init — genera un CLAUDE.md inicial para el proyecto.
/memory — abre los archivos de memoria en el editor del sistema.
Memoria rápida con # — empieza cualquier mensaje con # y se te preguntará en qué archivo de memoria guardar esa línea:

> # Ejecuta siempre pnpm test antes de commitear

Memoria automática

Claude también va acumulando aprendizajes entre sesiones por su cuenta. Para desactivarlo:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Ejemplo de CLAUDE.md

# Acme Web App

App de Next.js 15 con backend en Postgres. El gestor de paquetes es pnpm — nunca uses npm.

## Comandos

- `pnpm dev` — arranca el servidor de desarrollo
- `pnpm test` — ejecuta los tests (tienen que pasar antes de commitear)
- `pnpm db:migrate` — aplica las migraciones de base de datos

## Convenciones

- TypeScript en modo estricto; nada de `any` sin un comentario que lo justifique.
- React Server Components por defecto; añade `"use client"` sólo cuando haga falta.
- Las rutas de API viven en `app/api/`; deja los handlers finos y la lógica en `lib/services/`.
- Los errores se reportan con `lib/reportError.ts`, nunca se silencian.

## Flujo de trabajo

- Haz commits pequeños y revisables, con mensajes de conventional commits.
- Ejecuta `pnpm test` y `pnpm lint` antes de dar por terminada cualquier tarea.
- Los cambios de base de datos requieren un archivo de migración, nunca ediciones a mano.

## Trampas conocidas

- `lib/legacy/` es código generado — no lo edites; regenéralo con `pnpm gen:legacy`.
- Los tests atacan un Postgres real en el `:5433`; ver @docs/testing.md.

Última verificación: 2026-09-07

Fuentes oficiales:

Las herramientas de IA para programar evolucionan rápido. Si encuentras información desactualizada, abre un issue o un pull request.