Inicialización del proyecto: Usa /init para generar CLAUDE.md con un clic

📚 Navegación de la serie: El artículo anterior 11 Versión web y en la nube te sacó de la terminal y te permitió usar Claude Code en el navegador y en entornos en la nube. Este artículo vuelve al entorno local, a un hábito que es esencial cultivar: lo primero que debes hacer al entrar en un proyecto nuevo es escribir /init, y dejar que Claude escanee la base de código y escriba el manual del proyecto por ti. Siguiente artículo: 13 Estructura del proyecto.

Amigos, primero les contaré sobre una acción tonta muy común.

Cuando empecé a usar Claude Code, me hice cargo de un proyecto backend en Node.js que dejó un antiguo colega. Empecé a trabajar directamente sin ejecutar /init. La primera vez que le pregunté "cómo se ejecutan las pruebas", tuvo que buscar en el package.json antes de responder; veinte minutos después, en una nueva sesión, volvió a buscar desde el principio para la misma pregunta; por la tarde, al cambiar de tarea, me preguntó por tercera vez "si este proyecto usa npm o pnpm".

Llegado a este punto me resultó molesto: no es que sea tonto, es que no le di un "manual del proyecto", por lo que tiene que explorar desde cero cada vez. Una vez que aprendes a escribir /init primero al entrar a un proyecto, todas estas repeticiones desaparecen: entiende el proyecto de una vez, lo escribe en un archivo CLAUDE.md y lo guarda. A partir de entonces, cada vez que inicia una sesión trae este contexto, y nunca más tienes que explicárselo repetidamente.

En pocas palabras, /init hace solo una cosa: cambia "que Claude explore tu proyecto desde cero cada vez" a "que lo explore una vez y lo recuerde a largo plazo". Este artículo explicará claramente cómo se usa, qué aspecto tiene el resultado generado y qué te ahorra exactamente.

Después de leer este artículo, obtendrás:

• Comprender el punto de dolor central que resuelve /init: de "explorar desde cero cada vez" a "generar memoria a largo plazo de una vez".
• Un conjunto de operaciones que puedes simplemente teclear: iniciar claude en el directorio raíz del proyecto y teclear /init.
• Saber qué hace en segundo plano: escanea la estructura, identifica la pila tecnológica y genera un borrador de CLAUDE.md.
• Entender el aspecto general del CLAUDE.md generado y para qué sirve cada parte.
• Una percepción clave: /init es solo el punto de partida, el borrador debe completarse manualmente (cómo hacerlo, lo dejamos para el artículo 18).

---

01 ¿Por qué tener /init?: El problema de "amnesia" de Claude

Primero la conclusión: Cada vez que Claude Code abre una nueva sesión, se encuentra en un estado de "amnesia": no recuerda lo que le dijiste la última vez.

Esto no es un error, es su diseño. La documentación oficial lo dice muy claro:

Cada sesión de Claude Code comienza con una ventana de contexto completamente nueva.

Analogía: Es como si un nuevo becario llegara a trabajar cada día. Este becario es muy capaz, pero tiene un defecto: lo que le enseñaste hoy, mañana vendrá otra persona y tendrás que enseñárselo todo de nuevo. Le dices "usamos pnpm, no npm", "las pruebas están en el directorio tests/", "tienes que ejecutar el lint antes de hacer un commit", y al día siguiente llega uno nuevo y tienes que contárselo todo desde el principio.

Este es el estado real cuando no hay CLAUDE.md. La trampa en el proyecto de Node.js mencionada anteriormente surgió así: no es que Claude tenga mala memoria, es que simplemente no tiene un medio de memoria entre sesiones.

Entonces, ¿qué hacemos? La documentación oficial proporciona dos conjuntos de mecanismos para transferir conocimiento entre sesiones. Este artículo solo cubre el primero:

Mecanismo	Quién lo escribe	Qué contiene
Archivo CLAUDE.md	Tú (puedes dejar que /init haga un borrador)	Instrucciones y reglas: arquitectura del proyecto, comandos de compilación, convenciones
Memoria automática (Auto Memory)	El propio Claude	La experiencia y los aprendizajes de depuración que acumula mientras trabaja

Ten en cuenta que la memoria automática tiene un límite estricto: cada sesión solo carga las primeras 200 líneas o 25 KB, el exceso no entra en el contexto. Por lo tanto, no es confiable meter demasiadas cosas usando la memoria automática; CLAUDE.md es la fuerza principal.

