Rescaté un proyecto roto que me dejaron a medias sin documentar

Me llegó un proyecto a medias. Sin documentación, sin la persona que lo hizo y sin nadie a quien preguntarle por qué estaba montado así.

Y eso es más habitual de lo que parece: alguien empezó algo, se fue, y lo que queda es una carpeta que nadie entiende y que hay que hacer funcionar igual.

Te cuento cómo se entra ahí y qué haría distinto la próxima vez.

Qué me encontré

Una carpeta con archivos. Funciones que no se llamaban desde ningún sitio. Dos formas distintas de hacer lo mismo conviviendo, seguramente porque alguien empezó a cambiar algo y lo dejó a medias. Y varios archivos con nombres tipo "definitivo", "definitivo2" y "viejo", que es la firma universal de un proyecto abandonado.

Nada de comentarios. Ningún archivo que explicara qué es esto ni cómo se arranca.

Lo primero que sentí fue lo que siente todo el mundo: ganas de tirarlo y empezar de cero. Es una tentación fuerte y casi siempre es un error, porque ahí dentro hay decisiones y casos raros que tú no conoces y que vas a redescubrir a base de golpes.

¿Cómo entiendo un proyecto que no he hecho yo?

Con una regla: no leas el código hasta que sepas qué hace el programa.

Yo antes hacía lo contrario. Abría archivos al azar, intentaba entender línea por línea y a la media hora tenía la cabeza llena de detalles sin saber para qué servía nada. Eso es leer el manual de instrucciones de una máquina sin saber para qué sirve la máquina.

El orden correcto es de fuera hacia dentro, en cuatro pasos:

Uno: qué hace, desde fuera. Arráncalo si puedes y úsalo. Si no arranca, mira qué pantallas hay, qué botones, qué datos maneja. Necesitas una frase que diga "esto es un programa que hace X para Y".

Dos: por dónde entra. Cuál es el archivo que se ejecuta primero. Todo proyecto tiene una puerta de entrada, y desde ahí se sigue el hilo.

Tres: dónde están los datos. Qué guarda, en qué formato, dónde. La estructura de datos te cuenta más del proyecto que el código, porque es lo que más difícil resulta cambiar y por tanto lo que más se respeta.

Cuatro: ahora sí, el código. Y solo las partes que te hacen falta para lo que vas a tocar.

Dónde entra la IA

Aquí es donde la cosa cambió de verdad respecto a hace unos años.

Abrí Claude Code en la carpeta y lo primero que le pedí no fue arreglar nada. Le pedí que me explicara qué había ahí. Qué hace el proyecto, cómo se arranca, qué partes tiene y cómo se relacionan entre ellas.

Eso, que a mí me habría llevado una mañana entera de ir abriendo archivos, salió en un rato. Y no salió perfecto, ojo: hubo un par de cosas que interpretó de más. Pero como mapa inicial es exactamente lo que necesitas.

Después le pedí lo segundo más útil: que me escribiera un documento con esa explicación, dentro del propio proyecto. Es decir, la documentación que nunca existió, escrita el primer día.

Eso me pareció lo más valioso de todo el rescate. Porque a partir de ahí, cada vez que volvía al proyecto ya no partía de cero, y cada cambio que hacíamos se anotaba ahí mismo.

Si el proyecto que tienes entre manos es una web que ya existe y quieres tocarla sin romperla, el proceso concreto lo tengo en editar una web existente con Claude Code.

Las preguntas que más rendimiento me dieron

Después del mapa general, hay cuatro preguntas que resuelven casi todo.

"¿Qué partes de este proyecto no se usan?" En un proyecto abandonado hay mucho código muerto. Saber qué se puede ignorar reduce el problema a la mitad, y a veces a la cuarta parte.

"¿Qué pasa cuando ejecuto esto?" Seguir el recorrido de una acción concreta de principio a fin. Con dos o tres recorridos entendidos, ya te mueves.

"¿Qué está haciendo esta parte y por qué está escrita así?" Para los trozos raros. A veces la respuesta es "esto es un apaño para un caso concreto", y eso te salva de borrarlo.

"¿Qué se rompe si cambio esto?" La pregunta que hay que hacer antes de cada cambio, siempre.

Qué salió mal

Fiarme del mapa sin comprobarlo. La explicación inicial tenía un par de afirmaciones que no eran ciertas: describía una funcionalidad que estaba a medias como si funcionara. Me di cuenta al probarla. Desde entonces, cada cosa importante del mapa la verifico ejecutándola.

Arreglar de más. Empecé a limpiar cosas feas que no tenían nada que ver con lo que había venido a hacer. Dos horas después tenía cambios repartidos por todo el proyecto y ya no sabía cuál había roto qué. Aprendida la lección: primero que funcione, después se limpia, y nunca las dos cosas a la vez.

No guardar un punto de retorno. Estuve un rato largo haciendo cambios sin guardar una versión intermedia a la que volver. Cuando quise deshacer, tuve que deshacer a mano. Ahora guardo una versión en cuanto consigo que algo funcione, aunque sea feo.

Lo que aprendí sobre proyectos ajenos

Que el código no es el problema. El problema es la falta de contexto.

Un proyecto sin documentar no es difícil porque esté mal escrito. Es difícil porque cada decisión que ves tiene un motivo que no está escrito en ningún sitio, y tú no puedes distinguir entre "esto está así por una razón buena" y "esto está así porque alguien tenía prisa un jueves".

La IA no te devuelve ese contexto perdido, porque no lo tiene. Lo que hace es reconstruir el mapa mucho más rápido de lo que lo harías tú, y darte un sitio donde escribir el contexto nuevo para que no se vuelva a perder.

Ese es el cambio real: rescatar un proyecto ya no es una semana de arqueología. Es un par de sesiones para entenderlo y luego trabajo normal.

Si nunca has trabajado así y quieres el punto de partida, empieza por Claude Code para no programadores. Y para la parte de errores que aparecen al tocar, tienes cómo hacer que Claude Code arregle errores solo.

El documento que dejo escrito siempre

Al terminar un rescate dejo un archivo en la raíz del proyecto con cinco cosas: qué hace esto, cómo se arranca en local, dónde están los datos, qué partes son delicadas y qué cosas están a medias.

Cinco apartados, media página. No es documentación bonita, es la nota que me habría gustado encontrar el primer día.

Y lo escribo aunque el proyecto vaya a durar dos semanas más, porque el siguiente que entre ahí puedo ser yo mismo dentro de tres meses, sin acordarme de nada. Me ha pasado, y por eso ahora lo hago siempre.

Lo bueno de trabajar con la IA dentro del proyecto es que ese documento se mantiene solo: cada vez que cambiamos algo relevante, se actualiza en el mismo movimiento. Documentar deja de ser una tarea aparte que nunca se hace.

Y ahora qué

Si tienes un proyecto muerto en un cajón esperando a que alguien lo entienda, el orden es este.

Primero, que te lo expliquen desde fuera y verifica lo que te cuenten. Segundo, escribe la documentación que falta, ahí mismo, antes de tocar nada. Tercero, un solo cambio, probado, guardado. Y después el siguiente.

Y no lo tires para empezar de cero. Esa decisión se toma cuando entiendes el proyecto, no antes. Casi siempre, cuando por fin lo entiendes, resulta que no hacía falta tirarlo.

Si quieres aprender a montar y mantener tus propios proyectos web sin depender de que otro te los explique, te lo enseño entero aquí.

Crea tu web con Claude Code