Directorio / Guías / Claude Code

CLAUDE.md: el manual de tu proyecto

Qué es el archivo CLAUDE.md, dónde va, cómo crearlo con /init y qué escribir para que Claude no te pregunte lo mismo en cada sesión.

Guía paso a paso4 min de lecturaPor Rafael Schwart

Cada sesión de Claude Code empieza sin recordar la anterior. CLAUDE.md es un archivo de texto que Claude lee al inicio de cada sesión. Ahí escribes lo que le explicarías a una persona nueva en su primer día: cómo se corre el proyecto, qué reglas sigue y qué no se toca.

Funciona igual que un procedimiento en cualquier operación. Si vive en la cabeza de alguien, cada vez se hace distinto. Si está escrito, se repite igual.

Dónde va

ArchivoDóndePara qué
Del proyectoCLAUDE.md en la carpeta raíz del proyecto, o .claude/CLAUDE.mdLas reglas del proyecto. Si usas git, lo comparte todo el equipo.
Personal~/.claude/CLAUDE.md (en Windows, %USERPROFILE%\.claude\CLAUDE.md)Tus preferencias, en todos tus proyectos.
LocalCLAUDE.local.md en la raíz del proyectoNotas tuyas sobre este proyecto que no quieres compartir. Agrégalo a .gitignore.

Claude carga todos los que apliquen y los suma; uno no reemplaza al otro.

Créalo con /init

  1. Abre Claude Code en la carpeta del proyecto y escribe /init. Claude revisa los archivos y escribe un primer CLAUDE.md con los comandos y convenciones que encuentra. Si ya existe uno, propone mejoras en lugar de reemplazarlo.
  2. Léelo completo. /init solo sabe lo que está en los archivos. Corrige lo que esté mal y borra lo obvio.
  3. Agrega lo que Claude no puede descubrir solo. Quién usa el resultado, qué no se toca y por qué.
  4. Comprueba que cargó. En una sesión nueva, escribe /context all y busca el archivo en la lista Memory files. Para editarlo sin salir de la sesión, usa /memory.

Qué poner

  • Cómo se corre. El comando exacto para instalar, probar y ejecutar.
  • Reglas que se puedan verificar. «Los montos van con dos decimales y separador de miles» se comprueba. «Haz un buen trabajo» no.
  • Qué no tocar. Carpetas con datos originales, archivos que mantiene otra persona, configuración de producción.
  • Dónde está cada cosa. Una línea por carpeta importante, no por archivo.

Qué no poner

  • Secretos. Contraseñas, claves de API, tokens. El archivo suele terminar en git, y cualquiera con acceso al proyecto lo puede leer. Las claves van en un archivo .env que no se sube.
  • Lo que cambia todos los días. Los pendientes de hoy o las ventas de esta semana. Envejecen rápido y confunden.
  • Procedimientos largos. Si una sección se volvió un paso a paso de veinte líneas, conviértela en un skill: solo se carga cuando se usa.
  • Lo que Claude ya ve en los archivos. No describas cada archivo ni copies el código.

La documentación oficial recomienda menos de 200 líneas por archivo. Mientras más largo, más espacio ocupa en cada sesión y peor se sigue.

Un ejemplo para un negocio pequeño

Un script que arma el reporte semanal de ventas a partir de lo que exporta el punto de venta:

# Reporte semanal de ventas

Script que lee las ventas exportadas del punto de venta y genera
un Excel para la reunión del lunes. Lo usa la gerente de tienda.

## Cómo se corre
- Instalar dependencias: pip install -r requirements.txt
- Generar el reporte: python reporte.py --semana 2026-45
- El resultado queda en salidas/reporte-2026-45.xlsx

## Carpetas
- datos/: exportaciones originales del punto de venta. Solo lectura.
- salidas/: reportes generados. Se pueden borrar y volver a generar.
- reporte.py: todo el cálculo.

## Reglas
- Nunca modifiques ni borres archivos en datos/.
- Montos con dos decimales y separador de miles.
- Las devoluciones restan en la semana en que ocurren, no en la de la venta.
- Si una columna del archivo exportado cambia de nombre, detente y avísame.
  No adivines.

## No tocar
- .env (credenciales del correo que envía el reporte)
- precios/lista-oficial.xlsx (la actualiza administración)

Fíjate en que el ejemplo nombra el archivo .env, pero no copia lo que tiene adentro. Y que cada regla se puede comprobar mirando el resultado.

CLAUDE.md es contexto, no un candado. Claude lo sigue casi siempre, pero si una regla se tiene que cumplir cada vez, como no editar un archivo, refuérzala con un hook.

Cuándo actualizarlo

Cada vez que corriges a Claude por lo mismo por segunda vez, esa corrección va al CLAUDE.md. Revísalo de vez en cuando y quita lo que ya no aplica: dos reglas que se contradicen confunden más que ninguna, porque Claude puede elegir cualquiera de las dos.

Sigue leyendo

Más guías.

Cada una se lee en menos de cinco minutos.

Todas las guías
Guía paso a paso · 4 min

Claude Code desde cero

Qué es Claude Code, cómo instalarlo en Windows o Mac, tu primer pedido, cómo aprobar lo que hace y los comandos que vas a usar cada día.

  Arqentia

¿Prefieres que lo armemos contigo?

Treinta minutos para ver tu operación: cómo entra el dinero, dónde se pierde tiempo y qué conviene automatizar primero. Gratis para negocios y sin compromiso.

Agendar consulta