CLAUDE.md (el archivo de memoria del proyecto) es ese manual de inducción escrito para los "becarios que cambian todos los días": lo escribes de antemano y lo pones en el proyecto, cada vez que Claude comienza, lo lee primero y de inmediato "recuerda" de qué va este proyecto.

Y /init es el comando que te ayuda a generar el primer borrador de este manual con un solo clic.

💡 Resumen en una oración: Cada vez que Claude abre una sesión tiene "amnesia", CLAUDE.md es su medio de memoria entre sesiones: /init te ayuda a escribir el primer borrador de esta memoria con un clic.

---

02 Qué es /init: Dejar que Claude escriba su propio manual

/init es un comando de barra diagonal (slash command) incorporado en Claude Code (un comando que comienza con / en el cuadro de entrada).

Lo que hace se puede resumir en una frase: deja que Claude escanee tu proyecto y genere un borrador de CLAUDE.md exclusivo para este proyecto.

La descripción oficial es muy precisa:

Ejecuta /init para generar automáticamente un CLAUDE.md inicial. Claude analiza tu base de código y crea un archivo que contiene comandos de compilación, instrucciones de prueba y las convenciones del proyecto que descubre.

Analogía: Dejar que el nuevo empleado escriba su propio manual de inducción. Generalmente, el manual de inducción lo escribe un empleado veterano para que lo lea el nuevo. Pero /init es al revés: deja que el "recién llegado" lea todo el proyecto primero y luego organice lo que leyó (qué tecnología se usa, cómo se dividen los directorios, cómo ejecutar los comandos) en un manual. Si lo leyó correctamente o no, te darás cuenta al echarle un vistazo después.

El beneficio de este diseño es muy práctico: los hechos objetivos del proyecto (pila tecnológica, estructura de directorios, scripts disponibles), Claude puede extraerlos escaneándolos él mismo, no necesitas escribirlos palabra por palabra. El esfuerzo que te ahorras puedes usarlo para completar lo que no puede escanear (como las convenciones de nomenclatura de ramas del equipo), y con eso es suficiente.

¿Cuándo deberías usarlo? Generalmente, hay estos desencadenantes:

• Hacerse cargo de un proyecto que dejó otra persona: ni siquiera te has familiarizado con él, así que dejas que lo escanee primero para tener una base.
• Tu propio proyecto aún no tiene CLAUDE.md: lo has estado usando a pelo y ya es hora de agregarlo.
• Clonar un proyecto de código abierto y querer modificarlo: primero haz /init para obtener el mapa del proyecto, luego ponte a trabajar.

💡 Resumen en una oración: /init permite que Claude lea el proyecto por sí mismo y organice los hechos objetivos en un borrador de CLAUDE.md: te ahorras el esfuerzo de extraer los hechos y te concentras en completar lo que no puede escanear.

---

03 Cómo ejecutarlo: Entrar al directorio, iniciar, escribir comando

La operación es tan simple que parece anticlimática: después de iniciar claude, simplemente escribe /init en el cuadro de entrada y ya está.

Paso 1: Inicia Claude Code en el directorio raíz del proyecto.

Este paso es crucial, asegúrate de usar cd para entrar al directorio raíz del proyecto antes de iniciarlo, no puedes iniciarlo a pelo en el escritorio o en el directorio de inicio. Se enfatizó en el artículo 07: donde lo inicies, Claude lo considerará su espacio de trabajo y leerá los archivos de allí. Si ejecutas /init en tu directorio de inicio, escaneará un montón de tus archivos personales desordenados y no obtendrá nada útil.

cd /ruta/a/tu-proyecto
claude

Paso 2: Escribe /init en el cuadro de entrada y presiona Enter.

/init

Eso es todo. A continuación, no tienes que hacer nada, el resto lo hace todo Claude. Todo el proceso no requiere intervención manual, él analizará automáticamente y generará el resultado automáticamente.

Entonces, ¿qué hizo exactamente en segundo plano? Después de ejecutarlo muchas veces, el proceso es más o menos así:

Todo el asunto unido en una línea es: Iniciar claude en el directorio del proyecto → Escribir /init → Claude escanea la estructura del proyecto, identifica la pila tecnológica → Guarda un borrador de CLAUDE.md en el disco → Ajustas y completas manualmente. Los primeros cuatro pasos son básicamente automáticos, y el último paso de "ajuste manual" es la clave para convertir el borrador en un buen manual; esto se menciona en este artículo, pero se explica en detalle en el artículo 18.

La descripción oficial para este paso es "analiza tu base de código". En cuanto a qué archivos se escanean específicamente, generalmente se reducen a estas categorías (básicamente revisará todo esto):

