El sistema que uso para no quedarme afuera de mi propio proyecto

Realmente es bastante sencillo caer en la tentación de escribir en la consola de Claude, OpenCode o cualquier otro asistente de código, "crea un formulario que registre un cliente con los campos: a, b y c y muéstrame en un dashboard la cantidad de registros por fecha y otros datos relevantes", más que nada para los desarrolladores que en su momento empezamos a utilizar las herramientas de IA para agilizar el trabajo, ¿ya intentaste hacer algo así?

El resultado es hasta cierto punto impresionante la primera vez, pero como me paso a mí, estoy seguro de que no tardaste (o si estas iniciando, no tardaras) en darte cuenta que ese tipo de instrucciones no son sostenibles en un sistema profesional. Los sistemas se vuelven una caja negra enseguida.

Pasado ese impulso inicial del uso de los agentes de IA, la forma con la que me siento cómodo trabajando (de momento, esto puede cambiar en el tiempo), es delegando la escritura de código mas no la arquitectura, para ser específicos, el tener el mapa mental de los componentes que se utilizar en el sistema y como interactúan entre ellos es de vital importancia para no perder el control, es decir, que entra en el componente o controlador, que resultado da, como procesa la información y por qué la procesa de esa manera.

De esta manera te mantienes en los controles de mando, tomando decisiones conscientes y no simplemente siendo un espectador a la espera que el agente de IA haga lo que quiera con tu sistema y que llegue al fin que le pediste (si se lo describiste bien) a cualquier costo, esto te da la seguridad de entender y dar instrucciones precisas a los agentes, consiguiendo resultados puntuales y de la manera esperada, siendo eficiente en el uso de los recursos (tokens) y poder intervenir manualmente en cualquier momento de ser necesario.

Programando con agentes de IA

Cuando escuche por primera vez el termino Vibe Coding, me causo hasta cierto punto algo de fricción, y esto ya lo he escuchado de algunos desarrolladores también, el "yo no hago vibe coding", lo cierto es que en alguna medida todos lo hemos hecho en algún punto, para acotar a que me refiero, todos le hemos dicho al agente de IA, "Quiero que esta función haga esto en específico" o "necesito este resultado" ya sea en el flujo de trabajo o nada más por probar, y por más especifica que sea la solicitud, es en cierta medida vibe coding… Luego surgen otros términos o categorías que profesionalizan más esta manera de programar como el Spec Driven Development, que en resumen y de manera escueta es una especie de vibe coding más detallado (es por el cual yo me inclino).

Mi objetivo con lo anterior es expresar que se puede delegar una buena parte del trabajo de codificación sin que esto se vuelva una caja negra para los desarrolladores, sin importar como le llames a la metodología que utilizas para interactuar con el agente de IA, no se debe perder la capacidad de entender, explicar, modificar, testear y los términos que quieras… dentro de nuestro código.

¿Ahora, como lo hago? ¿Como mantengo el control?

Te voy a detallar que es específicamente con lo que actualmente he encontrado un punto de equilibrio entre productividad y control. Y este es un sistema basado en planes.

En el cual, como primer punto, escribo las generalidades y arquitectura del sistema, todo esto queda en un archivo que puede llamarse AGENTS.md o CLAUDE.md según el agente que estes usando.

Ojo, este es un archivo extenso, que debe tener el mayor nivel de detalle posible, puedes revisar uno de mis archivos en GitHub https://github.com/adrianVegaT/content-tracking/blob/main/CLAUDE.md, para tomarlo de referencia, ese archivo combina las instrucciones de Laravel Boost y mis instrucciones personales.

Este archivo debe contener al menos las siguientes partes:

1. Descripción del sistema
2. Objetivos Generales y específicos del sistema
3. Casos de uso
4. Diagrama ER (entidad - relación)
5. Tecnologías a utilizar
6. Arquitectura
7. Boceto del árbol de archivos

Pero si aun tienes algunas dudas sobre las decisiones técnicas o los casos de uso, una de las grandes ventajas de la IA es que puedes rebotar ideas e ir aclarando el camino a seguir si en alguno de los puntos te sientes estancado, lo importante es que definas estos puntos antes de empezar a codificar.

¿Por qué es importante esta sección?

Porque con esto sientas las bases para que el agente trabaje de una cierta manera, en el tono que tú quieres, manteniendo la estructura que tú has determinado y evitas que se ponga a crear archivos que difieren unos de otros (al menos en estilo de programación) entre sesiones.

Con esas bases puestas, la estructura de planes tiene mucho más sentido. Este archivo se escribe una vez al inicio y se actualiza solo cuando hay decisiones arquitectónicas mayores.

Sistema de planes

Con las bases y generalidades establecidas, paso al desarrollo de las funcionalidades específicas. Para ello utilizo la siguiente estructura.

Dentro de una carpeta llamada docs, creo archivos .md con las funcionalidades generales que voy a implementar, como por ejemplo: Gestión de posts.

