Abres un repo que no escribiste, o uno que vibe-codeaste hace cinco meses y ya no recuerdas. No hay PRD. No hay historias de usuario. No hay registro de decisiones. El código es el único documento en la sala, y no se explica solo.
Todas las guías enseñan la misma dirección. Escribe la spec, deja que el agente construya. Es un buen flujo para una carpeta en blanco. Es inútil para el software que ya existe, que es casi todo el software. El repo que tienes delante no se construyó desde una spec, y no puedes des-construirlo para conseguir una.
Así que necesitas la otra dirección. Leer el repo y sacar artefactos de producto: las historias que ya entrega, los criterios que ya impone, las decisiones que ya congeló en la estructura. Este es el camino que casi nadie documenta, y es el que más vas a usar.
El camino de ida asume un repo que todavía no existe
El desarrollo guiado por especificaciones, al menos como se vende, empieza antes del código. Describes comportamiento, un agente genera una implementación, la spec se queda como contrato. Limpio, cuando el tiempo corre en ese orden.
El código existente corrió el tiempo al revés. Alguien tomó cientos de decisiones pequeñas contra un deadline, la mitad en una ventana de chat, ninguna escrita. El comportamiento es real y está en producción. El registro de por qué se comporta así se evaporó en cuanto se cerró la sesión. Pregúntale al autor original seis meses después y te encoges de hombros los dos, porque el código es la única documentación que está garantizada al día, y también la menos legible.
Así que la pregunta útil no es “qué spec produciría este código”. Es más estrecha y sí tiene respuesta. ¿Qué contrato está imponiendo este código ahora mismo, lo escribiera alguien o no?
En un repo se esconden tres artefactos, a tres profundidades
Leer un repo en artefactos no es una extracción. Son tres, y cada una pierde más información.
Las historias son lo más superficial. El comportamiento que entrega el software está ahí, en las rutas, los handlers, los estados de la UI. Un flujo de registro, un reset de contraseña, un botón de exportar que manda un CSV por correo. Esto lo lees en la superficie con confianza decente, porque el código lo ejecuta a diario. Un agente es genuinamente bueno en esta pasada. Apúntalo al codebase, pregúntale qué puede hacer un usuario, y la lista que devuelve es casi toda verdad.
Los criterios de aceptación están una capa más abajo, y viven en los tests. Un test es un criterio que alguien ya acordó, escrito en un lenguaje que se ejecuta. “Los tokens de reset caducan a la hora” no es un comentario, es una aserción que falla si lo rompes. La suite de tests es la veta más rica de criterios de aceptación de todo el repo, porque a diferencia de la documentación no puede quedarse obsoleta en silencio sin ponerse en rojo. Donde no hay tests, los criterios siguen ahí, enterrados en el código de validación y las ramas de error, solo que más difíciles de creer.
Las decisiones son lo más profundo, y la extracción se vuelve lossy rápido. ¿Por qué auth es su propio servicio? ¿Por qué este módulo reimplementa algo que el framework ya da? Parte de eso se recupera del historial de git, los mensajes de commit, la forma del grafo de dependencias. Mucho se ha perdido, y el artefacto lo reconoce. Aquí es donde la extracción inversa se gana su peligro.
La línea entre leer e inventar
El modo de fallo no es la pereza. Es la seguridad. Un agente al que le pides “documenta este repo” produce un conjunto precioso de historias, criterios y racional, y un buen trozo del racional estará inventado. Sin mala fe. Rellena el hueco donde debería ir una decisión con una razón que suena plausible, y esa razón se lee exactamente igual que las de verdad.
Eso es peor que un doc vacío, porque un “porqué” equivocado y seguro lo trata como verdad la siguiente persona y el siguiente agente. Una carpeta llamada legacy se convierte en “el equipo decidió deprecar esto”, cuando en realidad alguien movió un fichero una vez y no volvió.
La disciplina es la procedencia. Cada artefacto extraído lleva una etiqueta. Comportamiento observado desde un test que pasa: probado. Comportamiento leído de una ruta: observado. Decisión conjeturada desde la estructura: inferido. Mantienes los tres aparte y nunca dejas que lo inferido se promocione a probado en silencio.
Es la misma regla que mantiene veraz a un grafo de conocimiento de producto leído hacia atrás, en vez de convertirlo en una alucinación segura sobre código desordenado.
Cómo corro la pasada de verdad
No “resume el repo”. Eso te da prosa. Quieres artefactos contra los que construir.
Empieza por los tests, porque son la fuente de más señal y la que menos miente. Cada aserción es un candidato a criterio de aceptación con evidencia adjunta. Léelos en criterios primero, antes de tocar una línea de implementación.
Luego lee la superficie: rutas, handlers, puntos de entrada, estados de UI. Eso se vuelven historias. Mantenlas al nivel del comportamiento visible para el usuario, no de la implementación. “Un usuario puede exportar sus datos”, no “el controlador de exportación llama al serializer”.
Después, y solo después, ve a por las decisiones, y trata el historial de git como testigo principal. Mensajes de commit, el orden en que se construyeron las cosas, qué se revirtió. Lo que no puedas fuentear, o lo marcas inferido o lo dejas fuera. El hueco también es dato. Una historia sin test debajo te está diciendo exactamente dónde el software está sin probar.
La salida no es un documento que lees una vez. Es un conjunto de artefactos contra los que un agente puede construir mañana sin re-derivar todo el contrato desde cero, que es el mismo problema que intenta resolver, aguas arriba, un cerebro de producto que se mantiene solo.
Los huecos son la mitad del valor
Los artefactos que puedes extraer son útiles. Los que no puedes lo son más, porque un hueco es una señal con ubicación.
Una ruta sin test debajo es comportamiento corriendo en producción que nadie acordó verificar. La extracción lo encuentra y le pone una bandera. Un cúmulo de código al que no llega ninguna historia es o peso muerto o una feature tan indocumentada que quitarla es una apuesta. Una decisión que no pudiste fuentear, solo inferir, marca un sitio donde el siguiente cambio se hace a ciegas.
Cuando corrí esta pasada sobre un prototipo viejo mío, la salida más valiosa no fue la lista limpia de historias. Fue la lista corta de endpoints que el intake podía describir pero no podía conectar con ninguna razón para existir. Dos eran restos de una idea que abandoné y olvidé borrar. Uno era portante y de verdad había olvidado que estaba ahí. Una spec de ida nunca habría sacado eso, porque una spec de ida solo sabe lo que te acordaste de escribir.
Dónde encaja PaellaDoc
Esta pasada inversa es lo que PaellaDoc llama intake. Lee un repo existente y su historial en historias, criterios de aceptación y decisiones, cada uno etiquetado con de dónde viene, y los mantiene como un contrato vivo en tu máquina en vez de un resumen suelto en un chat que vas a perder. El objetivo no es un export más bonito. Es que el siguiente agente, y el siguiente tú, empiecen desde lo que el código impone de verdad en vez de volver a adivinar.
Va local-first y gratis, sin nube y sin cuenta, contra el repo que ya tienes.
¿Cuál de tus repos tiene comportamiento real y cero registro escrito de por qué? Cuéntame en el foro.
Preguntas frecuentes
¿Qué artefactos de producto se pueden extraer de un repo existente?
El comportamiento que el código impone (historias de usuario), las condiciones que comprueba (criterios de aceptación, más ricos cuando hay tests) y parte de las decisiones congeladas en la estructura. Lo que no se recupera del todo es la intención: por qué se eligió algo, qué se descartó, y qué hace el código por accidente en vez de a propósito.
¿Por qué leer un repo en artefactos en vez de escribir specs hacia delante?
Porque casi todo el software ya existe. El camino de ida (spec y luego construir) encaja en greenfield. El código heredado, los prototipos vibe-coded y los sistemas legacy no tienen spec, y la forma más rápida de tener un contrato contra el que construir es leer el que el código ya impone.
¿Te puedes fiar de artefactos sacados del código por reverse intake?
Solo si cada uno lleva su procedencia. Un comportamiento leído de un test que pasa es evidencia. Una decisión inferida del nombre de una carpeta es una conjetura. La extracción es peligrosa cuando blanquea conjeturas como documentación segura, así que los artefactos deben marcar qué está probado, qué está observado y qué está inferido, y mantenerlos separados.