6. Inicialización de proyectos y CLAUDE.md

Objetivo del tema

Aprender a preparar cualquier proyecto para trabajar con Claude Code: generar el archivo de memoria CLAUDE.md con el comando /init, entender qué información conviene incluir (y cuál no), diferenciar los niveles de memoria disponibles y aprovechar las importaciones modulares y el atajo rápido #.

6.1 ¿Qué es CLAUDE.md y por qué importa?

Cuando abres Claude Code sobre un repositorio nuevo, el agente no sabe nada de él: cómo compilar, dónde viven los tests, qué convenciones sigue el equipo. El archivo CLAUDE.md resuelve esto: es un documento Markdown que Claude Code carga automáticamente en su contexto al iniciar cada sesión, convirtiéndose en la memoria persistente del proyecto.

Piensa en él como el "manual de incorporación" que le entregarías a un desarrollador nuevo en su primer día:

• Contexto persistente: no necesitas repetir las mismas explicaciones en cada conversación; el agente ya nace sabiendo cómo se trabaja en el proyecto.
• Consistencia: todas las sesiones (y todos los miembros del equipo) reciben exactamente las mismas reglas, sin depender de la memoria de cada persona.
• Prompts más cortos: al no tener que re-explicar el entorno, tus pedidos se centran en la tarea y el modelo dispone de más espacio útil para el código.

No se trata de documentación para humanos (el README cumple ese rol): es documentación para el agente, escrita en lenguaje natural pero con efecto directo sobre su comportamiento.

6.2 El comando /init paso a paso

La forma recomendada de crear este archivo es dejar que el propio agente lo redacte. Desde la terminal, dentro del proyecto:

cd /ruta/a/tu/proyecto
claude
/init

Al ejecutar /init, el agente explora el repositorio (README, manifiestos, configuraciones, estructura de carpetas) y genera un CLAUDE.md conciso y específico del proyecto. Se centra en lo que las sesiones futuras más necesitan:

Si ya existe un CLAUDE.md, /init lo mejora en lugar de reemplazarlo a ciegas, así que puedes re-ejecutarlo cuando el proyecto cambie de estructura sin miedo a perder el trabajo previo.

6.3 Anatomía de un buen CLAUDE.md

También puedes escribirlo a mano. Este ejemplo ilustra el nivel de detalle útil para un monorepo TypeScript:

# API de pedidos (monorepo)

## Comandos
- Instalar dependencias: bun install
- Tests: bun test
- Verificación completa antes de entregar: bun run check

## Estructura
- packages/core: lógica de negocio compartida
- packages/functions: funciones serverless
- infra/: definición de infraestructura por servicio

## Estándares de código
- TypeScript en modo estricto
- El código compartido va en packages/core con exports configurados

## Convenciones
- Importar módulos compartidos por nombre de workspace: @api/core/...
- IMPORTANTE: no modificar archivos generados en packages/functions/generated/

Tres principios que separan un buen archivo de uno inútil:

1. Instrucciones accionables, no aspiraciones: "escribe código de calidad" no cambia el comportamiento; "usa TypeScript estricto y valida entradas con Zod" sí.
2. Concisión: cada línea ocupa contexto en todas las sesiones. Si algo ya está en el README o en los comentarios del código, referencia el archivo en lugar de duplicarlo.
3. Énfasis donde importa: para reglas críticas, refuérzalas con IMPORTANT o YOU MUST; el modelo les da mayor peso que a una mención pasiva.

6.4 Los niveles de memoria

Claude Code lee instrucciones desde varias ubicaciones, cada una con un propósito distinto. Elegir el nivel correcto es la diferencia entre una configuración limpia y una mezcla confusa:

Niveles de memoria y su alcance

Nivel	Ubicación	Alcance	Uso recomendado
Corporativo	Directorio del sistema gestionado por IT	Todos los usuarios de la organización	Políticas obligatorias de seguridad y estilo, definidas centralizadamente.
Usuario (global)	~/.claude/CLAUDE.md	Todas tus sesiones, en cualquier proyecto	Preferencias personales: idioma de respuesta, estilo de commits, atajos propios.
Proyecto	CLAUDE.md en la raíz (versionado)	Todo el equipo sobre ese proyecto	Comandos, arquitectura y convenciones compartidas. El nivel más usado.
Subdirectorio	packages/api/CLAUDE.md, etc.	Sesiones que trabajan en esa zona	Reglas específicas de un módulo en monorepos grandes.
Local (personal)	CLAUDE.local.md	Solo tu máquina, en ese proyecto	Preferencias personales del proyecto; hoy se prefiere usar importaciones desde la memoria global.

