Claude Code Club · Cuaderno de estudio
Etapa 7 — Agents
💥 Las 4 formas en que se rompen los agentes de principiante (y su fix)
Lo que te llevarás: una chuleta de diagnóstico — la primera vez que tu agente se porte mal sabrás exactamente cuál de las cuatro es y cómo arreglarla en un movimiento, no en una espiral de debug de dos horas. Léela una vez, hazle captura, guárdala.
1 · Deriva de alma — «no suena a mí»
Síntoma: salida genérica, formal, con pinta de IA; usa palabras que tú jamás
dirías.
Causa: el SOUL es corto, vago o sin muestras reales de tu voz. «Escribe con mi voz» no le dice nada.
Fix: reescribe el SOUL con 4-6 frases de reglas de voz reales y pega 2 de tus posts pasados como referencia — «escribe como suenan los ejemplos: mismo ritmo, misma longitud de frase».
Causa: el SOUL es corto, vago o sin muestras reales de tu voz. «Escribe con mi voz» no le dice nada.
Fix: reescribe el SOUL con 4-6 frases de reglas de voz reales y pega 2 de tus posts pasados como referencia — «escribe como suenan los ejemplos: mismo ritmo, misma longitud de frase».
2 · Alcance desbordado — «hizo demasiado»
Síntoma: le pediste triar emails y también archivó 40 «para ayudar»; le
pediste redactar y también publicó.
Causa: las KEYS le dieron herramientas que no necesitaba, y el JOB no decía qué NO hacer.
Fix: reduce las herramientas al mínimo y añade una línea «NO HAGAS» al JOB («Solo borradores. No envíes, archives, etiquetes, muevas ni borres nada»). Los agentes siguen las restricciones que escribes; las que solo pensaste no cuentan. Si es importante, va en el archivo.
Causa: las KEYS le dieron herramientas que no necesitaba, y el JOB no decía qué NO hacer.
Fix: reduce las herramientas al mínimo y añade una línea «NO HAGAS» al JOB («Solo borradores. No envíes, archives, etiquetes, muevas ni borres nada»). Los agentes siguen las restricciones que escribes; las que solo pensaste no cuentan. Si es importante, va en el archivo.
3 · Divagar — «corrió 20 minutos y produjo papilla»
Síntoma: sigue pensando, mirando más archivos, dudando; quema tokens; salida
final vaga y con rodeos cuando querías un borrador.
Causa: sin condición de parada, o una vaga («cuando esté bien»).
Fix: condición de parada medible («cuando existan 3 archivos en /drafts/[fecha]/ y me hayas impreso un resumen de 3 líneas — para y espera»). Bonus: un presupuesto («si esto lleva más de 5 llamadas a herramientas, pausa y pregúntame»).
Causa: sin condición de parada, o una vaga («cuando esté bien»).
Fix: condición de parada medible («cuando existan 3 archivos en /drafts/[fecha]/ y me hayas impreso un resumen de 3 líneas — para y espera»). Bonus: un presupuesto («si esto lleva más de 5 llamadas a herramientas, pausa y pregúntame»).
4 · Fallo silencioso — «dijo hecho y no pasó nada»
Síntoma: el agente proclama éxito; miras la carpeta y no hay nada (o hay
archivos truncados).
Causa: un hook bloqueó una acción a mitad y no lo avisó fuerte, o no tiene permiso de escritura en esa ruta, o escribió en una ruta sutilmente distinta («/drafts/» vs «/Drafts/»).
Fix: contrasta siempre el informe final contra la carpeta real: haz tú el
Causa: un hook bloqueó una acción a mitad y no lo avisó fuerte, o no tiene permiso de escritura en esa ruta, o escribió en una ruta sutilmente distinta («/drafts/» vs «/Drafts/»).
Fix: contrasta siempre el informe final contra la carpeta real: haz tú el
ls; si está vacía, mira el log de hooks y los permisos en KEYS. Dos minutos de
verificación ahorran una semana de progreso fantasma. Y añade a la parada: «antes de imprimir el
resumen, verifica con ls que cada archivo existe e incluye sus tamaños».5 · (Bonus) Sangrado de contexto — el tono cambia a mitad
Síntoma: empieza profesional y acaba bromista, o al revés.
Causa: el orquestador reenvió demasiado historial de chat a un subagente, que heredó el rollo equivocado.
Fix: brifea a los subagentes solo con el input que necesitan — nunca la transcripción entera. Un párrafo entra, un párrafo sale.
Causa: el orquestador reenvió demasiado historial de chat a un subagente, que heredó el rollo equivocado.
Fix: brifea a los subagentes solo con el input que necesitan — nunca la transcripción entera. Un párrafo entra, un párrafo sale.
🧠 La meta-lección: cuatro de las cinco roturas son problemas del archivo, no del prompt. Cada arreglo al archivo dura para siempre; cada arreglo al prompt se evapora al cerrar la sesión. El instinto a memorizar: cuando un agente te sorprenda, abre primero su .md, y el chat después.
Fuente: Claude Code Club · Aula · Etapa 7 «Agents» — lección «Las 4 formas en que se rompen los agentes de principiante».
Añadido al cuaderno: 7 de julio de 2026. Traducción al español para estudio personal.
Añadido al cuaderno: 7 de julio de 2026. Traducción al español para estudio personal.