En el artículo anterior hablábamos de modelos mentales a la hora de usar LLMs para escribir código, y de cómo mantener el foco en este tipo de escenarios. Hoy veremos un punto de vista diferente, y es el de usar LLMs para entender código existente y acelerar nuestro onboarding en un proyecto.

LLMs para entender

Hace muchos años un buen amigo me decía que visitar un psicólogo solamente es útil cuando tienes un área concreta en la que quieres trabajar, en vez de esperar a que «te arregle». Esta reflexión la puedes aplicar a cualquier tipo de apoyo, coaching, o, como no puede ser de otra manera, al trabajo con LLMs.

Esto significa que, cuando preparamos un prompt de investigación, mientras más claro tengamos qué buscamos, mejor será la respuesta que tengamos del prompt.

Entendiendo el hoy

Veamos un ejemplo práctico. Llevo usando WordPress desde hace más de 15 años, al principio como usuario del sistema open-source y desde hace unos años como usuario del servicio WordPress.com, así que me pareció interesante usarlo como banco de pruebas para aprender más sobre él.

Para este ejercicio, empezamos por descargar la copia del repositorio de WordPress que está disponible en github, y preparar un prompt como el del ejemplo para el área de WordPress en la que estamos interesados (el sistema de instalación).

Una vez definida el área, necesitamos definir las preguntas a las que estamos buscando respuesta, y un lugar donde empezar para que el LLM no se pierda en el repositorio.

Además del texto, los LLMs pueden generar gráficos, y para ello podemos directamente usar Mermaid, ya que los gráficos se generan en formato de texto y se muestra de manera visual.

Finalmente, queremos ser explícitos con la narrativa, queremos que sea corta y concisa, porque los LLMs son muy verbosos a la hora de explicar un tema.

I want to learn about how WordPress installation works, specifically:

- When does the installation gets triggered (i.e. what is checked before redirecting the user to the installer).

- What permissions are checked

- What data is created in the database

- What flags (if any) are modified at repository level (i.e, does a file permission change?)

## References  

You should start looking at wp-admin/install.php and go down that path

## Outcome

I want to update this document (with additional sections) in a way that helps me answer those questions, with a short narrative on the installation process, as well as two Mermaid diagrams that explain the installation process.

- A system diagram that lists the different files involved in the installation and the external systems and configuration.
- A flow diagram that helps me understand the different steps the system makes.

## Steps

1. Gather the source code from the references.
2. Ask addititional questions about the task and the outcomes.
3. Update the document with the answers to the questions (if any).
4. Build the narrative.
5. Build the diagrams.

## Additional instructions

- Update this document on every step to keep track.
- Add file references (including line numbers).

Los documentos que generamos pueden ser temporales o integrarse en nuestro repositorio como parte de una carpeta de docs (en la que podemos incluir tanto los documentos como los «prompts»).

Entendiendo el ayer

El siguiente paso en nuestra comprensión del sistema de instalación de WordPress es entender «el ayer». Esto nos permite aprender acerca de la evolución de nuestro software y entender los cambios a través de la información almacenada en el sistema de control de código.

Para ello, podemos leer el contenido de los commits, la descripción de los mismos y los ficheros cambiados. En el siguiente prompt, podemos agregar un segundo documento que nos dé la visión histórica, seleccionando qué cambios consideramos relevantes y, decidiendo además en qué momento parar de investigar.

I want to learn about how WordPress installation works, specifically:

- When does the installation gets triggered (i.e. what is checked before redirecting the user to the installer).
- What permissions are checked
- What data is created in the database
- What flags (if any) are modified at repository level (i.e, does a file permission change?)

## References

You should start looking at wp-admin/install.php and go down that path

## Outcome

I want to create a new document in a way that helps me answer those questions, with a short narrative on the installation process, as well as two diagrams that explain the installation process.

- A system diagram that lists the different files involved in the installation and the external systems and configuration.
- A flow diagram that helps me understand the different steps the system makes.

I want a second document that looks about the story and evolution of the feature. For this document, you will search in the code repository, looking at the commit messages and also the actual code changes

## Steps for first document

