💻 computer science

Documentation-Guided Agentic Codebase Migration from C to Rust

RustPrint es un marco de agentes guiado por documentación que permite una migración escalable a nivel de repositorio de C a Rust mediante la conversión del código fuente en planos arquitectónicos para orientar la planificación, la verificación y la reparación iterativa de agentes, logrando un mayor éxito de compilación y preservación de funciones en comparación con los traductores basados en LLM existentes.

Autores originales: Minh Le-Anh, Anh Nguyen Hoang, Bach Le, Nghi D. Q. Bui

Publicado 2026-05-15

📖 5 min de lectura🧠 Análisis profundo

CC BY 4.0

Autores originales: Minh Le-Anh, Anh Nguyen Hoang, Bach Le, Nghi D. Q. Bui

Artículo original bajo licencia CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Esta es una explicación generada por IA del artículo a continuación. No ha sido escrita ni avalada por los autores. Para mayor precisión técnica, consulte el artículo original. Leer descargo de responsabilidad completo

Imagina que tienes una biblioteca masiva y antigua escrita en un lenguaje llamado C. Es la base de muchos sistemas críticos (como sistemas operativos y herramientas de red), pero está construida sobre cimientos inestables. Los "ladrillos" (la gestión de memoria) están sueltos, y si no eres extremadamente cuidadoso, toda la estructura puede colapsar o ser fácilmente penetrada por intrusos (violaciones de seguridad).

Quieres reconstruir esta biblioteca completa utilizando un nuevo lenguaje moderno llamado Rust. Rust es como una fortaleza: tiene cerraduras de seguridad automáticas que evitan que el edificio colapse. Pero aquí está el problema: traducir una biblioteca completa, ladrillo a ladrillo, es increíblemente difícil. Si solo traduces una habitación a la vez, a menudo pierdes los planos, olvidas cómo se conectan las habitaciones, o terminas con un edificio que parece Rust pero actúa como un edificio de C roto.

RustPrint es un nuevo "arquitecto y equipo de construcción" (un sistema de agente de IA) diseñado para resolver esto. En lugar de solo traducir línea por línea, utiliza una estrategia inteligente de tres pasos para asegurar que el nuevo edificio sea seguro, funcional y fiel al diseño original.

Así es como funciona RustPrint, usando analogías simples:

1. La Fase de "Planos" (Documentación Primero)

La mayoría de las herramientas de traducción intentan traducir una oración, luego la siguiente, luego la siguiente. RustPrint se detiene y dice: "Espera, leamos todo el libro primero".

Qué hace: Lee toda la base de código C antigua y escribe un manual de instrucciones masivo y detallado (documentación) que describe cómo funciona el sistema, cómo se conectan las partes y por qué fue construido de esa manera.
La Analogía: Imagina que estás renovando un castillo antiguo. En lugar de simplemente cambiar las piedras, primero contratas a un experto para dibujar un mapa perfecto y detallado de la distribución del castillo, los pasadizos secretos y la lógica estructural. Este mapa se convierte en el "plano" para la nueva construcción.
Por qué importa: Esto asegura que la IA entienda la intención del código, no solo la sintaxis. Evita que la IA olvide cómo dos habitaciones diferentes necesitan comunicarse entre sí.

2. La Fase de "Construcción" (Traducción por Agentes)

Una vez que los planos están listos, RustPrint envía un equipo de trabajadores especializados de IA para construir la nueva versión en Rust.

El Planificador: Mira los planos y dice: "Necesitamos construir la cocina aquí, la biblioteca allá, y asegurarnos de que la fontanería se conecte". Crea un plan de construcción paso a paso.
El Constructor: Construye las habitaciones (módulos de código) una por una.
El Inspector: Después de que se construye cada habitación, el Inspector realiza una "verificación de seguridad" (compilación). Si una pared está torcida o una tubería gotea (errores de código), el Constructor lo repara inmediatamente antes de continuar.
El Oficial de Seguridad: Verifica específicamente los atajos "inseguros". Rust permite código inseguro solo si es absolutamente necesario, pero este oficial intenta eliminarlos, asegurando que el edificio final sea una fortaleza.

3. La Fase de "Control de Calidad" (La Doble Verificación)

Aquí es donde RustPrint se vuelve realmente inteligente. No solo confía en que el edificio está terminado; lo verifica contra el original.

La Verificación "Espejo": Después de que se construye el nuevo edificio en Rust, la IA escribe un nuevo manual de instrucciones para la versión en Rust. Luego compara este nuevo manual con el manual original en C.
- Si el nuevo manual falta una sección (por ejemplo, "El túnel secreto"), la IA sabe que se perdió una característica y vuelve atrás para corregirlo.
La "Prueba de Estrés": La IA toma las pruebas originales (como pruebas de estrés para las paredes del castillo) y las ejecuta en el nuevo edificio en Rust. Si una pared se agrieta durante la prueba, la IA no solo la repara; descubre por qué se agrietó la pared y corrige el defecto de diseño subyacente.