Las reglas globales y locales no viajan por Git, así que reserva esos niveles para gustos personales; lo compartido por el equipo pertenece al repositorio.

6.5 Cómo se cargan las memorias

Al iniciar una sesión, Claude Code recorre el directorio de trabajo hacia arriba y carga los CLAUDE.md que encuentre, además del archivo global del usuario. Los archivos de subdirectorios siguen una regla distinta y eficiente: se cargan bajo demanda, cuando el agente lee o edita archivos de esa zona del proyecto.

Este diseño tiene una consecuencia práctica importante para monorepos: puedes mantener un CLAUDE.md breve en la raíz y memoria detallada por paquete, y el contexto se consumirá solo donde haga falta. Un monolito de documentación en la raíz paga peaje en cada sesión, incluso cuando el trabajo toca un solo archivo.

6.6 Importaciones modulares con @

Dentro de cualquier archivo de memoria, la sintaxis @ruta/al/archivo importa el contenido de otros archivos, lo que permite organizar la memoria en módulos reutilizables:

CLAUDE.md individual de cada proyecto que importa reglas comunes:
See @~/.claude/docs/estilo-commits.md
Convenciones de API: @docs/api-standards.md
Guía de pruebas: @docs/testing.md

Detalles a tener en cuenta:

• Funciona con rutas relativas al archivo que importa y con rutas absolutas (incluido ~ para tu home).
• Las importaciones pueden anidarse, con un límite de profundidad (hasta cinco saltos) que evita círculos infinitos.
• Los archivos importados no necesitan ser Markdown: también es válido importar un Makefile, un JSON de configuración o cualquier texto relevante.

Así mantienes un CLAUDE.md corto mientras la guía detallada vive en archivos modulares, potencialmente compartidos entre varios proyectos.

6.7 El atajo # y el comando /memory

Dos utilidades convierten el mantenimiento de la memoria en un hábito continuo en lugar de una tarea aparte:

• Atajo #: si una entrada del prompt comienza con #, Claude Code la interpreta como una memoria a guardar: te pregunta en qué archivo almacenarla (proyecto, usuario o local) y la agrega. Ejemplo: cuando descubres que los tests corren con make test-ci y no con npm test, escribes # los tests del CI corren con make test-ci y listo, queda registrado para siempre.
• Comando /memory: abre los archivos de memoria en tu editor para revisarlos y ajustarlos cómodamente.

La práctica recomendada es tratar la memoria como un diario de aprendizaje del proyecto: cada gotcha descubierto, cada convención acordada en una revisión de código y cada comando olvidado termina, tarde o temprano, en el CLAUDE.md.

6.8 Qué incluir y qué evitar

Contenido recomendado y contenido a evitar

Incluir	Evitar
Comandos de build, test y lint con su orden correcto.	Replicar contenido extenso del README o de la documentación existente.
Gotchas específicos: variables de entorno necesarias, servicios que deben estar levantados, comandos con nombres engañosos.	Frases vagas y aspiracionales ("escribe buen código", "sé cuidadoso") que no alteran el comportamiento.
Convenciones de estilo propias del equipo y excepciones a las reglas generales del lenguaje.	Instrucciones contradictorias entre sí o con la configuración real del repositorio.
Reglas críticas con énfasis explícito (IMPORTANT, YOU MUST).	Volcar todo el conocimiento del equipo en la raíz: usa subdirectorios e importaciones.
Referencias a documentos detallados para carga bajo demanda.	Información efímera (estado actual de ramas, tareas pendientes) que pertenece a issues.

6.9 Mantenimiento y trabajo en equipo

• El CLAUDE.md es código: revísalo en pull requests, discute sus cambios como cualquier archivo fuente y decide sus modificaciones con criterio técnico.
• Ajusta como quien ajusta prompts: si el agente comete el mismo error dos veces, no lo corrijas a mano una tercera: conviértelo en regla.
• Un solo punto de verdad: cuando una convención cambie, actualiza la memoria el mismo día; un CLAUDE.md desactualizado es peor que ninguno, porque induce errores con confianza.
• Divide responsabilidades: README para personas, CLAUDE.md para el agente, documentación técnica importada con @. Cada cosa en su lugar.
• En equipos grandes: nombra responsables de la memoria por área y revisa trimestralmente que las reglas sigan vigentes.

Conclusión: invertir quince minutos en un buen CLAUDE.md mejora todas las sesiones futuras: el agente compila, testa y respeta las convenciones sin que tengas que explicárselo cada vez. Con el proyecto inicializado, estamos listos para explorar a fondo la interfaz interactiva en el próximo tema.