• Manifiestos de dependencias: package.json (Node), requirements.txt (Python), pom.xml (Java) y similares: se usan para determinar la pila tecnológica y los comandos que se pueden ejecutar.
• Documentación existente: README y similares: para entender qué hace el proyecto.
• Archivos de configuración + Estructura de código: para entender cómo se dividen los directorios y dónde están los puntos de entrada.

⚠️ Un detalle que se pasa por alto fácilmente: Si el proyecto ya tiene un CLAUDE.md, /init no lo sobrescribirá bruscamente. La documentación oficial lo dice claramente: en este caso, sugerirá mejoras en lugar de sobrescribir. Si escribes /init nuevamente en un proyecto donde CLAUDE.md ya está escrito, podrías preocuparte de que lo escribiste en vano, pero honestamente enumerará un par de sugerencias de "aquí puedes agregar", sin tocar ni una línea del original. Este diseño es bastante considerado.

💡 Resumen en una oración: Usa cd para entrar al directorio raíz del proyecto, inicia claude, escribe /init y deja que escanee automáticamente: si ya existe CLAUDE.md, solo sugiere mejoras y no lo sobrescribe.

---

04 Qué aspecto tiene el resultado: Desglose del borrador de CLAUDE.md

Después de ejecutar /init, aparecerá un archivo CLAUDE.md en el directorio raíz de tu proyecto. Al abrirlo, verás un Markdown claramente estructurado.

Analogía: Un manual de proyecto estándar. No es un diario corriente, está dividido en secciones: qué hace el proyecto, qué tecnología usa, cómo se dividen los directorios, cómo se ejecutan los comandos y cuáles son las convenciones. Si un recién llegado (incluido Claude después de su "amnesia" en la próxima sesión) echa un vistazo a estas secciones, sabrá de qué va este proyecto.

El contenido generado generalmente cubre estas partes (los campos específicos que Claude utilizará variarán según la situación real de tu proyecto, a continuación se muestra un aspecto típico):

# Nombre del proyecto

## Descripción del proyecto
Describe brevemente qué hace este proyecto y cuáles son sus funciones principales.

## Pila tecnológica
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Base de datos: PostgreSQL

## Estructura de directorios
- `src/components/` - Componentes de React
- `src/api/`        - Capa de API
- `tests/`          - Archivos de prueba

## Comandos comunes
- Iniciar servidor de desarrollo: `pnpm dev`
- Ejecutar pruebas: `pnpm test`
- Revisión de código: `pnpm lint`

## Convenciones de desarrollo
- Usar modo strict de TypeScript
- Ejecutar `pnpm test` antes de confirmar cambios (commit)

Hablemos del valor de cada bloque, una por una: estas son exactamente las cosas sobre las que Claude te preguntaba repetidamente en el pasado:

Este bloque	Qué contiene	Las repeticiones que te ahorra
Descripción del proyecto	Propósito del proyecto, funciones principales	No tener que explicar "qué hace este proyecto" cada vez
Pila tecnológica	Qué frameworks, lenguajes, bases de datos usa	No tener que responder "esto es React o Vue" cada vez
Estructura de directorios	Qué hay en los directorios clave, dónde está el punto de entrada	No tener que buscar "en qué carpeta está el código de la API" cada vez
Comandos comunes	Cómo iniciar, probar y revisar	No tener que revisar package.json cada vez para buscar comandos
Convenciones de desarrollo	Reglas del proyecto (como modo strict)	No tener que recordar "asegúrate de activar el modo estricto" cada vez

¿Lo entiendes? En el proyecto de Node.js anterior, las preguntas agotadoras de "cómo ejecutar las pruebas" y "si usar npm o pnpm" fueron respondidas de una vez por las secciones de "Comandos comunes" y "Pila tecnológica". Una vez que el manual está escrito y colocado ahí, Claude lo lee al principio y estas conversaciones repetitivas se reducen a cero.

En cuanto a dónde debe colocarse este archivo, la ubicación oficial dada es ./CLAUDE.md en el directorio raíz del proyecto (o ./.claude/CLAUDE.md). /init lo coloca en el lugar correcto de manera predeterminada, por lo que no tienes que preocuparte por la ruta. La relación jerárquica más detallada (cómo se superponen el nivel de usuario y el nivel de proyecto), la dejaremos para el artículo 18.

💡 Resumen en una oración: El CLAUDE.md generado se divide en secciones de "Descripción / Pila tecnológica / Directorios / Comandos / Convenciones", cada una elimina precisamente un tipo de preguntas repetitivas que hacía antes: /init se encarga de ubicar el archivo por ti.