Esta es la funcionalidad general que quiero implementar, pero dentro de esta existen diversas actividades que se deben realizar, esta lo correspondiente al CRUD como tal, pero también está la implementación gráfica, el testing, los detalles de seguridad, etc.

Entonces, este archivo md especifico de la función, va estructurado con las siguientes secciones:

1. Nombre del plan
2. Contexto
3. Arquitectura
4. Fases
5. Decisiones tomadas

Donde el punto 4 es el más importante, porque es donde se detallan las tareas atómicas a realizar, vamos a un ejemplo para que quede más claro:

La funcionalidad de Gestión de posts, puede tener distintas fases, como lo pueden ser:

Fase 1: Establecer la conexión con la base de datos

Fase 2: Creación de los formularios de creación y edición de posts

Fase 3: Lógica y funcionalidad de archivado de posts

Fase 4: Dashboard de rendimiento de posts

Y cada una de estas fases debe tener tareas específicas para concluir con éxito la implementación de cada fase. Tomemos de ejemplo la fase 1: Establecer la conexión con la base de datos.

Esta fase puede estar dividida en tareas atómicas como las siguientes:

• [ ] Tarea1: Crear controlador con las 7 funciones correspondientes a un crud: index, show, create, store, edit, update, delete.
• [ ] Tarea 2: Crear las rutas adecuadas para el funcionamiento del crud, cuidando los detalles de seguridad, poniendo especial atención en las políticas de visualización de datos por usuario, prevención de inyeccion sql, protección contra ataques dos y ddos a través de los formularios y / o rutas.
• [ ] Tarea 3: Crear la pantalla de index
• [ ] Tarea 4: Crear la pantalla de show

Y así sucesivamente hasta que tengas todas las especificaciones que necesites en tu funcionalidad. La primera objeción que encontré respecto a esto y que seguramente ya estarás pensando en ello es, "pero esto es demasiado verboso", "es mucho escribir", "mejor lo programo directamente". Y si, tienes razón en cierta medida, es bastante verboso, pero tiene también sus ventajas. Como primera ventaja yo resaltaría que:

1. Al tener ese nivel de detalle el mapa mental que te creas del sistema es prácticamente integro a nivel lógico, por lo que sabes donde esta cada cosa al punto de poder intervenirlo manualmente de ser necesario.
2. Este tipo de planes te permiten moverte de manera fluida en lenguajes que aún no dominas del todo, o por lo menos no de manera tan fluida como para igualar la velocidad con la que escribes en lenguaje natural al escribir las especificaciones.
3. El registro que llevas en los planes es un base muy solida para la documentación.
4. Y por último y probablemente uno de los puntos más importantes, te permite gestionar la memoria del agente de IA entre sesiones o evitar que tus conversaciones lleguen al punto de compactarse y pierdas contexto valioso para tu desarrollo, lo cual es uno de los problemas más engorrosos en la actualidad, a su vez también te permite utilizar distintos modelos entre sesiones sin perder calidad en la generación de código.

¿Puedo hacer “Vibe Coding” sin sentirme culpable?

En esta sección quiero hacer más que nada una aclaratoria, y es que, hay un caso en específico en el que realmente no importa si el sistema se vuelve una caja negra y no entiendes del todo como está procesando la información, y es en los MVPs.

Cuando tienes que sacar algo rápido para que el usuario se haga una idea visual sobre el producto es de mucha utilidad la velocidad con la que puedes sacar un producto vibecodeandolo, y si, acá estamos obviando temas de seguridad, estructura, control, buenas prácticas, etc. Y las estamos cambiando por velocidad, pero esa velocidad es la que en muchas ocasiones nos permite obtener retroalimentación de un producto sin dedicarle todo el tiempo que requeriría si seguimos un flujo de desarrollo completo, por supuesto, el mvp no es algo que vayas a colocar en producción tal cual, repito, esto nos sirve para testear y obtener retroalimentación del usuario lo más rápido posible.

Esa es la única manera en la que al menos yo me permito esa situación y cambio control por velocidad.

Conclusión

Si tuviese que resumir este post en una frase seria "delega la escritura, no la arquitectura", partiendo de la base que la inteligencia artificial es un multiplicador, por lo que si desde el principio le entregas orden y tus solicitudes son sobre ese orden ya implantado, el resultado será apegado a tu idea original manteniendo tú el control sobre cómo se construyó tu proyecto, en cambio, si le das rienda suelta a la IA y que esta tome decisiones esperando que lea tu mente, el resultado muy rara vez será el esperado en su totalidad, y no porque la IA sea mala ni mucho menos, es más un tema de contexto y conocimiento del negocio, cosas que aun necesitan la mayor parte del trabajo humano.

Esta es una entre tantas metodologías que surgen en busca de sacar el mayor provecho posible a las capacidades que la inteligencia artificial ofrece dentro de nuestros proyectos manteniéndonos al mando de esto.

Así que dime, ¿cómo controlas el desarrollo de tus proyectos con IA, que metodologías usas o has probado?