Los Resultados: ¿Funcionó?

Los investigadores probaron RustPrint en 8 proyectos reales de C a gran escala (que van desde bibliotecas pequeñas hasta sistemas masivos con más de 80.000 líneas de código).

La Competencia: Otras herramientas (como C2Rust o traductores de IA simples) intentaron hacer esto pero fallaron. O no pudieron terminar la construcción (el código no se compilaba) o construyeron una estructura que parecía Rust pero estaba llena de agujeros.
El Éxito de RustPrint:
- Terminó el trabajo: RustPrint construyó con éxito una versión funcional y compilable de cada proyecto individual.
- Mantuvo las características: Preservó entre el 93% y el 97% de las características originales (dependiendo del modelo de IA utilizado), mientras que otros métodos solo conservaban alrededor del 50%.
- Aprobó las pruebas: Cuando ejecutaron las pruebas originales en el nuevo código, RustPrint aprobó entre el 95% y el 98% de ellas. Otros métodos fallaron significativamente con más frecuencia.
- Fue seguro: El código resultante estaba casi completamente libre de atajos "inseguros", lo que lo hace mucho más seguro que los intentos anteriores.

La Conclusión

RustPrint demuestra que para migrar un sistema de software masivo y complejo, no puedes ser solo un traductor; tienes que ser un arquitecto. Al obligar a la IA a escribir un "plano" primero, comparar los planes y ejecutar pruebas de estrés, RustPrint puede mover con éxito el código C heredado al mundo seguro y moderno de Rust sin perder el alma del sistema original.

Nota: El artículo se centra estrictamente en la migración técnica del código. No afirma que este método esté listo para su uso inmediato en dispositivos médicos críticos para la vida o que resuelva todos los problemas de software, sino que es una herramienta altamente efectiva para la tarea específica de traducir grandes bases de código C a Rust.

Resumen Técnico: RustPrint – Migración de Base de Código Guiada por Documentación de Agentes de C a Rust

Declaración del Problema

La migración de repositorios heredados de C a Rust es crítica para abordar las vulnerabilidades de seguridad de la memoria inherentes al modelo de punteros de C, sin embargo, sigue siendo un desafío de ingeniería significativo. Las herramientas de traducción existentes (por ejemplo, C2Rust) a menudo operan a nivel de archivo o función, preservando estructuras al estilo de C y resultando en un uso intensivo de bloques unsafe, o bien no logran capturar la intención arquitectónica, el flujo de datos y la razón de diseño del sistema original. Además, los enfoques actuales basados en Modelos de Lenguaje Grande (LLM) a menudo luchan con tareas a escala de repositorio, fallando en producir salidas compilables para bases de código grandes (11K–84K líneas de código) debido a una falta de comprensión holística y coordinación entre módulos. El problema central es que la migración es fundamentalmente una tarea de comprensión de la base de código que requiere un modelo mental de estructuras de datos compartidas, límites de módulos e invariantes entre archivos, lo cual las estrategias de traducción aisladas no pueden recuperar.

Metodología: El Marco RustPrint

RustPrint es un marco multiagente diseñado para la migración de C a Rust a nivel de repositorio. Introduce un paradigma impulsado por documentación donde la documentación generada automáticamente sirve como una representación intermedia (IR) para guiar la planificación, la traducción y el refinamiento. El marco opera a través de una tubería de cinco etapas:

1. Traducción de Código Guiada por Documentación

En lugar de traducir unidad por unidad, RustPrint primero genera documentación holística de la base de código fuente de C utilizando un módulo dedicado DocGen.

Proceso: El repositorio fuente se agrupa a nivel de archivo y luego se eleva a abstracciones de componentes de nivel superior. El módulo DocGen produce documentación estructurada ( $S_{doc}$ ) que captura características abstractas, interacciones de módulos y razón de diseño, en lugar de solo descripciones sintácticas.
Agentes:
- Planificador: Convierte $S_{doc}$ en un plan de implementación a nivel de crate (IMPLEMENTATION_PLAN.md), resolviendo detalles arquitectónicos y definiendo responsabilidades de componentes.
- Traductor: Implementa cada crate planificado, iterando con cargo_check para asegurar la compilabilidad y detect_unsafe para minimizar los bloques inseguros.
- Sintetizador: Realiza la integración a nivel de repositorio, resolviendo dependencias entre crates y generando un README.md unificado.

2. Refinamiento de Código Impulsado por Requisitos

Para asegurar la completitud semántica, RustPrint emplea un mecanismo de refinamiento iterativo que compara la documentación de la base de código Rust generada ( $T_{doc}$ ) contra la documentación fuente ( $S_{doc}$ ).

Mecanismo: El sistema aproxima la preservación funcional mediante la equivalencia de documentación: $CodeEquiv(S, T) \approx DocEquiv(S_{doc}, T_{doc})$ .
Agente: El Refinador de Requisitos identifica brechas donde $T_{doc}$ no coincide con $S_{doc}$ (por ejemplo, características omitidas, APIs desajustadas). Edita el código traducido usando str_replace_editor, verifica la compilación e itera para reparar funcionalidad faltante o desalineada.