---

05 Percepción clave: /init es el punto de partida, no el final

Esta es la frase que más quiero que recuerdes de este artículo: /init genera un borrador, no la versión final.

¿Por qué se debe completar manualmente? Porque hay cosas que Claude no puede extraer incluso si escanea toda la base de código: simplemente no están en el código, solo están en tu mente y en la del equipo.

Aquí hay algunos ejemplos que Claude definitivamente no puede inferir por sí mismo:

• Convenciones de nomenclatura de ramas: Han acordado feature/xxx, fix/xxx, ¿en qué archivo está escrito eso? En ninguno. Claude no lo puede escanear.
• Proceso de despliegue: ¿Fusionar a main activa el despliegue automáticamente o hay que hacerlo manualmente? No se puede ver en el código del proyecto.
• Requisitos de Code Review: "Un PR debe ser aprobado por dos personas", "Para cambios en módulos clave, primero proponer un plan en Modo Plan"; estas son reglas implícitas del equipo.
• Contexto de negocio: Por qué esta parte fue diseñada de esta manera, qué módulo es propenso a errores si se toca; estos "porqués" están escondidos en tu cabeza.

La forma correcta es la optimización iterativa, no codificar todo rígidamente de una vez.

El proyecto de Node.js anterior es el ejemplo perfecto de uso incorrecto: después de ejecutar /init pensé que todo estaba listo y no lo completé. Resultó que los "comandos comunes" generados omitieron un script de despliegue personalizado (porque ese script estaba oculto en scripts/ y no expuesto en package.json), por lo que naturalmente Claude no lo escaneó. Tuve que agregar manualmente una línea en CLAUDE.md: "Para desplegar usa ./scripts/deploy.sh", para completarlo verdaderamente. Por lo tanto, el hábito correcto es fijo: después de ejecutar /init, léelo inmediatamente de principio a fin y agrega manualmente las restricciones estrictas que no pudo escanear.

La comparación de la forma correcta es así:

❌ Uso incorrecto	✅ Uso correcto
Después de ejecutar /init no le haces caso, lo usas como versión final	Después de ejecutar /init lo lees por completo, lo tratas como un borrador a revisar
Esperar que extraiga todas las convenciones del equipo	Agregar manualmente las restricciones que no puede escanear (ramas, despliegue, revisión)
Escribirlo una vez y no volver a tocarlo	Iterarlo continuamente a medida que el proyecto evoluciona, eliminar lo obsoleto

Solo recuerda esta división del trabajo: /init es responsable de extraer rápidamente los hechos objetivos como base (en lo cual es bueno), tú eres responsable de agregar las convenciones subjetivas y el contexto del negocio (solo tú lo sabes). Con ambas partes trabajando juntas, obtienes un CLAUDE.md verdaderamente útil.

En cuanto a "cómo convertir este borrador en un manual conciso y útil" — por ejemplo, cómo diseñar la jerarquía, cómo usar referencias para dividirlo, cómo mantenerlo a largo plazo — ese es el trabajo del artículo 18 "Guía de uso de CLAUDE.md". En este artículo, solo necesitas "tenerlo", y el siguiente paso es "escribirlo bien".

💡 Resumen en una oración: /init solo extrae los hechos objetivos como base, las convenciones del equipo y el proceso de despliegue que no puede escanear deben ser agregados manualmente por ti: el borrador solo cuenta después de ser revisado.

---

06 Manos a la obra: Ejecuta /init en un proyecto mínimo

Hablar por hablar no tiene sentido. A continuación, utilizaremos un proyecto mínimo de dos o tres archivos para guiarte a través de /init por completo, verificando que realmente genera CLAUDE.md. No depende de ningún entorno complejo, simplemente sigue y teclea.

Paso 1: Crea un proyecto mínimo (Mac / Linux)

mkdir init-demo
cd init-demo
echo '{"name": "init-demo", "scripts": {"test": "echo test ok"}}' > package.json
echo 'console.log("hello from init-demo");' > index.js

Usuarios de Windows PowerShell: escriban mkdir init-demo, cd init-demo. Para esos dos archivos package.json e index.js, creenlos usando el Bloc de notas, peguen el contenido que está entre comillas simples de arriba y guardenlos.

Resultado esperado: En la carpeta init-demo hay dos archivos, package.json e index.js. Al escribir ls (usar dir en Windows) podrás verlos.

Paso 2: Inicia Claude Code en el directorio del proyecto

claude

Resultado esperado: Aparece la pantalla de bienvenida con un cuadro de entrada en la parte inferior. Confirma que la terminal se encuentra actualmente en el directorio init-demo.

