Enseñarle a la IA a pensar como un ingeniero senior

• Una metodología que hace que las herramientas de código con IA planifiquen antes de escribir código puede prevenir implementaciones incorrectas y acelerar el desarrollo
• Se aplican 8 estrategias de planificación según el nivel de dificultad, y cada estrategia sigue una estructura en la que agentes específicos investigan en paralelo y luego el desarrollador ejerce juicio y toma decisiones
• Cada estrategia incluye reproducción de bugs, búsqueda de mejores prácticas, análisis de la base de código, investigación del historial de git, entre otros, y las preferencias y patrones que aprende el agente se acumulan automáticamente
• El sistema, publicado como open source, puede instalarse en Claude Code o iniciarse desde una sola función para ir enseñándole gradualmente a la IA la forma de pensar del desarrollador

---

Desarrollo centrado en planificación con IA

• Se presenta un enfoque que hace que la IA elabore un plan antes de escribir código
  • Este método, más que simplemente escribir código, acelera la implementación de funcionalidades y reduce errores
• Como ejemplo, se presenta el proceso de desarrollo de la función “email bankruptcy” de la app de gestión de correo Cora
  • Al implementar una función para ordenar 53,000 correos sin perder mensajes importantes, un agente de investigación con IA realizó un análisis previo
  • Detectó de antemano el límite de 2,000 elementos de Gmail, timeouts del sistema y problemas de espera del usuario, evitando una implementación incorrecta

8 estrategias de planificación

Estrategia 1: reproducir y documentar bugs

• Objetivo: reproducir el bug antes de corregirlo y generar una guía paso a paso
• Cuándo usarla: Fidelity 1~2, especialmente al corregir bugs
• Justo después del lanzamiento de la función de email bankruptcy, surgió un problema en el que 19 usuarios quedaron atrapados en un estado de fallo de la tarea
  • Tras revisar los logs de AppSignal, se diagnosticó que los errores de rate limit de Gmail se estaban ignorando en producción
  • Si fallaba un lote, se detenía toda la tarea, pero como no se notificaba al usuario, este solo veía un spinner de carga infinito
• Durante la reproducción se descubrió la necesidad de procesamiento por lotes y reanudación de tareas, confirmando que un simple reintento no era suficiente
• Efecto compuesto: se agregó a la checklist del agente @kieran-rails-reviewer el punto “al hacer trabajos en background que llaman APIs externas, verificar manejo de rate limiting, reintentos y estados parciales abandonados”

Estrategia 2: investigar mejores prácticas

• Objetivo: buscar en la web casos similares de resolución de problemas
• Cuándo usarla: en todos los niveles de dificultad, especialmente con patrones poco familiares
• Al actualizar un gem que estaba dos versiones atrasado, el agente buscó “ruta de actualización de versión X a Y”, “breaking changes entre versiones” y “problemas comunes de migración”
  • Encontró la guía oficial de actualización y 3 posts de blog de ingenieros que hicieron la misma actualización
  • 3 minutos de investigación evitaron horas de debugging por prueba y error
