Un desarrollador traslada el contexto de un agente de IA de los chats al repositorio con doubled-graph

Cuando se cambia de Claude Code a Codex o a otra herramienta, la primera pregunta suele ser cómo transferir el historial de chats. El autor de un análisis publicado en Habr sostiene que esa no es la pregunta correcta. Desde hace seis meses mantiene el contexto del proyecto no en las conversaciones, sino en el repositorio, y afirma que cambiar de agente ha dejado de ser doloroso.

Por que el historial de chats es una mala memoria

Una conversación conserva el debate sobre el proyecto, no las decisiones finales. Contiene ruido, repeticiones, ideas descartadas y corteses mensajes de "OK". El nuevo agente tiene que leerlo y reinterpretarlo todo, sin ninguna forma de verificar esa interpretación: en el chat no hay contratos, límites de módulos ni criterios de aceptación que puedan contrastarse con el código.

Existe una segunda desventaja. Reconstruir el contexto se convierte en un impuesto para cada nueva sesión. Cada vez que cambia la herramienta, hay que volver a reunir el conocimiento y determinar cuál de los mensajes contradictorios fue el definitivo.

El autor propone una prueba sencilla de portabilidad. Abra el repositorio con un agente que nunca haya visto el proyecto y dele una única instrucción: "Lee lo que hay aquí y explica cómo está organizado el proyecto y qué está ocurriendo ahora mismo." Si la respuesta es precisa, el contexto vive realmente en el repositorio.

Que contiene el repositorio

La base es la metodología GRACE de osovv, publicada con licencia MIT: la intención, los límites de los módulos y las comprobaciones se guardan junto al código. El autor añadió tres elementos: un flujo para migrar código existente, un grafo de llamadas mediante CodeGraphContext y una envoltura MCP. El conjunto forma la utilidad doubled-graph.

El código se anota con comentarios-ancla emparejados. Cada módulo tiene un MODULE_CONTRACT con su objetivo, alcance y dependencias; cada función, un CONTRACT con entradas, salidas y efectos secundarios; y la lógica se divide en bloques. El campo LINKS vincula un archivo con un módulo, de modo que un grep normal de un identificador como M-AUTH-VALIDATE entrega al agente un par de párrafos relevantes en lugar de 40 archivos. Un linter verifica que las anclas estén emparejadas, sean únicas y correspondan a las exportaciones reales.

Hay dos grafos. Declared describe la intención y se guarda en .grace/graph/. Computed se construye a partir del AST y muestra los hechos: quién llama a quién. La herramienta detect_changes los compara y encuentra discrepancias: código sin módulo, un módulo sin código, dependencias obsoletas, un módulo sin comprobaciones o un archivo sin anotaciones. Un hook post-commit actualiza el grafo computed, mientras que detect_changes puede ejecutarse en pre-commit o CI. Antes de editar, el agente también pregunta a qué afectará el cambio.

Migracion de proyectos antiguos

Los métodos de "primero la especificación, después el código" suelen fracasar en proyectos con diez años de antigüedad donde no existe una especificación, pero el código funciona. Por eso hay dos modos. En migration, la fuente de verdad es el código: el agente reconstruye la intención, anota los archivos y pasa por puertas de aprobación humana. En post_migration, la fuente de verdad son los artefactos y cualquier discrepancia resulta sospechosa. Entonces hay tres salidas: actualizar el artefacto mediante un paquete de cambios, revertir el código para ajustarlo al contrato o registrar el problema en DRIFT.md y bloquear el módulo.

Otra idea independiente es el belief-state. En puntos críticos, el agente registra qué supuesto no evidente adoptó, junto con un ancla y un session_id. Cuando meses después llegue un registro de producción, se podrá reconstruir el estado de la IA en ese punto.

Limitaciones y conclusion

El autor advierte con franqueza sobre las limitaciones: no hay cifras, no realizó un experimento controlado y todo se basa en impresiones subjetivas. Además, la metodología es exigente: sostiene que los diez principios deben aplicarse en conjunto y que una implantación parcial no compensa el esfuerzo. Las anotaciones con anclas añaden ruido al código y las puertas de aprobación ralentizan las correcciones rápidas. Para proyectos pequeños, todo esto puede ser excesivo.

Aun así, la idea merece atención incluso sin adoptar la metodología completa. Si trabaja con varios agentes, lleve al repositorio al menos los contratos de los módulos, el grafo de dependencias y la lista de comprobaciones, y deje que CI detecte las discrepancias con el código. Comprobar el resultado es sencillo: dele a un agente nuevo esa misma instrucción única. Para probarlo, ejecute pipx install doubled-graph, después doubled-graph setup y use la instrucción inicial del directorio prompts.