1. Gather the source code from the references.
2. Ask addititional questions about the task and the outcomes.
3. Update the document with the answers to the questions (if any).
4. Build the narrative.
5. Build the diagrams.

### Considerations for the first document  

1. Keep the concepts in one line (two at most).
2. Keep code references to up to 5 context lines and add links to the full file using wiki syntax with relative values.

## Steps for the second document

1. Pick the last 10 commits of the repository.
2. Search for the feature we are researching
3. If there are references in the commit message or in the code, add it to the analysis document
4. Continue with the next 10 commits.

### Considerations for the second document  

1. Only consider meaningful changes in the analysis, being bugfixes, new features and large refactors.

2. Compact conversation after each 10 commit block as you will have the context in the document.

Estos documentos los podríamos complementar (si tuvieramos acceso) con los documentos de diseño de las características, las definiciones de tareas (issues de Jira por ejemplo) o cualquier documentación que existe para entender los por qués, que muchas veces no llegan a plasmarse en el código.

LLMs para aprender

Los ejemplos que hemos visto antes con WordPress nos permiten tener un documento que explica un área del sistema que estamos mirando, pero ese documento es tan solo el principio en nuestra exploración.

Repetición y exposición

Cuando nos examinamos del carnet de conducir, aprendemos unas reglas básicas de la carretera y nociones elementales, pero realmente aprendemos a conducir tras años de experiencia en la carretera. Cuando aprendemos un idioma, solamente ganamos fluidez mediante repetición y exponiéndonos al mismo muchas veces.

En los proyectos de software pasa algo parecido, solamente vamos a desarrollar destreza en nuestro software mediante repetición y exposición, pero cómo podemos acelerar ese proceso usando LLMs?

Dar cera, pulir cera

Otra manera en la que podemos beneficiarnos de los LLMs es invirtiendo la relación, y que sean ellos los que nos hagan preguntas sobre nuestro sistema. Podemos además especificar cuan detalladas o difíciles queremos que sean las preguntas y cuantas indicaciones queremos.

I want to learn about how WordPress installation works, specifically:

- When does the installation gets triggered (i.e. what is checked before redirecting the user to the installer).
- What permissions are checked
- What data is created in the database
- What flags (if any) are modified at repository level (i.e, does a file permission change?)

## References

You should start looking at wp-admin/install.php and go down that path

## Outcome

I want you to ask me targeted questions about the instalation system, point me to the files that will help me find the answer, and evaluate my responses.

- The questions should require a written answer (no yes/no questions).
- The questions and answers should be brief.
- The dificulty level is of a tenured engineer with some experience in PHP

## Steps

- Read the code
- Pick one of the original areas
- Ask the question (providing hints)
- Evaluate the question

Como resultado, podemos tener a nuestro agente haciendo preguntas sobre el área del código de la que estamos intentando aprender, y gracias a la naturaleza no determinista de los LLMs, es casi seguro que tendremos preguntas diferentes con cada ejecución.

Repitiendo el simil del carnet de conducir, si nos acostumbramos a contestar preguntas sobre el repositorio también desarrollamos cierta memoria muscular a la hora de saber cómo está organizado y el día de mañana sabremos donde buscar.

Una nota sobre WordPress

El código fuente de WordPress está sobradamente extendido, hasta tal punto alimenta más del 40% de todos los sitios públicos de internet, por eso es posible que el código fuente de WordPress forme parte de los datos de entrenamiento de los modelos y por ello las respuestas sean mejores, para mitigar esto, en los prompts somos explícitos a la hora de establecer qué información leer, y herramientas como Cline leen expresamente los ficheros de código locales a la hora de hacer el análisis.

Siguientes pasos

Los prompts que hemos visto se pueden extender y convertir en plantillas que establecen un proceso, y que luego podemos aplicar a otros proyectos u otros procesos, lo importante es poder tener una manera estructurada de entender el estado de un repositorio, la historia del mismo, y una forma de aprendizaje basada en un bucle: pregunta -> búsqueda -> respuesta -> evaluación.

Y tú, has intentado usar LLMs para entender código? Te recomiendo probarlo con una pequeña parte de tu sistema, haz tus preguntas y que el LLM te acompañe en la exploración.