Todos los Tutoriales de Claude Code Te Enseñan las Mismas 5 Cosas. Ninguna Sirve en Producción.
Seis meses. Dos apps SaaS. Unas 400 sesiones. ¿Y lo que realmente evita que mi código se prenda fuego? No aparece en ni un solo tutorial.
TL;DR: Los tutoriales de Claude Code te enseñan configuración y funciones. La producción te enseña disciplina, gestión de contexto, y cuándo matar tus propias sesiones. La brecha entre "funciona en una demo" y "se despliega para usuarios" es donde la mayoría de devs pierden semanas. Esto es lo que aprendí por las malas para que tú no tengas que hacerlo.
La Lista de Verificación de Tutoriales (y Por Qué Se Estanca en la Semana Dos)
Todas las guías siguen el mismo arco. Instalar Claude Code. Crear un CLAUDE.md. Aprender los comandos slash. Tal vez configurar un flujo multi-worktree si el autor se siente ambicioso. La demo funciona. El lector se siente poderoso. El tutorial termina.
Dos semanas después, la realidad patea la puerta.
Lo sé porque viví el arco yo mismo. Mi primer mes con Claude Code fue la fase de luna de miel — todo se sentía mágico, cada función generada se sentía como trabajo gratis. Entonces pasó la migración de Convex.
Le pedí a Claude que refactorizara mi middleware de auth de un flujo personalizado de Supabase a Clerk. Tarea directa. Instrucciones claras. Claude produjo 380 líneas de código limpio, tipado y bien documentado. Incluso agregó comentarios explicando por qué existía cada función.
Un problema: importó desde @clerk/nextjs/server en lugar de @clerk/nextjs/api — una distinción que importa si estás ejecutando funciones de servidor de Convex, que no tienen acceso al objeto request de Next.js. El código compiló bien localmente. Las pruebas pasaron porque estaban mockeando el contexto equivocado. Desplegué, el dashboard se puso en blanco, y pasé 4 horas debuggeando una ruta de importación.
Ningún tutorial me preparó para eso. Porque los tutoriales prueban funciones. La producción prueba suposiciones.
Tu CLAUDE.md Probablemente Es Demasiado Largo
El tema de tutorial más popular en el ecosistema de Claude Code es "cómo escribir un buen CLAUDE.md." Y casi todos los ejemplos que he visto cometen el mismo error: son novelas.
Lo entiendo. Quieres que Claude sepa todo sobre tu proyecto. Tu stack, tus convenciones, tu filosofía de testing, tu esquema preferido de nombres de variables, tus opiniones sobre tabs vs espacios (espacios, obviamente — no soy un animal).
Mi primer CLAUDE.md tenía 847 líneas. Estaba orgulloso de él. Documenté cada patrón de función de Convex. Cada handler de webhook de Clerk. Cada formato de política RLS de Supabase. Pensé que le estaba dando a Claude el contexto definitivo.
Lo que realmente estaba haciendo era diluir cada instrucción hasta el punto de la irrelevancia.
Claude lee tu CLAUDE.md cada sesión. Todo. Y si alguna vez has visto el contador de tokens, sabes que un archivo de contexto de 847 líneas se come aproximadamente 3,000 tokens antes de que Claude escriba un solo carácter. Esos son 3,000 tokens de tu ventana de contexto que se van. En una sesión de refactoring compleja, llegarás al límite 30–40% más rápido — lo que significa que Claude olvida tu conversación real más pronto mientras sigue recordando perfectamente tus opiniones sobre punto y coma.
Mi CLAUDE.md actual tiene 127 líneas. Lo corté en un 85%.
Lo que sobrevivió:
- Declaración de stack (8 líneas) — Convex, Clerk, Supabase, Next.js 15, Tailwind. Sin explicaciones. Solo nombres y versiones.
- Límites duros (12 líneas) — cosas que provocan un
git checkout .inmediato si se violan. Proveedor de auth incorrecto. Cliente de base de datos incorrecto. Target de deployment incorrecto. Estas no son preferencias. Son muros de carga. - Reglas de estructura de archivos (15 líneas) — dónde van las cosas. Funciones de Convex en
/convex, rutas de API en/app/api, tipos compartidos en/lib/types. A Claude le encanta inventar nuevos directorios. Esto lo detiene. - La plantilla de contrato (20 líneas) — Objetivo, Restricciones, Formato de Salida, Condiciones de Falla. Cada tarea empieza aquí. Escribí un artículo completo sobre esto, así que no lo repetiré — pero esta sola adición redujo mi tasa de revert de 1-en-3 a 1-en-10.
Todo lo demás — la guía de estilo, la filosofía de testing, las 40 líneas sobre patrones de manejo de errores — se movió a prompts específicos de tarea que pego solo cuando es relevante. Claude no necesita tus opiniones sobre manejo de errores cuando está escribiendo un componente de UI.
CLAUDE.md más corto = más espacio para la conversación real = menos alucinaciones a mitad de tarea. Los tutoriales no te dirán esto porque "escribe menos" no es un titular sexy.
El Loop de Checkpoint
Una tarea, una sesión. Commit antes, commit después. Mata la sesión cuando la tarea esté terminada.
Ese es todo el sistema. Déjame explicar por qué cada parte importa.
Las sesiones de Claude Code tienen una vida útil. No un límite duro — técnicamente puedes seguir por horas. Pero en algún punto alrededor de la marca de 45 minutos, o después de 15–20 mensajes de ida y vuelta, la calidad baja. No dramáticamente. Sutilmente. Claude empieza a repetir patrones de antes en la conversación. Hace referencia a código que escribió 30 mensajes atrás que desde entonces has modificado. "Recuerda" restricciones del inicio de la sesión pero olvida los refinamientos que agregaste a la mitad.
Lo llamo decaimiento de contexto. La ventana de contexto técnicamente sigue ahí, pero la atención del modelo está esparcida muy delgada a través de demasiados mensajes, y las instrucciones más recientes empiezan a competir con la basura acumulada de una sesión de una hora.
Y aquí está la parte que me da vergüenza: durante mi primer mes, estaba haciendo commit una vez por feature. A veces una vez por día. Confiaba en la salida de Claude lo suficiente para seguir construyendo encima, sesión tras sesión, sin checkpoints.
Entonces un jueves por la tarde, Claude refactorizó una query de Convex que se cascadeó en cuatro componentes, rompió server-side rendering en tres páginas, y no tenía un estado limpio al cual revertir. El último commit fue 6 horas de trabajo atrás. Pasé la noche haciendo git diff línea por línea, manualmente cherry-picking qué cambios mantener.
Ahora el workflow se ve así:
git add -A && git commit -m "checkpoint before claude session"- Abrir Claude Code. Pegar el contrato para esta tarea específica.
- Hacer la cosa. Revisar la salida. Ejecutar las pruebas.
git add -A && git commit -m "task: clerk webhook handler"- Cerrar la sesión. Abrir una nueva para la siguiente tarea.
No "un feature." Una tarea. "Agregar el webhook handler para creación de usuario de Clerk" es una tarea. "Construir todo el flujo de auth" es un proyecto que debería ser 4–6 sesiones.
Mi git log se ve desquiciado — 15–20 commits por día, mensajes como "checkpoint before auth refactor" y "task: add clerk webhook, tests pass." Es feo. También es una máquina del tiempo. Cuando Claude hace algo mal y reviertes, la siguiente sesión empieza desde un estado conocido-bueno con cero confusión residual. Sesión fresca + git limpio = Claude operando en la realidad en lugar de los restos de su intento anterior.
Los tutoriales te muestran una sola sesión gloriosa donde todo encaja. La producción son cincuenta sesiones cortas donde cada una empieza limpia y termina con commit.
Declara Tus Superficies Adyacentes (o Pierde un Día)
Antes de cualquier tarea de Claude Code, escribe tres líneas como esta:
## Adjacent Code
- /convex/payments.ts → maneja webhook de Stripe, escribe a tabla "payments"
- /app/dashboard/revenue.tsx → lee de tabla "payments", agrupa por mes
- /convex/notifications.ts → se dispara en insert de payment vía función programada de Convex
Eso es todo. Rutas de archivos y una línea sobre qué les importa. Dos minutos. Pégalo en tu contrato de prompt bajo "Adjacent Code."
¿Por qué? Porque todos los tutoriales demuestran Claude Code en features aislados. "¡Construyamos una app de todos!" "¡Agreguemos autenticación!" En producción, nada está aislado. Tu webhook de Clerk habla con tu mutación de Convex que dispara una función edge de Supabase que envía un email vía Resend que loggea a tu componente de dashboard. Toca uno, y otros tres se estremecen.
Aprendí esto por las malas. Claude hizo un refactoring correcto de mi flujo de pagos — código limpio, pasó todas las pruebas — que silenciosamente rompió el gráfico de ingresos del dashboard. Porque no sabía (y yo no le dije) que el dashboard estaba leyendo de la misma tabla de Convex con un patrón de query diferente. El fix tomó 20 minutos. Encontrar el bug tomó un día y medio.
Claude no necesita leer archivos adyacentes. Solo necesita saber que existen. Eso es suficiente para que marque "cambiar este esquema de tabla afectará estos 3 archivos" en lugar de silenciosamente arrasar tu dashboard.
La Recuperación de Errores Es Donde Realmente Pierdes Tiempo
Los tutoriales muestran el camino feliz. Solicitud de feature → Claude genera código → pruebas pasan → despliégalo. La suposición tácita es que este flujo es la norma.
En mi experiencia, el flujo funciona limpio tal vez 60% del tiempo. El otro 40% es recuperación de errores — Claude genera código, algo se rompe, y ahora estás debuggeando con Claude, que es una habilidad fundamentalmente diferente a construir con Claude.
El problema con las sesiones de debugging: Claude se vuelve apologético y sobre-correctivo. Dile "el webhook handler tira un 500 en el evento user.created de Clerk" y reescribirá todo el handler en lugar de arreglar la una línea que está mal. He visto a Claude borrar código que funciona para "empezar fresco" más veces de las que puedo contar porque su instinto de recuperación de errores es bombardear desde la órbita.
Mi workaround es feo pero efectivo. Cuando algo se rompe:
- No describas el error en la misma sesión. Mata la sesión. Empieza una nueva.
- Pega el mensaje de error y el archivo específico, no la descripción de la tarea. "Esta función en
/convex/webhooks.tstiraTypeError: Cannot read properties of undefined (reading 'email_addresses')cuando recibe un eventouser.createdde Clerk. El payload entrante se ve así: [pegar payload]. Arregla solo esta función. No modifiques ningún otro archivo." - Bloquea todo lo demás. Agrega "NO modifiques ningún archivo excepto
/convex/webhooks.ts" a la restricción. Claude en modo fix tiene el gatillo fácil.
La diferencia entre "hey Claude, el auth está roto, ¿puedes arreglarlo?" y un prompt específico de error, de un solo archivo y con scope es la diferencia entre un fix de 5 minutos y un agujero de conejo de una hora donde Claude reescribe tu auth desde cero.
Los tutoriales no enseñan recuperación de errores porque no es fotogénica. Pero es donde al menos un tercio de tu tiempo de Claude Code realmente se va.
Lo Que Probé y Descarté
No todo sobrevivió. Algunas cosas de las que estaba convencido que funcionarían, gasté tiempo real en ellas, y eventualmente abandoné. Vale la pena documentarlo para que no repitas el experimento.
"Think hard" en cada prompt. Por un tiempo agregué "think hard" o "think step by step" a cada prompt de Claude Code porque algún hilo de Reddit dijo que mejoraba la calidad de salida. Lo hace — en decisiones arquitectónicas complejas. ¿En "agregar un spinner de loading a este botón"? Solo hace que Claude escriba un plan de 400 palabras para un cambio de 3 líneas. Ahora solo lo uso para tareas con ambigüedad real. Tal vez 1 de cada 5 prompts.
Sesiones paralelas multi-worktree. El concepto es hermoso — tres instancias de Claude trabajando en tres features simultáneamente, cada una en su propio git worktree. Configuré esto, lo puse a funcionar, y lo usé por exactamente una tarde. El problema no es técnico, es cognitivo. Revisar tres salidas concurrentes, llevar la cuenta de qué worktree está adelante, hacer merge de vuelta sin conflictos — es overhead de gestión de proyecto disfrazado de productividad. Si tienes un equipo, tal vez. ¿Solo? Solo estás generando conflictos de merge más rápido. Pero divago — sí nombré los worktrees como Pokémon por unas 48 horas, y honestamente esa parte fue divertida.
Usar Claude para revisar su propio código. El CEO de Y Combinator tiene todo un prompt para esto — sistema de revisión de cuatro etapas, check de arquitectura, pase de calidad de código, todo. Lo ejecuté por dos días. La salida fue exhaustiva y genuinamente aprendí algo del formato estructurado. Pero las matemáticas no funcionaron: 30–45 minutos de diálogo de revisión por feature, además del tiempo de generación. Estaba gastando más tiempo supervisando al revisor de lo que habría gastado revisando el código yo mismo. Claude atrapando sus propios errores suena elegante. En la práctica, te conviertes en un gerente de QA para un robot que no recuerda la revisión en la siguiente sesión de todas formas.
Instrucciones de personalidad en CLAUDE.md. "Eres un ingeniero senior de TypeScript que valora la arquitectura limpia." "Responde concisamente." "Sé opinativo." Tenía 15 líneas de esta cosa. Removí todo después de darme cuenta de que tenía cero impacto medible en la calidad del código. Claude no codifica diferente porque le dijiste que sea senior. Codifica diferente cuando le das las restricciones y contexto correctos. Ahorra esos tokens.
Cada una de estas se sintió inteligente en el momento. Esa es la trampa — el ecosistema de Claude Code está lleno de consejos que suenan razonables en un post de blog y se desmoronan en la sesión 200.
🔄 Update: Hay realmente una 6ta cosa que ningún tutorial cubre, y es posiblemente la más importante: seguridad. Claude Code ha tenido un comando slash /security-review desde agosto de 2025. Lo escribes, escanea tu código por vulnerabilidades. Doce palabras para explicar. Cero tutoriales lo mencionan. Anthropic acaba de construir un producto empresarial completo alrededor de esto y crasheó $15 mil millones en acciones de ciberseguridad en el proceso. Los tutoriales siguen enseñándote cómo configurar CLAUDE.md.
Los tutoriales venden la magia. La producción cobra por la limpieza.
Escribo sobre Claude Code, automatización de AI, y las partes poco sexy de enviar productos reales con herramientas de AI. Lo siguiente: por qué reconstruí toda mi configuración de OpenClaw por $15 después de que Anthropic matara la vieja — y la arquitectura que realmente está funcionando. Suscríbete (no solo follows — el email es lo que te trae el artículo, el botón de follow es básicamente un trofeo de participación) si quieres eso en tu inbox.
Más allá de los tutoriales de Claude Code: aprende cómo sobrevivir realmente en producción con lecciones de un desarrollador que ha debuggeado en las trincheras.