• También sirve para decisiones no técnicas: “mejores prácticas para tiers de precios SaaS”, “copy de conversión para campañas de email drip”, “estrategias de reintento para trabajos en background”, etc.
• Efecto compuesto: cuando se detecta un patrón útil, se guarda automáticamente en archivos docs/*.md, y ante una pregunta similar la próxima vez se revisa eso antes de buscar en la web

Estrategia 3: investigar la base de código

• Objetivo: buscar patrones similares en el código existente
• Cuándo usarla: en cualquier trabajo donde pueda haber funcionalidad ya existente o duplicada
• Antes de agregar event tracking a una nueva función, el agente buscó en la base de código: “¿cómo se maneja hoy el event tracking?”, “¿cuáles son los patrones de llamadas analíticas?”, “¿dónde se envían los eventos?”
  • Encontró un sistema de tracking ya existente, incluso con métodos helper (que el propio autor había olvidado)
  • Si la IA no consulta la base de código, intenta reconstruir todo desde cero
• En vez de crear un nuevo sistema de tracking, se resolvió extendiendo el patrón existente, evitando construir un segundo sistema incompatible
• Efecto compuesto: se creó el agente “@event-tracking-expert”, que se ejecuta automáticamente al planificar cualquier funcionalidad que requiera tracking

Estrategia 4: investigar el código fuente de librerías

• Objetivo: leer directamente el código fuente de paquetes y gems instalados
• Cuándo usarla: al usar librerías que cambian rápido o tienen poca documentación
• El gem RubyLLM agrega constantemente nuevos modelos, parámetros y funciones, pero la documentación se queda atrás
  • El agente analizó el código fuente de RubyLLM: “¿qué opciones de modelo están disponibles?”, “¿qué parámetros se pueden pasar?”, “¿qué funciones no documentadas existen en la versión más reciente?”
  • Entregó hallazgos como “la versión 1.9 agregó soporte para streaming, pero no está documentado”, junto con nombres de parámetros y ejemplos tomados del test suite
• Efecto compuesto: cada vez que se actualizan dependencias, también se actualiza automáticamente el conocimiento, evitando trabajar con información obsoleta

Estrategia 5: estudiar el historial de git

• Objetivo: entender la intención detrás de decisiones pasadas analizando el historial de commits
• Cuándo usarla: en refactors, al retomar trabajo previo o cuando se necesita entender el “por qué”
• Al detectar que se estaba usando una versión antigua de EmailClassifier, antes de intentar actualizarlo se revisó el historial de git: “¿por qué seguimos en v1?”, “¿ya intentamos actualizar a v2?”
  • Se encontró un PR de otro integrante del equipo de hace 3 meses: al actualizar a v2, correos de la bandeja de entrada terminaban archivados y correos archivados volvían a la bandeja
  • En la discusión del PR había un registro de que se revirtió intencionalmente, con razones detalladas
• Efecto compuesto: la memoria institucional se preserva y se vuelve buscable, permitiendo que los nuevos integrantes hereden la lógica de decisiones pasadas

Estrategia 6: aclarar requisitos con prototipado

• Objetivo: aclarar requisitos mediante prototipado rápido en un entorno separado
• Cuándo usarla: Fidelity 3, incertidumbre de UX, trabajo exploratorio
• Al rediseñar la interfaz de Brief para email, se crearon en Claude 5 prototipos de layout distintos, 5 minutos cada uno
  • Se probaron manualmente para detectar puntos incómodos y luego se mostró la mejor versión a algunos usuarios
  • Comentario de un usuario: “el layout abruma y no sé cómo archivar un correo”
• Ese insight se incorporó como requisito del plan real: “el botón de archivar debe ir en la esquina superior izquierda; la memoria muscular del usuario espera esa ubicación por Gmail”
• Efecto compuesto: el prototipado convierte la incertidumbre en especificaciones concretas y documenta reacciones de usuarios

Estrategia 7: sintetizar con opciones

• Objetivo: integrar toda la investigación en un solo plan con trade-offs incluidos
• Cuándo usarla: al terminar la etapa de investigación, antes de implementar
• Después de ejecutar las estrategias 1~6, el agente sintetiza: “con base en esta investigación, propone 3 formas de resolver el problema. Incluye complejidad de implementación, impacto en rendimiento, costo de mantenimiento y patrones existentes con los que encaja cada enfoque”
• Ejemplo de sincronización de inbox de Gmail:
  • Opción A—usar el sistema de sincronización existente: implementación rápida, pero duplica código y dificulta la separación de responsabilidades
  • Opción B—sincronización en tiempo real: arquitectura limpia, pero puede ser lenta y presentar problemas de confiabilidad
  • Opción C—construir un sistema de caché espejo: la mejor solución de largo plazo, con la separación más limpia, pero con la mayor carga inicial de trabajo
• Tras comparar, se puede tomar una decisión informada en 30 segundos
• Efecto compuesto: las elecciones revelan preferencias; si se marca una preferencia por “compatibilidad primero”, el sistema le dará más peso a la compatibilidad en decisiones similares futuras

Estrategia 8: revisión con agentes de estilo

• Objetivo: pasar el plan terminado a revisores especializados para comprobar preferencias del desarrollador
• Cuándo usarla: etapa final del plan, antes de implementar
• Se ejecutan automáticamente 3 agentes de revisión:
  • Agente de simplificación: marca sobreingeniería, “¿de verdad esta función necesita 3 tablas de base de datos? ¿No bastaría con 1 tabla con un campo de tipo?”
  • Agente de seguridad: revisa vulnerabilidades comunes, “este plan permite entrada de usuario directamente en una consulta a la base de datos; hay que agregar sanitización de entrada”
  • Agente de estilo Kieran: aplica preferencias personales, “se están usando joins complejos; Kieran prefiere queries simples, considerar desnormalización”
• Efecto compuesto: con el tiempo, los agentes acumulan los gustos del desarrollador; si se marca “esto no me gusta” o “buen hallazgo”, el sistema aprende

Cómo empezar

Qué puedes probar hoy mismo

• El sistema de planificación fue publicado como open source en Github Marketplace de Every
• Al instalarlo en Claude Code, puedes usar de inmediato el comando slash /plan y los agentes de investigación
• El plugin puede usarse en Claude Code o en Droid

Una forma simple de comenzar

• Elige una funcionalidad Fidelity 2 que estés construyendo esta semana: una tarea con alcance claro y que abarque varios archivos (agregar una nueva vista, implementar un sistema de feedback, refactorizar un componente)
• Antes de pedirle a Claude Code o Cursor que la construyan, dedica 15 a 20 minutos de investigación:
  1. Mejores prácticas: ¿cómo lo resolvieron otras personas? Busca en la web posts de blog, Stack Overflow y documentación
  2. Tus propios patrones: ¿cómo lo resolviste tú antes? Busca funcionalidades similares en tu base de código actual
  3. Capacidades de librerías: ¿qué soportan realmente las herramientas que usas? Usa IA para leer documentación o código fuente
• Haz que la IA sintetice la investigación en un plan que incluya:
  1. El problema a resolver (una sola oración clara)
  2. 2 o 3 enfoques de solución (con pros y contras honestos de cada uno)
  3. Patrones de código existentes con los que debe coincidir
  4. Edge cases o consideraciones de seguridad
• Revisa el plan y observa tu reacción: si piensas “esto es demasiado complejo” o “ya existe una forma mejor”, no te limites a corregir el plan; captura y registra por qué piensas eso
• Lanza la funcionalidad con base en el plan y compara la implementación final con el plan original: ¿en qué se desvió?, ¿por qué?, ¿qué habría mejorado el plan?
• Invierte 10 minutos en formalizar un aprendizaje: agrégalo al archivo CLAUDE.md y escribe una regla como “al hacer trabajo de tipo X, recuerda revisar Y” o “por la razón C, se prefiere el enfoque A sobre B”
• Cuando se acumulen aprendizajes, crea agentes o comandos de investigación especializados: “Event Tracking Expert” (conoce tus patrones), “Security Checker” (marca errores comunes)
• Repite la próxima semana, consulta tus notas, verifica si el segundo plan es mejor que el primero y, después de algunos meses, construye un sistema que conozca la forma de pensar del desarrollador