Siete horas para un script simple: lecciones reales de control sobre Claude Code

Me senté a leer un libro en español y pensé: "Necesito una herramienta para esto. La monto ahora mismo — nada del otro mundo, un script y un prompt." Acabé tirándome siete horas. Todavía no tengo muy claro adónde se fue el tiempo.

Plan de la sesión

Quería añadir un Módulo de Lectura a mi tutor de idiomas — un módulo que ayudase a desgranar frases de libros. Parecía sencillo: escribir un prompt para el módulo, pulir un poco la metodología y conectar la llamada del subsistema al sistema de control principal del bot. En paralelo, guardar resultados en PostgreSQL para analizarlos después.

Hice una mini-revisión: cogí tres enfoques distintos para explicaciones gramaticales, filtré lo que sobraba y monté una versión final. Es la v1 — cuento con ir refinándola con el tiempo.

Cómo fue en realidad

Siempre le pido al modelo que confirme y narre el plan antes de hacer nada, pero a veces Claude Code me sorprende. Le pedí un subsistema con un solo script — y lo que obtuve fue un sistema de control del bot roto. Claude Code decidió reemplazar el núcleo entero con este mini-módulo. Que resultó no ser tan mini. Después empezó a ejecutar sin mi aprobación, y no llegué a pararlo a tiempo. De repente estoy dando vueltas entre configuraciones de Docker Compose y restaurando sistemas desde cero — unos desde una rama de backup, otros de nuevo. Qué

Momentos destacados

Momento 1. "Pruebas" de que Sonnet 4.5 existe

El glitch más raro en bastante tiempo. Claude Code concluyó de pronto que mi "plan" de API solo permite Haiku y no Sonnet 4.5. Costó muchas iteraciones:

• Convencer al modelo de que los "planes" no existen en ese sentido (Anthropic expone una sola API).
• Quitar el nombre del modelo que estaba hardcodeado en el código.
• Traer "pruebas" de otro proyecto (base de datos de CVs) donde Sonnet funciona.
• Añadir detección automática de modelos disponibles.

Hubo un momento en que estaba literalmente pegando logs de otro servicio: "Mira, aquí tienes una petición exitosa a claude-sonnet-4-5-20250929." Después volví a comprobarlo — y todo funcionaba. Sigo sin saber qué pasó "en la cabeza de la IA," pero fue una lección sobre el valor de los proof-of-concepts en sistemas reales.

Momento 2. El prompting como control de calidad

No tengo "prompts mágicos que siempre funcionan." Lo que sí tengo es un control estricto cada vez:

• "Explícame con tus palabras qué has entendido de la tarea."
• "¿Qué archivos vas a modificar y por qué?"
• "Repite el plan de acción antes de ejecutar."

Hoy me ayudó mucho usar Claude desktop en paralelo para partes aisladas. Por ejemplo, le pedí a Opus que evaluase la calidad de las explicaciones pedagógicas — me dio recomendaciones que luego implementé a través de Claude Code.

Cambiar de modelo con criterio funciona mejor que intentar "exprimir todo" de uno solo:

• Haiku — para tareas rápidas
• Sonnet — para desarrollo
• Opus — para revisión crítica

Frases del día que funcionaron

Cuando la base de datos no guardaba nada

Esta formulación empujó a la IA a mirar el problema de forma sistémica en vez de ir parcheando agujeros.

Para actualizar documentación

La palabra "quirúrgicamente" marcó el tono adecuado: ediciones precisas en vez de reescribir el documento entero.

Sin esto ya no puedo vivir — y tú tampoco deberías

Los desarrolladores profesionales hacen esto de forma automática, pero para mí fue un "ajá" genuino: crear ramas de backup después de cada hito relevante.

Conclusiones

• Las pruebas reales ganan a los argumentos. Cuando la IA insistía en que el modelo no estaba disponible, solo los logs de otro proyecto ayudaron.
• Las ramas de backup te salvan la vida. Crea ramas de backup en GitHub después de cada hito importante. El V0.5.5-reading-SQL de hoy es un punto de restauración seguro si las cosas se tuercen.
• El control gana a los "prompts mágicos." Haz que la IA reformule la tarea con sus palabras antes de ejecutar — los malentendidos salen a la superficie pronto.
• El modo multi-modelo es más potente. La combinación Haiku → Sonnet → Opus da mejores resultados que depender de un solo modelo.