El código conserva el qué, no el porqué
La IA permite escribir y modificar código con más rapidez. El problema aparece después: el repositorio contiene el resultado, pero no siempre conserva el requisito, la restricción o la decisión que lo produjo.
Cuando otra persona o agente vuelve sobre ese código, tiene que reconstruir la intención a partir de nombres, comentarios y comportamiento observado. Esa reconstrucción consume tiempo y puede reabrir decisiones ya resueltas.
Qué se pierde cuando falta contexto
El contexto no es una explicación larga alrededor del código. Son piezas concretas:
- el problema de usuario que justificó el cambio;
- los requisitos y criterios de aceptación;
- las alternativas descartadas y sus motivos;
- las restricciones técnicas o de negocio;
- la evidencia que demuestra que el resultado cumple el contrato.
Sin esos enlaces, el onboarding se alarga, las revisiones repiten debates anteriores y los agentes trabajan con una versión incompleta del sistema.
Cómo lo organiza PaellaDoc
PaellaDoc trata el contexto como parte del trabajo, no como un documento separado que hay que mantener después. Conecta discovery, decisiones, especificaciones, tareas, código y evidencia para que se pueda recorrer el camino entre una necesidad y su implementación.
La estructura cumple tres funciones:
- mantiene los artefactos relacionados bajo una identidad común;
- entrega a cada agente las reglas y decisiones que necesita para su tarea;
- guarda la verificación junto a la versión del contrato que se comprobó.
Dónde cambia el flujo
Definición de producto
La investigación, la decisión y el requisito permanecen enlazados. Una historia de usuario deja de ser un resumen aislado y conserva la evidencia que la originó.
Diseño técnico
Las decisiones de arquitectura incluyen sus restricciones y alternativas. El equipo puede revisar por qué existe una frontera antes de modificarla.
Implementación y verificación
La tarea llega al agente con criterios comprobables. El resultado vuelve con logs, tests y otros artefactos de verificación conectados al mismo contrato.
Lo que PaellaDoc no sustituye
La estructura no decide por el equipo, no convierte una hipótesis en evidencia y no garantiza que una especificación sea correcta. Hace visibles las decisiones y sus pruebas para que puedan revisarse sin reconstruirlas desde cero.
Ese es el objetivo: que aumentar la velocidad de implementación no reduzca la capacidad de entender, revisar y cambiar el producto después. Los principios del desarrollo AI-First explican el modelo con más detalle.
Preguntas frecuentes
¿Qué es PaellaDoc?
PaellaDoc es un framework para preservar el contexto a lo largo de todo el ciclo de desarrollo, nacido de un dolor concreto: código generado por IA que se vuelve ilegible para su propio autor meses después. En lugar de documentación separada del trabajo, captura el razonamiento, los requisitos y las decisiones detrás del código y los mantiene conectados a él, para que el «porqué» sobreviva mucho después de que la IA produjera el «qué».
¿Qué es la crisis del contexto en el desarrollo con IA?
Es la brecha que abre la IA entre lo rápido que se escribe el código y lo rápido que desaparece su contexto. El código fluye deprisa, pero el razonamiento detrás — las decisiones, las restricciones, la intención — rara vez se captura. Meses después, ese contexto perdido hace que tu propio código te resulte ajeno, ralentiza el onboarding y las decisiones pasadas se vuelven a discutir. La crisis no es la calidad del código; es el conocimiento perdido.
¿Por qué se pierde el contexto en el desarrollo asistido por IA?
Porque la generación es instantánea y capturar el contexto no lo es. Cuando un asistente escribe una función en minutos, los prompts, los trade-offs y las opciones descartadas detrás suelen quedar sin registrar. La documentación tradicional vive en herramientas aparte y se pudre. Sin anclar deliberadamente el razonamiento al código, cada cambio futuro obliga a alguien a reconstruir la intención desde cero, que es justo donde el ahorro de tiempo se esfuma en silencio.