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.
Qué se captura y qué es ruido
Esa lista es corta a propósito. El fallo habitual no es capturar de menos, es capturar todo, y eso produce un segundo repositorio que nadie lee y en el que nadie confía.
Hay una pregunta que lo mantiene acotado. ¿Alguien que toque este código dentro de seis meses decidiría peor sin esto? Una alternativa descartada pasa el filtro, porque sin ella la misma opción se vuelve a proponer y a descartar. Una restricción pasa, porque sin ella alguien quita una frontera que existía por un motivo. Un resumen en prosa de lo que hace la feature no pasa, porque el código ya lo dice y el resumen lo contradirá en una o dos releases.
Esa distinción pesa más con agentes de lo que pesaba con equipos. Una persona que lee un resumen caducado suele notar el desajuste y se va al código. Un agente lo lee como vigente y actúa en consecuencia, así que el contexto que iba a ayudar acaba produciendo trabajo equivocado hecho con seguridad. El contexto capturado tiene que ser de la clase que se puede contrastar con el repositorio, o es un pasivo disfrazado de activo.
Por qué esto no se pudre como se pudren los documentos
La documentación de siempre caduca porque vive en un sitio que el trabajo no toca. Nadie actualiza una página de wiki como efecto secundario de integrar un cambio, así que la página y el código se separan, y esa separación no se ve hasta que alguien se apoya en ella.
El contexto atado a los artefactos que describe se comporta de otra forma. Cuando una decisión, sus criterios y su evidencia comparten identidad con el cambio que los produjo, un cambio posterior que los contradiga tiene algo concreto a lo que contradecir, y el conflicto aparece en el momento en que sale barato resolverlo. Es el mecanismo detrás de la documentación que deja de pudrirse, y la razón de que capturar tenga que ir dentro del trabajo y no en un paso posterior.
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. El framework de desarrollo AI-first sitúa esta capa de preservación de contexto dentro del ciclo completo; la comparación con Waterfall, Agile y DevOps explica en qué se diferencia el modelo operativo.
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.
¿Qué no merece la pena capturar?
Todo lo que el código ya dice, y todo aquello que nadie decidiría distinto por haberlo leído. Los resúmenes en prosa de lo que hace una función son el caso más claro: el código es más exacto y además se mantiene solo. Captura lo que el código no puede sostener, que son los motivos, las opciones descartadas, las restricciones y la evidencia de que el resultado cumplió su contrato.
¿En qué se diferencia esto de escribir mejor documentación?
La documentación suele ser un artefacto aparte que se mantiene con su propio ritmo, y por eso deriva. La diferencia está en dónde vive el contexto. Cuando la decisión, los criterios y la prueba comparten identidad con el cambio que los produjo, mantenerlos al día forma parte de cerrar ese cambio en vez de competir con él. La memoria de producto desarrolla qué significa eso para un equipo con el tiempo.