Resonant Coding: Guía práctica

Todo lo anterior suena bien en teoría, pero la teoría tiene esa particularidad molesta de disolverse cuando toca la realidad. Así que acá va cómo se materializa esto en el día a día, con la advertencia de que cualquier sistema que pretenda ser definitivo está condenado a fracasar, y este no es la excepción1.

Este documento es una expansión del método de tres pasos —investigación, planificación, implementación— descrito en Resonant Coding, con las estructuras adicionales que fuimos descubriendo que necesitábamos a medida que lo aplicábamos en proyectos reales.

Estructura de carpetas

La primera decisión fue estructural: si el contexto es un balde que se ensucia, entonces hay que tener baldes separados para cada tipo de agua. En la práctica esto se traduce en carpetas con funciones específicas2:

  • research/ para los documentos de investigación, nombrados con fecha para poder rastrear la evolución del entendimiento
  • plans/ para los planes de implementación, también fechados, también versionados
  • specs/ para las especificaciones formales en formato Gherkin3, que funcionan como documentación viva y tests ejecutables al mismo tiempo
  • handoffs/ para los documentos de traspaso entre sesiones, porque el modelo no recuerda nada y alguien tiene que recordar por él

Procedimiento

La segunda decisión fue procedimental: antes de escribir código, escribir un plan. Siempre. Sin excepciones. El plan divide el trabajo en fases que puedan completarse en un tiempo razonable, con criterios de éxito explícitos —automatizados cuando se puede, manuales cuando no queda otra. Cada fase es un balde limpio: el modelo recibe solo el plan de esa fase y la información relevante, nada más. Para tareas con riesgo arquitectónico, a veces usamos tracer bullets4.

Memoria

La tercera decisión fue sobre la memoria. Los modelos no recuerdan, pero los archivos sí. Al final de cada sesión de trabajo —o cuando hay que pasar el contexto a otra persona, o a otro modelo, o a uno mismo del futuro— se genera un documento de handoff que captura el estado actual: qué se hizo, qué se aprendió, qué queda pendiente, qué archivos son relevantes. Es memoria prostética externalizada, y funciona mejor de lo que tiene derecho a funcionar5.

Decisiones de diseño

Para las decisiones de diseño que no son obvias —cuando hay múltiples caminos posibles y elegir uno implica descartar otros— mantenemos una carpeta de debates/ donde se documentan las opciones consideradas, los pros y contras de cada una, y la razón por la que se eligió lo que se eligió. Esto parece burocracia hasta que, seis meses después, alguien pregunta “¿por qué hicieron esto así?” y la respuesta está escrita en vez de perdida en la cabeza de alguien que ya no trabaja acá6.

Flujo típico

El flujo típico termina siendo algo así:

  1. Llega un requerimiento. Antes de tocar código, se crea un documento de investigación. El modelo lee el código existente, la documentación, lo que haya, y genera un resumen del estado actual. Ese resumen pasa por la Regla de los 5 hasta que sea confiable.

  2. Con el documento de investigación como input —y solo ese documento, en una conversación nueva, con el balde limpio—, se genera un plan. El plan divide el trabajo en fases, cada fase tiene criterios de éxito, cada tarea es lo suficientemente pequeña como para caber en un solo balde. El plan también pasa por la Regla de los 5.

  3. Se implementa fase por fase, cada una en su propia conversación, cada una validada antes de pasar a la siguiente. Si algo no funciona, se ajusta el plan, no se improvisa.

  4. Al final de la sesión, se genera el handoff. El próximo que retome el trabajo —sea humano o modelo— tiene todo el contexto que necesita.

Hay una tentación constante de saltarse pasos, de ir directo al código porque “esto es simple” o “ya sé cómo hacerlo”. A veces funciona. Más seguido de lo que me gustaría admitir, no funciona, y el tiempo que ahorraste salteando pasos lo perdés multiplicado arreglando lo que salió mal. El método es más lento al principio y más rápido al final. La pregunta es si tenés la paciencia para llegar al final7.

Notas