Las herramientas de programación con IA todavía tienen dificultades para entender repositorios grandes.
CodeWiki ayuda a los desarrolladores a analizar proyectos de GitHub y generar documentación estructurada, facilitando la exploración de bases de código desconocidas. En lugar de pedirle a un modelo de IA que adivine cómo funciona un repositorio a partir de archivos dispersos, CodeWiki construye una comprensión estructurada del proyecto.
En este tutorial, utilizaremos CodeWiki con Atlas Cloud para convertir un repositorio de GitHub en una Wiki generada por IA.
Cómo CodeWiki analiza un repositorio de GitHub y genera documentación
CodeWiki utiliza un análisis de repositorio jerárquico
En lugar de tratar un repositorio como un gran bloque de texto, CodeWiki lo analiza a través de diferentes niveles de estructura.
El flujo de trabajo se puede resumir así:
plaintext1Repositorio 2 ↓ 3Análisis de la estructura del proyecto 4 ↓ 5Comprensión de módulos 6 ↓ 7Análisis de componentes 8 ↓ 9Generación de documentación
Este enfoque sigue un flujo de trabajo similar al que utilizan los desarrolladores para aprender sistemas desconocidos:
- Entender la arquitectura general
- Identificar los módulos principales
- Explorar componentes importantes
- Leer la implementación detallada
CodeWiki aplica esta idea mediante el análisis de repositorios asistido por IA.
CodeWiki genera algo más que comentarios de código
La documentación tradicional suele centrarse en funciones o clases individuales.
CodeWiki se centra en la documentación a nivel de repositorio.
Los materiales generados pueden incluir:
- descripción general del proyecto
- explicaciones de módulos
- información de arquitectura
- documentación visual
El objetivo no es solo explicar qué hace cada archivo.
Se trata de crear un mapa más claro de cómo encaja el proyecto.
Paso a paso: generar una Wiki con IA para un proyecto de GitHub con CodeWiki
El flujo de trabajo tiene cuatro pasos principales:
- Instalar CodeWiki
- Configurar un proveedor de LLM
- Ejecutar el análisis del repositorio
- Explorar la documentación generada
Paso 1: Instalar CodeWiki
Instala CodeWiki directamente desde GitHub:
plaintext1pip install git+https://github.com/FSoft-AI4Code/CodeWiki.git
Tras la instalación, el comando codewiki estará disponible.
Puedes verificar que la CLI está disponible:
plaintext1codewiki --version
Si ves el error cannot import name 'OpenAIModel', intenta lo siguiente:
plaintext1python -m pip uninstall pydantic-ai pydantic-ai-slim -y 2python -m pip install "pydantic-ai>=1.0.6,<2"
Paso 2: Obtener una clave de API de Atlas Cloud
Ve a la consola de Atlas Cloud, abre la página de claves API, haz clic en Create API Key (Crear clave API), luego copia y almacena la clave de forma segura. Atlas Cloud indica que la clave solo se muestra una vez, así que guárdala en un lugar seguro al crearla.
Mantén la clave privada. No la pegues en un repositorio público de GitHub, en un borrador de artículo público ni en una captura de pantalla.
La clave de API se pasa como un token Bearer, y Atlas Cloud también recomienda almacenarla en una variable de entorno en lugar de codificarla directamente en los proyectos.
En macOS o Linux:
plaintext1export ATLASCLOUD_API_KEY="tu-clave-api-de-atlas-cloud"
En Windows PowerShell:
plaintext1$env:ATLASCLOUD_API_KEY="tu-clave-api-de-atlas-cloud"
Para un uso a largo plazo en Windows, añade ATLASCLOUD_API_KEY en Propiedades del sistema → Variables de entorno.
Paso 3: Configurar CodeWiki para usar Atlas Cloud
CodeWiki ya incluye un proveedor dedicado atlas-cloud. Esto significa que no necesitas configurarlo manualmente como un endpoint genérico compatible con OpenAI.
Ejecuta:
plaintext1# Atlas Cloud: la URL base se establece automáticamente en https://api.atlascloud.ai/v1; 2# La clave API se lee desde $ATLASCLOUD_API_KEY cuando se omite --api-key. 3codewiki config set \ 4 --provider atlas-cloud \ 5 --main-model anthropic/claude-sonnet-4.8 \ 6 --cluster-model anthropic/claude-sonnet-4.8 \ 7 --fallback-model zai-org/GLM-5.2
En este modo, CodeWiki utiliza automáticamente la URL base de Atlas Cloud, https://api.atlascloud.ai/v1. Si se omite --api-key, CodeWiki lee la clave de la variable de entorno ATLASCLOUD_API_KEY.
Los IDs de modelo anteriores provienen del ejemplo de Atlas Cloud de CodeWiki. Las páginas de modelos de Atlas Cloud también muestran que los IDs de los modelos se pasan directamente en las solicitudes de API, por ejemplo anthropic/claude-sonnet-4.8 y zai-org/GLM-5.2.
Comprueba la configuración guardada:
plaintext1codewiki config show 2codewiki config validate
codewiki config show te permite inspeccionar la configuración actual, mientras que codewiki config validate comprueba si la configuración es válida. Ambos comandos se enumeran en la sección de configuración de CodeWiki.
Paso 4: Generar documentación para un proyecto
Navega hasta el repositorio que deseas documentar:
plaintext1cd /ruta/a/tu/proyecto
Luego ejecuta:
plaintext1codewiki generate
Por defecto, CodeWiki escribe la documentación generada en ./docs/. La salida incluye archivos como overview.md, documentación a nivel de módulo, module_tree.json, metadata.json y, cuando el visor HTML está habilitado, index.html.
Para generar un visor HTML que se pueda usar con GitHub Pages:
plaintext1codewiki generate --github-pages --create-branch
El archivo README de CodeWiki describe esto como el flujo de trabajo de GitHub Pages y señala que la documentación generada se colocará bajo ./docs/.
Ejemplo de uso
Puedes hacer clic en Demo en vivo para ver una demo interactiva y ejemplos.
Por qué CodeWiki funciona bien con Atlas Cloud para la documentación de repositorios
El proveedor integrado atlas-cloud de CodeWiki es útil porque la documentación de repositorios no suele ser una tarea para un solo modelo. El flujo de trabajo puede utilizar un modelo principal, un modelo de agrupación (clustering) y un modelo de respaldo, por lo que un proveedor unificado compatible con OpenAI reduce la fricción de probar y cambiar los IDs de los modelos durante la configuración.
Atlas Cloud es una plataforma que ofrece acceso unificado a más de 300 modelos a través de una API, un endpoint y una cuenta de facturación; su endpoint de LLM es compatible con OpenAI en /v1, lo que coincide con el tipo de integración que CodeWiki necesita para modelos de chat-completion.
Para los desarrolladores, la ventaja práctica es sencilla. En lugar de registrar cuentas separadas y reescribir la configuración específica del proveedor mientras pruebas la calidad de la documentación, puedes mantener el comando CodeWiki estable y cambiar los nombres de los modelos según sea necesario.
Por qué los agentes de codificación de IA del futuro necesitan un mejor contexto del repositorio
Las herramientas de programación con IA están mejorando rápidamente.
Pero generar código es solo una parte de la ingeniería de software.
Antes de modificar un sistema existente, un agente de IA necesita contexto:
- ¿Qué hace cada módulo?
- ¿Cómo interactúan los componentes?
- ¿Qué decisiones de diseño deben permanecer sin cambios?
Un flujo de trabajo posible se ve así:
plaintext1Repositorio 2 ↓ 3Capa de conocimiento 4 ↓ 5Agente de IA 6 ↓ 7Cambios en el código
La capa faltante no es otro generador de código.
Es un sistema que ayuda a la IA a comprender el software existente.
Herramientas como CodeWiki representan un enfoque hacia la construcción de esta capa de conocimiento del repositorio.
Preguntas frecuentes
¿Cómo puede la IA entender un repositorio de GitHub?
La IA puede entender mejor un repositorio de GitHub cuando el código base se analiza de forma estructural en lugar de procesar solo archivos individuales.
Las herramientas a nivel de repositorio ayudan a organizar la información sobre módulos, componentes y la estructura del proyecto.
¿Puede CodeWiki generar diagramas de arquitectura?
Sí. El README oficial enumera diagramas de arquitectura del sistema, visualizaciones de flujo de datos, gráficos de dependencias y diagramas de secuencia como artefactos visuales.
¿Dónde guarda CodeWiki la documentación generada?
Por defecto, la documentación generada se guarda en ./docs/. La estructura de salida documentada incluye overview.md, archivos de documentación de módulos, archivos JSON del árbol de módulos, metadatos y un visor opcional index.html.
¿Puede CodeWiki publicar documentación en GitHub Pages?
Sí. CodeWiki admite la salida para GitHub Pages con comandos como codewiki generate --github-pages --create-branch.
¿Qué modelo debería usar para CodeWiki?
Utiliza un modelo potente de programación o de contexto largo para el paso principal de documentación, y mantén configurado un modelo de respaldo. La configuración de CodeWiki admite modelos separados para la tarea principal, la agrupación y el respaldo, lo cual es útil porque la agrupación de módulos y la documentación extensa no siempre requieren el mismo tipo de modelo.
¿Es la salida de CodeWiki totalmente fiable?
No. Trata el resultado como documentación generada que requiere revisión de ingeniería. CodeWiki puede generar documentos y diagramas estructurados, pero aún debes verificar las afirmaciones sobre la arquitectura, los límites de los módulos y las descripciones del flujo de datos con el código fuente.
¿En qué se diferencia CodeWiki de pedirle a ChatGPT que explique un repositorio?
Un prompt de chat es útil para explicaciones ad hoc, pero CodeWiki está diseñado como un flujo de trabajo repetible a nivel de repositorio. Analiza la base de código, la descompone en módulos, genera documentación estructurada y puede producir artefactos visuales y un visor navegable.
Conclusión
CodeWiki es útil porque convierte la documentación del repositorio en un flujo de trabajo de ingeniería. Instálalo, configura el proveedor, ejecútalo en un repositorio real, inspecciona la descripción general y los documentos de los módulos generados, y luego publica el visor solo después de revisarlo.
Para los desarrolladores, la mayor ventaja no es que la IA escriba Markdown más rápido. La ventaja es que una base de código grande se vuelve más fácil de navegar: los módulos, dependencias, diagramas y notas de arquitectura se reúnen en un solo lugar, y el flujo de trabajo puede volver a ejecutarse a medida que el proyecto cambia.