Paso 3: Ejecuta /init

En el cuadro de entrada escribe:

/init

Resultado esperado: Claude comenzará a desplazarse por la pantalla: verás que lee package.json, index.js, analiza el proyecto y luego escribe el archivo. Al finalizar, te dirá que se ha generado CLAUDE.md. Dado que este proyecto tiene solo dos archivos, todo el proceso será muy rápido, desde unos pocos hasta unos diez segundos.

Paso 4: Confirma que CLAUDE.md se ha generado

Sal de Claude (escribe exit o presiona Ctrl+D) y vuelve a la terminal para revisar:

cat CLAUDE.md

(En Windows PowerShell usa type CLAUDE.md)

Resultado esperado: La terminal imprimirá un documento Markdown donde, como mínimo, verás el nombre del proyecto init-demo, que la pila tecnológica es Node.js / JavaScript, y que el comando test (echo test ok) fue identificado como "Ejecutar pruebas". Ver esto = /init funcionó correctamente y realmente entendió y recordó este pequeño proyecto.

Paso 5 (Opcional): Verifica que lo "recordó"

Vuelve a entrar a claude y pregunta:

¿Cuál es el comando de prueba de este proyecto?

Resultado esperado: Te dirá el comando de prueba directamente, sin necesidad de ir a buscar en package.json de nuevo, porque la respuesta ya está escrita en el CLAUDE.md que lee al iniciar. Con esto, verás con tus propios ojos que la "amnesia" se ha curado.

⚠️ Pequeño recordatorio: en un proyecto real, /init escanea muchos más archivos y el contenido generado es mucho más rico, por lo que se ejecutará más lento que en esta demostración, ten paciencia y espera a que termine de escanear; después de escanear, no olvides lo que se mencionó en la Sección 05: léelo todo de nuevo y agrega manualmente las restricciones estrictas que no pudo escanear.

💡 Resumen en una oración: Crea un proyecto mínimo de dos archivos, escribe /init en claude, sal y haz cat CLAUDE.md, y verás con tus propios ojos que ha entendido el proyecto; luego pregunta cuál es el comando de prueba para verificar que la "amnesia" está curada.

---

07 Resumen

En este artículo, hemos explicado a fondo una sola acción: lo primero que debes hacer al entrar a un proyecto nuevo es escribir /init para que Claude mismo escriba el primer borrador del manual del proyecto.

Repasemos los puntos clave:

Dimensión	Conclusión
Qué resuelve	Claude tiene "amnesia" en cada sesión, CLAUDE.md es el medio de memoria entre sesiones
Qué es /init	El comando que permite a Claude escanear el proyecto y generar automáticamente el borrador de CLAUDE.md
Cómo ejecutarlo	Usa cd para entrar al directorio raíz del proyecto → Inicia claude → Escribe /init
Qué hace	Escanea la estructura, identifica la pila tecnológica, extrae comandos, los guarda como borrador
Qué aspecto tiene	Se divide en secciones de descripción, tecnología, directorios, comandos y normas
Percepción clave	El borrador no es la versión final: las convenciones del equipo deben agregarse manualmente

Ahora deberías ser capaz de: Entrar a cualquier proyecto, iniciar claude en el directorio raíz y escribir /init para que genere automáticamente un CLAUDE.md, entender qué es cada sección en el contenido generado y comprender que esto es solo el punto de partida: los hechos objetivos él los saca por ti, pero las convenciones subjetivas debes agregarlas tú mismo. A partir de ahora, Claude ya no es un "nuevo empleado amnésico que cambia todos los días", sino un veterano que ha leído el manual de tu proyecto desde el principio.

---

El próximo artículo es 13 "Estructura del proyecto": después de ejecutar /init, la "estructura de directorios" en CLAUDE.md es lo que Claude ha escaneado. Pero un proyecto, además de CLAUDE.md, también tiene un directorio .claude/, settings.json, comandos personalizados, configuración de MCP, y un montón de "archivos exclusivos de Claude Code" que cumplen diferentes funciones. ¿Dónde se guardan y qué aspecto tienen? El próximo artículo te ayudará a aclarar toda esta estructura de proyecto de una vez por todas.

---

Lecturas recomendadas

• Equipos de agentes inteligentes (Agent teams): Colaboración en múltiples sesiones
• Mejores prácticas: Agrupa buenos hábitos dispersos en una mentalidad que puedas seguir
• Configuración de desarrollo: Ajusta el "entorno de trabajo" donde Claude hace las cosas