Arrancar un Nuevo Proyecto con /init
/init es un comando de barra de Claude Code que escanea un repositorio nuevo (o existente) y redacta un CLAUDE.md inicial para ti, de modo que no tengas que escribir la memoria del proyecto desde cero.
Resumen
Cada nuevo proyecto eventualmente necesita un CLAUDE.md que describa sus convenciones, estructura y reglas.
Escribirlo desde cero significa re-derivar cosas que Claude Code ya puede ver por sí mismo, como el lenguaje, la disposición de las carpetas y la configuración de las pruebas.
/init cierra esa brecha haciendo que Claude Code examine el proyecto primero y produzca un borrador, que luego tú lees y corriges.
Es el camino más rápido desde "sin memoria de proyecto" hasta "un CLAUDE.md funcional", aunque el resultado aún necesita una revisión humana.
Receta
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
cd mi-proyecto
claude
# una vez dentro de la sesión de Claude Code:
/initCuándo usar esto:
- Al iniciar un proyecto completamente nuevo y quieres tener la memoria del proyecto lista desde el primer día.
- Al heredar un repositorio existente que aún no tiene un CLAUDE.md.
- Las convenciones del proyecto han cambiado lo suficiente como para que valga la pena regenerar y revisar el CLAUDE.md existente.
- Quieres una primera pasada rápida para documentar la estructura antes de refinarla manualmente.
Ejemplo de Trabajo
Aquí tienes una sesión completa desde un CLAUDE.md vacío hasta uno revisado, en un pequeño proyecto de API Node.js.
# 1. Inicia Claude Code dentro de la raíz del proyecto
cd order-service
claude
# 2. Ejecuta /init dentro de la sesión
/init
# Claude Code escanea package.json, la estructura de carpetas, el contenido
# existente de README, la configuración de pruebas y cualquier archivo de configuración,
# luego escribe un CLAUDE.md de primera pasada en la raíz del proyecto.
# 3. Revisa lo que produjo
cat CLAUDE.mdUn borrador inicial típico de /init se ve algo así:
# Proyecto: order-service
## Descripción general
Una API REST de Node.js para gestionar pedidos de clientes.
## Pila Tecnológica
- Node.js, Express
- PostgreSQL a través de `pg`
- Jest para pruebas
## Estructura
- `src/routes/` - Manejadores de rutas de Express
- `src/services/` - lógica de negocio
- `src/db/` - acceso a la base de datos
- `__tests__/` - archivos de prueba de Jest
## Comandos
- `npm test` - ejecuta la suite de pruebas
- `npm run dev` - inicia el servidor de desarrollo# 4. Edita el borrador para añadir cualquier cosa que /init no pudo inferir,
# como reglas específicas del equipo y restricciones estrictas.## Reglas Estrictas
- Nunca consultes la base de datos directamente desde un manejador de rutas; pasa por `src/services/`.
- Siempre añade una prueba en `__tests__/` para cualquier ruta nueva.
- No hagas commit directamente en `main`.# 5. Haz commit del archivo finalizado
git add CLAUDE.md
git commit -m "Añadir CLAUDE.md vía /init"Lo que esto demuestra:
/initproduce un borrador estructural inicial (pila, carpetas, comandos) a partir de lo que puede observar en el repositorio.- Las reglas específicas del equipo y las restricciones estrictas rara vez son inferibles solo del código; sigues añadiéndolas manualmente.
- El archivo generado está destinado a ser revisado y confirmado como cualquier otro archivo del proyecto, no aceptado ciegamente.
- Ejecutar
/inites lo suficientemente rápido como para repetirlo cada vez que la forma del proyecto haya cambiado significativamente.
Profundización
Cómo Funciona
/initlee los archivos del proyecto (manifiestos de paquetes, estructura de carpetas, documentación existente, configuración) para inferir la pila tecnológica y la disposición.- Escribe el resultado en
CLAUDE.mden la raíz del proyecto, en markdown plano. - Si ya existe un
CLAUDE.md, ejecutar/initde nuevo lo actualiza basándose en el estado actual del proyecto en lugar de crear un archivo duplicado. - El comando no ejecuta pruebas, no instala nada ni modifica código; solo produce documentación.
- Lo que escribe se carga exactamente igual que un
CLAUDE.mdescrito a mano al inicio de cada sesión futura.
Lo que /init Captura Confiablemente vs. Lo que No
| Categoría | Capturado de forma fiable por /init | Normalmente necesita una revisión humana |
|---|---|---|
| Pila Tecnológica | Sí - inferido de manifiestos/configuración | - |
| Estructura de Carpetas | Sí - inferido del árbol de archivos | - |
| Scripts/Comandos Existentes | Sí - desde package.json o similar | - |
| Convenciones del Equipo no visibles en el código | No | Sí - añadir manualmente |
| Reglas estrictas ("nunca hacer X") | No | Sí - añadir manualmente |
| Contexto de Negocio / Términos del Dominio | Parcial, si está documentado en README | A menudo necesita ser añadido |
Volver a Ejecutar /init en un Proyecto Existente
# CLAUDE.md ya existe y está un poco desactualizado
/init
# Claude Code vuelve a escanear el proyecto y actualiza CLAUDE.md
# para reflejar la estructura actual, en lugar de empezar de nuevoTrampas Comunes
- Aceptar el borrador sin leerlo.
/initinfiere lo que puede ver, pero no puede conocer las convenciones del equipo no escritas. Solución: lee siempre el archivo generado de principio a fin antes de confirmarlo. - Perder reglas escritas a mano en una re-ejecución. Volver a ejecutar
/initactualiza el archivo basándose en el estado actual del proyecto, lo que puede mezclarse con ediciones manuales previas si no prestas atención. Solución: compara el archivo después de volver a ejecutar/inity confirma que tus reglas estrictas siguen ahí. - Tratar el borrador como exhaustivo.
/initdocumenta lo que existe, no lo que nunca debería suceder. Solución: añade una sección explícita de "Reglas Estrictas" manualmente para cualquier cosa no negociable. - Ejecutar /init en el directorio incorrecto. Si se ejecuta fuera de la raíz real del proyecto, el escaneo produce una imagen inexacta o vacía del proyecto. Solución: confirma que estás en la raíz del proyecto (
pwd, busca el archivo manifiesto del proyecto) antes de ejecutarlo. - Dejar que el borrador se desactualice. Un CLAUDE.md generado una vez al inicio del proyecto puede desviarse a medida que la base de código evoluciona. Solución: vuelve a ejecutar
/initperiódicamente, o actualiza el archivo manualmente cuando la estructura cambie significativamente.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Escribir CLAUDE.md a mano desde cero | El proyecto es pequeño y ya sabes exactamente qué documentar | Quieres un borrador rápido de hechos estructurales ya visibles en el repositorio |
/init y luego refinamiento manual | Iniciar un proyecto nuevo o heredar uno sin documentar | El proyecto ya tiene un CLAUDE.md completo y preciso |
| Copiar una plantilla de CLAUDE.md de un proyecto similar | Mantienes varios proyectos estructuralmente similares | Cada proyecto tiene una estructura o convenciones significativamente diferentes |
Preguntas Frecuentes
¿Qué hace exactamente /init?
Escanea el proyecto actual (pila tecnológica, estructura de carpetas, documentación existente, archivos de configuración) y escribe un CLAUDE.md de primera pasada documentando lo que encuentra.
¿Necesito un proyecto vacío para ejecutar /init?
No. Funciona en un repositorio nuevo o en uno existente. En un proyecto que ya tiene un CLAUDE.md, ejecutarlo de nuevo actualiza el archivo basándose en el estado actual del proyecto.
¿Sobrescribirá /init mis reglas escritas a mano?
Puede mezclarse con las ediciones manuales al volver a ejecutarse, ya que reescribe basándose en el estado actual del proyecto. Siempre compara el archivo después de una re-ejecución para confirmar que todo lo que añadiste a mano sigue presente.
¿Ejecuta /init pruebas o instala dependencias?
No. Solo inspecciona el proyecto y escribe documentación en CLAUDE.md; no ejecuta pasos de compilación, no instala paquetes ni modifica código.
¿Está el archivo que genera /init listo para hacer commit tal cual?
Trátalo como un primer borrador. Captura de forma fiable hechos estructurales como la pila y la disposición de las carpetas, pero las convenciones del equipo y las reglas estrictas suelen necesitar ser añadidas manualmente antes de que sea realmente útil.
¿Dónde escribe el archivo /init?
En CLAUDE.md en la raíz del proyecto actual.
¿Puedo ejecutar /init en una subcarpeta para obtener un CLAUDE.md anidado?
/init está destinado a la raíz del proyecto. Los archivos CLAUDE.md anidados para carpetas específicas se suelen escribir a mano para las reglas específicas de ese ámbito.
¿Con qué frecuencia debo volver a ejecutar /init?
Cada vez que la estructura del proyecto haya cambiado lo suficiente como para que el CLAUDE.md existente se sienta desactualizado; no hay un horario fijo, es una decisión basada en cuánto ha variado.
¿Qué sucede si ejecuto /init en el directorio incorrecto?
El escaneo refleja cualquier proyecto (o falta de él) que esté realmente en ese directorio, lo que produce un borrador inexacto o casi vacío. Confirma que estás en la raíz del proyecto deseada primero.
¿Sabe /init sobre las convenciones específicas de mi equipo?
Solo lo que es visible en el propio repositorio (patrones de código, documentación existente). Las convenciones del equipo no escritas y las reglas estrictas deben añadirse manualmente después de generar el borrador.
¿Es /init obligatorio antes de que Claude Code pueda trabajar en mi proyecto?
No. Claude Code funciona sin un CLAUDE.md; simplemente comienza cada sesión con menos contexto de pie sobre tus convenciones. /init es una conveniencia para poner ese contexto en marcha rápidamente.
¿Cuál es la forma más rápida de comprobar si el borrador de /init es bueno?
Léelo de principio a fin y pregúntate si refleja con precisión dónde viven las cosas y cómo funciona realmente el proyecto hoy en día, luego añade cualquier cosa que no pudiera inferir, como reglas estrictas.
Relacionado
- Qué Hace Realmente CLAUDE.md - el concepto que /init está arrancando.
- Conceptos Básicos de Gestión de Contexto - dónde encaja /init entre las herramientas principales de la sección.
- Escribir un Archivo CLAUDE.md Que Realmente Se Siga - refinando el borrador que produce /init.
- Archivos CLAUDE.md Anidados y Cómo Funciona la Herencia de Ámbito - añadiendo reglas con ámbito más allá de lo que genera /init en la raíz.
Versiones de la Pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.