3. Revisión de Código Consciente de la Ejecución

Reconociendo que la comparación de documentación no puede exponer todos los errores en tiempo de ejecución, el marco añade un bucle de retroalimentación impulsado por pruebas.

Proceso: La suite de pruebas fuente es traducida a Rust por el Traductor de Pruebas.
Agente: El Revisor de Ejecución analiza las pruebas fallidas usando cargo_single_test. Actualiza únicamente el código de producción traducido (no las pruebas) para corregir inconsistencias de comportamiento como casos límite, actualizaciones de estado o desajustes de protocolo que sobreviven a la alineación estática pero fallan bajo ejecución concreta.

Contribuciones Clave

Paradigma de Migración Impulsado por Documentación: El artículo propone utilizar la documentación de la base de código generada automáticamente como una representación intermedia para la traducción a nivel de repositorio. Este enfoque codifica la comprensión de toda la base de código antes de la traducción, permitiendo la generación de Rust idiomático que preserva la intención arquitectónica en lugar de simplemente replicar la estructura sintáctica.
Refinamiento Iterativo Guiado por Documentación: Un mecanismo que evalúa y mejora el código Rust generado comparando su documentación contra la fuente, identificando sistemáticamente brechas de cobertura y promoviendo la alineación estructural.
Revisión Consciente de la Ejecución: La integración de retroalimentación impulsada por pruebas permite que el sistema corrija iterativamente inconsistencias de comportamiento mediante la ejecución dinámica de pruebas, logrando corrección funcional más allá de lo que garantiza la traducción estática.
Evaluación a Gran Escala: El marco se evalúa en ocho repositorios C del mundo real que van desde 11K hasta 84K líneas de código, abordando la limitación de trabajos anteriores que se centraron en pequeños puntos de referencia.

Resultados Experimentales

La evaluación se realizó en ocho repositorios utilizando dos modelos base: un modelo de pesos abiertos (Kimi-K2-Instruct) y un modelo de pesos cerrados (GPT-5.4). Las líneas base incluyeron herramientas tradicionales (C2Rust) y agentes basados en LLM (Self-Repair, EvoC2Rust y una línea base agéntica de Claude Code).

Compilabilidad del Proyecto: RustPrint compiló con éxito cada repositorio objetivo bajo ambos modelos base. En contraste, los traductores LLM de línea base (Self-Repair, EvoC2Rust) fallaron en producir repositorios compilables de extremo a extremo a esta escala. C2Rust compiló pero retuvo un uso pesado de unsafe.
Preservación de Características: Medido mediante la puntuación CodeWikiBench, RustPrint superó significativamente a la línea base de Claude Code.
- Con Kimi-K2-Instruct: RustPrint logró 93.26% frente a 52.52% para Claude Code.
- Con GPT-5.4: RustPrint logró 97.76% frente a 48.87% para Claude Code.
Corrección Funcional: Utilizando un protocolo de evaluación cruzada (probando la salida de RustPrint con las pruebas de Claude Code y viceversa), RustPrint demostró una robustez superior.
- Kimi-K2-Instruct: 95.17% de Tasa de Aprobación de Pruebas (TPR) frente a 79.85% para Claude Code.
- GPT-5.4: 98.70% de TPR frente a 79.85% para Claude Code.
Seguridad: RustPrint logró altas tasas de seguridad, minimizando los bloques unsafe. Con GPT-5.4, alcanzó tasas seguras del 99.41% a nivel de API y del 98.47% a nivel de archivo, superando a otros métodos.

Significado y Afirmaciones

El artículo afirma que la coordinación guiada por documentación es una dirección viable y efectiva para la migración escalable de bases de código. Los resultados sugieren que tratar la migración como un problema de coordinación entre archivos, interfaces y pasos de reparación, en lugar de una tarea de generación de código cruda, es esencial para el éxito a escala de repositorio.

Los autores enfatizan que:

La planificación y el refinamiento importan más que la traducción de un solo disparo: El bucle iterativo de generar documentación, compararla contra la fuente y refinarla basándose en la retroalimentación de ejecución es crítico para manejar dependencias complejas entre módulos.
La documentación actúa como una guía operativa: No es meramente contexto de fondo, sino un plano funcional que impulsa la recuperación de requisitos faltantes y la alineación estructural.
La corrección de comportamiento es alcanzable: Los resultados de las pruebas de suites cruzadas indican que las ganancias no son solo documentales; los repositorios traducidos preservan el comportamiento real en tiempo de ejecución.

El artículo concluye que, si bien el estudio actual representa un primer resultado sólido en repositorios realistas, el enfoque deja claros caminos para mejoras futuras, como manejar repositorios de lenguajes mixtos, dependencias externas más profundas y sistemas de compilación menos estandarizados. Los autores posicionan a RustPrint como un método práctico para escalar la traducción basada en LLM de archivos aislados a tareas de ingeniería completas a nivel de repositorio.