Tu Proyecto de Claude Code No Está Configurado. Solo Parece Que Lo Está.
Las buenas instrucciones a Claude Code marcan la diferencia entre una app que funciona y un desastre lleno de bugs que nadie quiere debuggear. El nuevo flujo de onboarding de proyectos simplificó mucho ese trabajo, básicamente una entrevista. Extrae lo que no es obvio, configura hooks y skills, hace las preguntas que te olvidarías de responder. Pero aún necesitas saber qué pasa cuando encuentra tu CLAUDE.md ya existente.
Y lo que pasa no es lo que la mayoría de posts han descrito.
TLDR: /init no es un generador mejorado. En un repo con un CLAUDE.md existente, cambia a modo auditoría: lee tu archivo, cruza referencias con lockfiles y configs, y saca a la luz lo que dejó de coincidir mientras el código avanzaba. En el 4º repo, 64 líneas, encontró 5 mentiras silenciosas. La diferencia entre generar y corregir es todo el artículo.
En un repo nuevo, sí, genera. La comunidad corrió con eso, razonablemente. "Setup 10x más fácil," el CLAUDE.md se escribe solo ahora. Cierto para una pizarra en blanco. Pero el caso más común es un repo que ya tiene documentación, escrita temprano, antes de que el codebase se convirtiera en lo que realmente es. En el momento que /init detecta un archivo existente, no reemplaza: audita. Cruza referencias del CLAUDE.md contra lockfiles, configs, schemas, y saca a la luz lo que ya no coincide. Ese es el trabajo.
Lo corrí en 4 repos durante unos días.
Esperaba un Generador. Obtuve un Auditor.
Thariq del equipo de Claude Code posteó el flag de env var en marzo: CLAUDE_CODE_NEW_INIT=1, modo preview, flujo de setup basado en entrevista. Un hilo en r/ClaudeAI de la misma semana tenía 118 comentarios sobre una pregunta que se quedó: "Sean honestos: cuando Claude escribe un plan largo, ¿realmente lo leen? ¿O solo dicen que se ve bien?" El doc que nadie relee ya era un punto de dolor vivo en la comunidad.
Puse el flag y corrí /init en los 4 repos.
Lo que esperaba en cada uno: un CLAUDE.md con una sección de stack, un bloque de comandos, algunas convenciones. Boilerplate que limpiaría manualmente. El tipo de output que te da un punto de partida y necesita una pasada humana para ser realmente útil.
Lo que obtuve en cambio: en 3 de los 4 repos, /init detectó un archivo existente e inmediatamente cambió de comportamiento. En un repo en blanco genera desde cero. Con un archivo ya presente, el enfoque es diferente. Lee el CLAUDE.md actual, lee el codebase, encuentra los huecos donde lo que escribiste ya no coincide con lo que el código realmente es.
Documentation drift no se anuncia. No es como un error de build o un test que falla. Es más como corrupción en un archivo de guardado: el juego sigue corriendo, los números se ven bien, y luego llega la pelea del boss y las stats no suman lo que se prometió. Para cuando te das cuenta, has estado jugando con suposiciones incorrectas por un rato.
Los docs de Claude Code describen el nuevo /init como siguiendo el principio de "solo incluir lo que Claude no inferiría por sí mismo". En un repo existente eso significa: primero determinar qué es realmente el código, luego comparar eso con lo que está documentado, luego sacar a la luz el delta. El delta es lo que importa.
2 Repos Que Ya Se Conocían
Repo 1 era mi dashboard principal de producto: el proyecto central, CLAUDE.md de unas 150 líneas, escrito temprano y actualizado ocasionalmente. /init devolvió 11 líneas nuevas.
Las adiciones eran hechos arquitectónicos que no estaban en el archivo: la entidad de datos central alrededor de la cual gira todo el sistema, una regla de routing que canaliza toda la lógica helper a un módulo específico, auth de 2 niveles (end-user vs machine-to-machine), una tarea programada aislada que corre fuera del ciclo normal de requests. Nada documentado. Todo inferible del código si lees profundamente y cruzas referencias de los imports.
Luego marcó 1 mentira. El CLAUDE.md referenciaba npm install y localhost:3000. bun.lock estaba en el root. El proyecto había estado corriendo en un puerto diferente por meses. Ambos habían sido ciertos en algún momento, ambos habían dejado silenciosamente de ser ciertos, y nada se había roto. Los comandos npm aún se ejecutan en un proyecto bun, mayormente. El puerto incorrecto solo significa que pruebas la URL incorrecta una vez, luego la correcta, y te olvidas. Fácil de pasar por alto. Fácil de dejar.
Repo 2 era un problema diferente. Un proyecto con cerca de 700 líneas de CLAUDE.md cuidadosamente mantenido, actualizado después de cada cambio significativo. /init leyó todo, escaneó el codebase, volvió con 3 líneas. El runner bun test había sido agregado recientemente y no estaba documentado. No rewrite, no cambios estructurales, solo los comandos faltantes.
Y un veredicto: "Tu CLAUDE.md ya está muy por encima de lo que /init generaría aquí."
(Mantengo un doc interno de 500 líneas en un proyecto completamente separado, nada que ver con esto, que he estado actualizando por 2 años porque encuentro la escritura clarificadora. Mi hija entró una vez mientras reescribía un header de sección y preguntó por qué estaba escribiendo un libro sobre mi código. No tuve una buena respuesta. En fin.)
Una herramienta que sabe cuándo parar es tan rara como una que sabe cuándo empezar.
El Repo Sin Mapa
El 3er repo: un sistema de entrega de catálogo multi-frontend. Múltiples frontends Astro, un backend Hono, SQLite, sin CLAUDE.md, sin README en el root. Empezado rápidamente porque la forma era clara, documentación era para después, y después siguió moviéndose.
/init devolvió un mapa arquitectónico completo en 4 pasadas paralelas de herramientas. Las lecturas independientes salen simultáneamente: config root, rutas Hono, configs Astro, scripts de build, notas de deploy. La reconstrucción es rápida porque las llamadas no esperan unas a otras.
El mismo principio aplica aquí como en cómo Claude Code construye contexto de proyecto desde un codebase existente: un mapa estructurado y preciso es casi siempre el trabajo que hace que las sesiones subsecuentes dejen de irse por las ramas. El mapa existe y es correcto, o el modelo improvisa, e improvisar sobre la imagen incorrecta se compone rápidamente.
La invariante clave que sacó a la luz que yo no habría escrito: Astro corre bajo Node, todo lo demás bajo Bun. Ese detalle estaba enterrado en un comentario en el script de deploy y una llamada fnm use 22 en el script de build. Una restricción arquitectónica específica de cómo funciona el proceso de build de Astro, completamente indocumentada. Cada sesión de Claude Code en este repo había estado operando sin ella.
Lo que las 4 pasadas ensamblaron concretamente: el schema SQLite, un pipeline de export serializando contenido a bundles JSON por sitio, la secuencia de build Astro bajo Node 22 (no Bun, porque el renderer SSG de Astro lo requería), un paso rsync a nginx con reglas de rewrite ya definidas, y un Cloudflare Worker manejando routing edge frente a todo. La cadena completa de entrega desde filas SQLite crudas hasta archivos estáticos renderizados detrás de Cloudflare, documentada en una pasada. Sin árbol de directorios, sin consejos genéricos de proyecto. Lo suficientemente específico para navegar sin preguntar.
5 Mentiras en 64 Líneas
El 4º repo: mi pipeline de procesamiento de producto. Full stack, backend Convex, frontend Vite/Express, secrets manejados a través de Infisical. El CLAUDE.md tenía 64 líneas, escrito 3 meses antes, preciso en su momento.
/init encontró 5 lugares donde la documentación se había vuelto silenciosamente ficción.
1. El package manager
El CLAUDE.md instruía: npm install, npm run dev. bun.lock estaba en el root. La migración a bun había pasado en algún punto y los docs no habían seguido. Claude Code había estado corriendo comandos npm en un proyecto bun, silenciosamente, sin error, porque la mayoría de comandos npm aún se ejecutan. La incompatibilidad se esconde hasta que la resolución de dependencias diverge y pasas una tarde averiguando por qué.
2. Los estados de workflow faltantes
El CLAUDE.md documentaba 3 códigos de status de orden en el schema Convex: draft, published, archived. El schema real tenía 7. Los 4 faltantes manejaban casos edge: processing, failed, review, scheduled. Los estados que importan para cualquier operación no trivial. Cada sesión de Claude Code había estado escribiendo lógica contra un modelo del sistema que tenía 4 estados de menos.
3. La carpeta Convex
El CLAUDE.md describía convex/ como la capa principal de procesamiento. Eso había sido cierto temprano. Durante 3 meses, el trabajo pesado había migrado a server.js: generación PDF para hojas de producto, redimensionado de imágenes, dispatch de webhook a integraciones partner. Las funciones Convex se volvieron routing delgado. El procesamiento real pasaba en un archivo que los docs habían dejado de mencionar.
4. El switch de modo indocumentado
Un shell script en el root alternaba el stack entre Convex Cloud manejado y una instancia Convex self-hosted dependiendo del target de deployment. Cero mención en el CLAUDE.md. Cada sesión de Claude Code había estado asumiendo una conexión backend estática, cuando había un paso de switch manual con consecuencias reales para dónde aterrizaba la data.
5. El puerto que toma 3 archivos encontrar
El CLAUDE.md decía que el dev server corre en puerto 3150. El puerto real: 3002. Vite proxeaba a Express en 3002, PORT era inyectado por Infisical, vite.config.ts era el puente entre los 3. Para encontrar el puerto real, necesitabas cruzar referencias de 3 archivos. /init hizo esa referencia cruzada. Yo no. Por 3 meses.
Nadie mintió deliberadamente. El CLAUDE.md había sido preciso. El código se había movido como el código siempre se mueve: no en rewrites dramáticos sino en 10 decisiones por semana, cada una demasiado pequeña para sentir que garantizaba una actualización de doc. Después de 3 meses, 5 de esas decisiones habían derivado más allá de lo que estaba escrito.
Interludio: el árbol git sucio
Este repo tenía estado uncommitted. Un package-lock.json eliminado, un archivo backup sin track sentado en el root. /init no saltó el repo, no forzó el árbol, no escribió sobre el directorio de trabajo.
Corrió 5 pasos git en secuencia: creó un worktree en una rama dedicada, hizo edits en aislamiento, committeó con un mensaje de commit convencional, hizo fast-forward merge a main, luego limpió el worktree y eliminó la rama. WIP intocado, historial git limpio.
La razón por la que esto funcionó limpiamente: git hooks versionados que fuerzan este workflow. El modelo no eligió precaución. Operó dentro de restricciones de proyecto que no podía bypasear. Esa es una garantía diferente que confiar en la buena voluntad del modelo, y vale la pena entender la diferencia entre buena voluntad del modelo y disciplina real de tooling antes de decidir cuánta confianza poner en cualquiera.
Lo Que /init No Puede Hacer
/init audita lo que es trazable. Archivos que puede leer, configs que puede cruzar referencias, schemas que puede comparar contra documentación. Esa es una capacidad real, subestimada porque el output se ve simple. Solo la mentira del puerto me ahorró una sesión de debugging que no quería tener.
Pero hay una categoría de conocimiento que no puede tocar.
El git hook que forzó el workflow de worktree existe porque, meses antes de que /init existiera, estuve cerca de borrar una sesión de trabajo viva al dejar que un run de Claude Code committeara directamente a main en un árbol sucio. El hook fue el fix que codeé esa tarde. Está documentado en su propio código pero no en ningún CLAUDE.md. /init vio el hook y lo referenció correctamente, pero no pudo decirme por qué la secuencia importaba, o qué pasaría si alguien lo eliminara asumiendo que era limpieza boilerplate, o qué había costado la tarde que lo produjo en trabajo perdido.
Ese conocimiento vive en el incidente. Las reglas de proyecto más valiosas tienden a venir de algo que se rompió, no de un escaneo de archivo o una entrevista de onboarding. Puedes documentar el qué pero no la historia del por qué, y el por qué es usualmente la parte que evita que el error se repita. /init es una herramienta de auditoría, no una retrospectiva. Encuentra mentiras presentes, no lecciones pasadas, y conocer esa diferencia es la mayor parte de la razón para confiar en lo que saca a la luz.
Creo que la otra mitad de hacer /init útil es llevar tu documentación a un estado que valga la pena auditar en primer lugar. Si estás temprano en un proyecto, la brecha entre "lo que pretendo que sea este codebase" y "lo que Claude Code realmente necesita documentado" es el trabajo que Vibe Coding, For Real mapea, específicamente la distinción entre documentación de intención y documentación de implementación. /init solo es útil en implementación. La intención aún es tuya para escribir.
Lanza /init esta noche en tu repo más viejo. No para obtener un CLAUDE.md limpio. Para averiguar cuántas líneas ya están mintiendo. 😬
Fuentes
- Thariq (@trq212), equipo Claude Code: post X anunciando CLAUDE_CODE_NEW_INIT=1, marzo 2026
- Claude Code Docs, changelog Semana 16 (13-17 abril, 2026)
- r/ClaudeAI, datos comunidad GummySearch, junio 2026
- wmedia.es: "/init en Claude Code: mucho más que un template CLAUDE.md," abril 2026
Este post puede contener enlaces de afiliado. Si los clickeas, podría ganar una pequeña comisión (no te cuesta nada, y me ayuda a seguir enviando artículos de calidad todos los días para tu placer de lectura).