- Al usar Claude Code por primera vez, se lo abordó simplemente con un método de iterar entre instrucciones en prompts y correcciones, pero en tareas complejas surgieron problemas de dependencia del historial de conversación y límites de contexto
- Para resolverlo, antes de implementar una función se le hace redactar un documento de plan (plan document), que se convierte en la única fuente de verdad (SSOT) en una sesión nueva
- El documento de plan incluye una reformulación de requisitos, detalles de implementación, comandos para verificar la calidad del código y más, y sigue actualizándose durante la implementación como un documento vivo (living document)
- Esto resuelve el problema de pérdida de contexto y permite continuar el proyecto en sesiones nuevas usando solo un documento único
- Como resultado, la IA deja de ser una simple herramienta de ejecución y pasa a cumplir el rol de socio de diseño colaborativo que impulsa al desarrollador a pensar y documentar mejor el diseño
El problema: los límites de un enfoque basado solo en conversación
- Al trabajar de forma conversacional con Claude Code, sirve bien para tareas simples, pero a medida que las tareas complejas crecen aparecen varias limitaciones importantes
- La conversación se vuelve la única fuente de verdad, por lo que un mensaje nuevo puede sobrescribir fácilmente instrucciones anteriores, y es difícil detectar con claridad cuándo ocurre eso
- Debido al límite del tamaño de contexto de la IA, cuanto más larga se vuelve la conversación, más probable es que se pierda información anterior
- Aunque Claude Code tiene una función de compresión de conversaciones, eso no elimina por completo esta limitación
Experimento con un enfoque centrado en documentos de plan
- Para resolver estos problemas, se probó un enfoque basado en documentos de plan
- Al inicio, se le explica a Claude Code con el mayor detalle posible la función que se quiere implementar o el bug que se debe corregir
- También se mencionan archivos fuente existentes o documentos de plan previos que puedan servir de referencia
- Se evita dar instrucciones de implementación excesivamente específicas para fomentar el papel de la IA como generadora de propuestas de diseño
- Cuando el documento de plan resulta suficientemente satisfactorio, se borra el historial de conversación y se vuelve a empezar usando solo ese plan como contexto
- El plan incluye un resumen de la función, el plan de implementación, código y pseudocódigo, y comandos de tipos/lint/tests
Proceso de diseño colaborativo
- Cuando no convence el diseño propuesto por la IA, se le da retroalimentación concreta para guiar una aproximación revisada
- En el proceso de discusión, a veces se descubre que la primera propuesta de la IA era más adecuada, y eso resulta más eficiente que programar basándose solo en un diseño propio
- Una conversación estructurada ofrece una experiencia parecida a discutir un plan con otro desarrollador
- La IA no suele presentar por sí sola un enfoque completamente distinto, pero si se le pregunta puede proponer alternativas diferentes
Enfoque de documento vivo (Living Document)
- El documento de plan no se escribe una sola vez y se da por terminado, sino que se sigue actualizando incluso durante la implementación de la función
- Los cambios que aparecen durante la implementación, la verificación de tipos, el lint o las pruebas se reflejan en tiempo real
- Se forma el hábito de pedir una revisión del estado más reciente del plan cada vez que se hace un commit
- Como el plan se mantiene siempre actualizado, en una sesión nueva basta con adjuntarlo para continuar sin pérdida de contexto
Revisión de código y cambios en los hábitos de desarrollo
- Una vez iniciada la implementación, se revisan periódicamente los cambios y, si el resultado es satisfactorio, se tiende a confiar más en el trabajo de la IA
- Al revisar el código final, el documento de plan actualizado ayuda a entender la base de las decisiones técnicas
- La experiencia de planificar con cuidado y documentarlo de antemano permite crecer como mejor desarrollador
- Como hay que explicárselo a la IA, uno termina organizando con mayor claridad su propio proceso de toma de decisiones
Del caos al sistema
- Este método hace que el documento de plan se convierta en la única fuente de verdad, resuelve la pérdida de contexto y fomenta el pensamiento arquitectónico
- El documento de plan incluye tanto la especificación como el registro de implementación, y deja constancia no solo del “qué”, sino también del “por qué” y el “cómo”
- El resultado final es un proceso de desarrollo planificado, bien documentado y confiable
- La IA se consolida no como un simple implementador, sino como un socio de diseño colaborativo
Aún no hay comentarios.