Cómo evité que Claude repitiera mis errores.

Transcript

1. CLAUDE COMMUNITY · GUADALAJARA · 29 AGO 2026 Cómo evité que Claude repitiera mis errores Ocho horas en el día de Dani, sus dolores y cómo se arreglan. Franchesco Romero 01 / 32 · Wizeline
2. QUIEN ESTÁ EN ESTA HISTORIA Dani no es principiante. Ese es justo el problema. Tres años programando, ocho meses en esta startup. Producto en producción, con clientes. Sin QA. Usa Claude Code a diario desde hace cuatro meses. Ya pasó la fase del wow. Ahora quiere que le rinda más. 02 / 32 ACTO 1 · LA PERSONA
3. 8h ACTO UNO Un lunes cualquiera Nada de lo que va a pasar hoy es un desastre. Todo es normal. Ese es el punto. 03 / 32 ACTO 1 · LA PERSONA
4. EL DÍA COMPLETO, DE UN VISTAZO 09:10 10:40 12:15 15:30 17:00 21:14 Pega el contexto. Corrige lo mismo. Media hora perdida Acepta algo que no Deploy. Tests en Producción caída. Otra vez. Cuarta vez. por la contraseña. sabe evaluar. verde. Cuatro cosas pequeñas y una caída. Las cuatro primeras son la causa de la última. 04 / 32 ACTO 1 · LA PERSONA
5. 09:10 Lo primero que hace Dani no es programar: es pegar tres párrafos explicando el proyecto. SESIÓN NUEVA Los tiene en una nota. Los pega cada mañana. DOLOR 1 05 / 32 El costo de arranque ACTO 1 · LA PERSONA
6. 10:40 Claude escribe un alert(). Aquí los avisos van con toasts, siempre. Dani lo corrige. CODE REVIEW Cuarta vez este mes. Ninguna corrección sobrevivió a la sesión. DOLOR 2 06 / 32 Las correcciones no se acumulan ACTO 1 · LA PERSONA
7. 12:15 Media hora buscando por qué fallan los tests. Era la contraseña: no es la del .env/README. TESTS EN ROJO Claude no podía saberlo: no está escrita en ningún archivo del repo. DOLOR 3 07 / 32 Las mismas fallas, cada vez ACTO 1 · LA PERSONA
8. 15:30 Claude propone una migración que borra una columna. Dani duda dos segundos y la acepta. LA MIGRACIÓN No es flojera: el modelo ha tenido razón todo el día. DOLOR 4 08 / 32 Ninguna red debajo del juicio ACTO 1 · LA PERSONA
9. 21:14 · EL COSTO 78s de errores 500 en el panel de administración. cloudwatch · 21:14 UndefinedColumnError: column listings.public_visibility does not exist GET /api/v1/admin/marketplace 500 · 500 · 500 · 500 · 500 ... El deploy cambia las tareas de una en una. La migración corrió primero. Durante 78 segundos el código viejo pidió una columna que ya no existía. 09 / 32 ACTO 1 · LA PERSONA
10. Dani le pidió que revisara la migración. Nadie le dijo nunca cómo se despliega este proyecto. 10 / 32 ACTO 1 · LA PERSONA
11. LO QUE DANI NECESITA DE VERDAD DOLOR 1 Pegar el contexto cada mañana → Que viva en el repo, no en una nota DOLOR 2 Corregir lo mismo cuatro veces → Que una corrección valga para siempre DOLOR 3 Caer en la misma trampa → Que cada error quede archivado DOLOR 4 Ser el único filtro → Que lo crítico no dependa de su juicio Ninguna se resuelve escribiendo un prompt más largo. 11 / 32 ACTO 1 · LA PERSONA
12. LA IDEA Usar bien Claude Code no es escribir mejores prompts. Es montar el contexto para no tener que repetirlos. Un prompt muere con la sesión. Lo que queda escrito en el repo, no. 12 / 32 ACTO 2 · LA IDEA
13. TRES CAPAS, CADA UNA PARA UN DOLOR 1 CLAUDE.md 2 Memoria 3 Hooks Lo que no puede deducir leyendo el repo. Un archivo por error, con el porqué. Lo que no se le puede confiar al modelo. dolores 1 y 3 siempre presente dolores 2 y 3 presente si aplica dolor 4 no es negociable Ordenadas por qué tan seguro es que se apliquen. 13 / 32 ACTO 2 · LA IDEA
14. 1 CAPA UNO · DOLORES 1 Y 3 CLAUDE.md Para que Dani deje de pegar párrafos y para que la contraseña de la base de pruebas se escriba una sola vez. 14 / 32 ACTO 3 · LA TÉCNICA
15. CÓMO DECIDIR QUÉ ESCRIBIR Si el modelo lo puede deducir leyendo el repo, sobra. Los tres párrafos que Dani pega cada mañana fallan esta prueba casi completos. 15 / 32 ACTO 3 · LA TÉCNICA
16. CÓMO HACERLO MEJOR SOBRA · LO DEDUCE SOLO SIRVE · NO ESTÁ EN NINGÚN LADO ## Base de datos ## Base de datos Usamos PostgreSQL con Nunca edites el esquema a SQLAlchemy. mano, siempre Alembic. Los modelos viven en `models/`. Los tests necesitan un Usamos Alembic para Postgres real. La clave no migraciones. es la del README: sácala del gestor de secretos. La derecha le ahorra a Dani los treinta minutos de las 12:15. 16 / 32 ACTO 3 · LA TÉCNICA
17. LAS CUATRO CATEGORÍAS QUE SÍ GANAN SU LUGAR 01 · TRAMPAS 02 · CONVENCIONES 03 · COMANDOS 04 · PROHIBICIONES Parece que funciona Sin rastro en el y no código No están en el manifiesto Rompen producción La contraseña que no El alert() de las 10:40. Cómo se corren de Lo que va siempre de es la del README. verdad los tests. una forma. Las cuatro salieron de perder tiempo, no de documentar. 17 / 32 ACTO 3 · LA TÉCNICA
18. CÓMO HACERLO MEJOR · EL ERROR QUE CASI TODOS COMETEN Un CLAUDE.md de 600 líneas rinde peor que uno de 100. No son datos que se acumulan. Son Líneas de CLAUDE.md, proyecto real por revisión · medido con git log 250 200 150 reglas que compiten por atención. 100 ↑ la poda, 5 abr: 249 → 129 Estructura de carpetas 50 Lista de dependencias Qué hace cada endpoint 0 24 mar 31 mar 1 abr 3 abr 5 abr 15 may 30 may 23 jul 16 ago Podarlo 18 / 32 ACTO 3 · LA TÉCNICA
19. 2 CAPA DOS · DOLORES 2 Y 3 Memoria Para que la corrección de las 10:40 sea la última, y para que el error de las 21:14 no vuelva nunca. 19 / 32 ACTO 3 · LA TÉCNICA
20. CÓMO SE VE UNA MEMORIA BIEN ESCRITA FEEDBACK · MIGRACIONES Expand/contract, nunca DROP de un jalón Qué pasa: un DROP viaja en el mismo deploy que el código que deja de usar la columna, pero el backend cambia sus tareas de una en una. Por qué: el rollout deja código viejo y nuevo sirviendo a la vez. Pasó el 21/07: 78 segundos de 500. Cómo aplicarlo: lo aditivo va en un paso. Lo destructivo en dos deploys: primero dejas de usar la columna, después la borras. Qué pasa, por qué pasa, qué hacer. Sin la tercera es una queja. 20 / 32 ACTO 3 · LA TÉCNICA
21. CÓMO HACERLO MEJOR · LA PARTE QUE TODOS SE SALTAN Sin el porqué, la regla se aplica donde no toca. Regla sin porqué Regla con porqué "No hagas DROP COLUMN "No hagas DROP COLUMN en migraciones." en un solo deploy porque el rollout solapa dos versiones del código." Nunca borra una columna. Ni donde no Sabe dónde no aplica, y que un RENAME es aplica. La regla se vuelve superstición y te un DROP disfrazado. Generaliza a casos estorba. que tú no escribiste. 21 / 32 ACTO 3 · LA TÉCNICA
22. LA CAPA QUE DEBE CRECER 84 memorias en cinco meses. Memorias acumuladas mar a ago 2026 · fecha de creación 90 80 70 60 50 Esta es la capa que debe crecer. 40 Cada archivo es algo que sí se 30 rompió. El salto de julio es el mes en que dejé 20 10 0 mar abr may jun jul ago de solo arreglar y empecé a archivar. 22 / 32 ACTO 3 · LA TÉCNICA
23. El error de las 10:40, archivado 23 / 32 ACTO 3 · LA TÉCNICA
24. 3 CAPA TRES · DOLOR 4 Hooks Para que a las 15:30, cansada y sin nadie con quien contrastar, Dani no sea el único filtro. 24 / 32 ACTO 3 · LA TÉCNICA
25. Cuándo dejar de pedirlo y empezar a exigirlo SI LA REGLA... VA EN PORQUE Es preferencia de estilo CLAUDE.md Que falle de vez en cuando no daña Vino de un error concreto Memoria Necesita el porqué y cuándo aplica Se descubre semanas después Hook Nadie va a revisar. Se acumula Cuesta dinero o producción Hook El fallo ocasional ya no es aceptable 25 / 32 ACTO 3 · LA TÉCNICA
26. CÓMO HACERLO MEJOR · UN HOOK QUE SOBREVIVE .githooks/pre-commit Seis meses en CLAUDE.md, cumpliéndose casi siempre. "Casi siempre" fueron tres features de retraso. El mensaje dice cómo saltarlo USER_VISIBLE_PATHS=( '^backend/app/api/v1/admin/' '^frontend/src/pages/admin/' ) # tocó algo visible pero no la guía? if ! echo "$STAGED" | grep -qx \ 'docs/guia-equipo.md'; then La lista de rutas es conservadora ✗ commit bloqueado También hay hooks de Claude Code # y le dice cómo saltarlo: # git commit --no-verify fi 26 / 32 ACTO 3 · LA TÉCNICA
27. El hook diciendo que no 27 / 32 ACTO 3 · LA TÉCNICA
28. DE BOLSILLO · SI SOBRA TIEMPO Un subagente cuesta más tokens, no menos. LO QUE SE CREE LO QUE PASA "Delego a un subagente y ahorro." Paga su propio prompt de sistema, su CLAUDE.md y sus esquemas. Su resumen te llega como entrada. Lo que ahorras es ventana de contexto principal, que es otro recurso. 28 / 32 ACTO 3 · LA TÉCNICA
29. EL MISMO MARTES · AZUL CLAUDE.MD · ROJO MEMORIA · VERDE HOOK 09:10 Pega tres párrafos Escribe la primera instrucción 10:40 Corrige el alert() No aparece. Se archivó 12:15 Media hora con la contraseña Los tests pasan a la primera 15:30 Acepta sin poder evaluar Claude explica el expand/contract 17:00 Deploy con los dedos cruzados El hook la detiene. 2 min más 21:14 Producción caída, 78s de 500 Está cenando 29 / 32 ACTO 4 · EL CIERRE
30. HONESTIDAD · TRES COSAS QUE PROBÉ Y SALIERON MAL INTENTO 1 Un hook sin escape Sin escape documentado, estorba a la primera y alguien lo desinstala. 30 / 32 INTENTO 2 Guardar memoria de todo Los errores de dedo no son propiedades del sistema. INTENTO 3 CLAUDE.md como onboarding Escribirlo para quien llega nuevo es lo que lo infla. El modelo no llega nuevo: llega leyendo. ACTO 4 · EL CIERRE
31. QUÉ HACER EL LUNES · UNA HORA EN TOTAL 1 Abre tu CLAUDE.md y pregúntale qué sobra. "¿Qué puedes deducir leyendo el repo?" Borra eso. 2 Lo próximo que se rompa, archívalo de inmediato. Antes de arreglarlo. Con el porqué. 3 Elige una regla y conviértela en hook. La que te duela si falla. Con su escape. 31 / 32 ACTO 4 · EL CIERRE
32. GRACIAS El modelo no se acuerda. Tu repositorio sí. CLAUDE.md Franchesco Romero 32 / 32 Memoria · Hooks Claude Community MX ACTO 4 · EL CIERRE