Lum1104/Understand-Anything es una herramienta de código abierto orientada a la comprensión de código. Puede analizar bases de código, bases de conocimiento o documentación y convertirlas en un grafo de conocimiento interactivo, para que puedas buscar, explorar nodos y hacer preguntas sobre la estructura del proyecto desde un Dashboard.
Cuando entras en un proyecto grande, lo difícil no suele ser que falte código, sino no saber por dónde empezar. Understand Anything escanea el proyecto, extrae archivos, funciones, clases, dependencias y relaciones de dominio de negocio, y después genera un grafo visual que ayuda a pasar de la vista global al detalle.
Qué problemas ayuda a resolver primero
Es especialmente útil para:
- Entender rápidamente la estructura modular de una base de código desconocida;
- Generar guías de onboarding para nuevos miembros del equipo;
- Revisar dependencias y alcance de impacto antes de una refactorización;
- Entender el posible alcance de un cambio antes de revisar código;
- Convertir una base de conocimiento o documentación del equipo en un grafo explorable;
- Añadir contexto de proyecto a entornos de programación con IA como Codex, Claude Code, Cursor y Copilot.
Para proyectos medianos y grandes, funciona como un mapa del proyecto. No sustituye el criterio de ingeniería, pero ayuda a encontrar puntos de entrada más rápido.
Instalación
En Claude Code, puedes instalarlo desde el mercado de plugins:
|
|
También soporta Codex, Cursor, VS Code + GitHub Copilot, Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity, Vibe CLI, Trae y otras plataformas.
En macOS / Linux, usa el script de instalación:
|
|
Para instalarlo directamente para Codex:
|
|
En Windows PowerShell:
|
|
El instalador clona el repositorio en:
|
|
También crea los enlaces necesarios para la plataforma elegida. Después de instalar, normalmente conviene reiniciar el CLI o el IDE.
Primer análisis de la base de código
Entra en el directorio del proyecto objetivo y ejecuta:
|
|
La herramienta escanea el proyecto, extrae archivos, funciones, clases y relaciones de dependencia, y genera:
|
|
Si quieres generar descripciones de nodos en chino y una interfaz de Dashboard en chino, especifica el idioma:
|
|
El proyecto también soporta opciones de idioma como:
|
|
En la primera ejecución, si no pasas --language, la herramienta detecta el idioma de la conversación actual y pide confirmación cuando hace falta. La elección se guarda en:
|
|
Las ejecuciones posteriores reutilizan esta configuración.
Qué directorios analizar primero
Si el proyecto es un monorepo, no hace falta analizar todo el repositorio en la primera ejecución. Es más prudente empezar por directorios clave y comprobar el tiempo de ejecución y la calidad del grafo.
Buenos objetivos iniciales:
src/: código de negocio principal en muchas aplicaciones monolíticas;apps/: puntos de entrada de frontend, backend o aplicaciones independientes en un monorepo;packages/: librerías compartidas, SDK, bibliotecas de componentes o módulos base;services/: directorios de servicios en proyectos de microservicios;backend/,frontend/: límites principales en proyectos separados por frontend y backend;docs/owiki/: objetivos separados cuando quieras analizar una base de conocimiento.
Por ejemplo, analiza solo la aplicación frontend:
|
|
O analiza solo un paquete compartido:
|
|
Esto evita escanear un monorepo completo desde el primer intento, especialmente cuando las dependencias son complejas o el grafo generado puede crecer mucho.
Abrir el Dashboard
Después de generar el grafo, ejecuta:
|
|
El Dashboard abre una página interactiva donde puedes:
- Mover y ampliar el grafo de conocimiento del proyecto;
- Buscar archivos, funciones, clases o conceptos semánticos;
- Hacer clic en nodos para ver resúmenes, relaciones y código;
- Ver grupos de arquitectura como API, Service, Data, UI y Utility;
- Seguir recorridos generados automáticamente para entender la estructura del proyecto.
Al leer un proyecto desconocido, empieza por la búsqueda del Dashboard. Por ejemplo, busca auth, payment, api, database o router, y luego sigue los nodos conectados.
Comandos comunes
Además de /understand y /understand-dashboard, estos comandos suelen ser útiles:
|
|
Corresponden aproximadamente a estas tareas:
/understand-chat: hacer preguntas sobre la base de código;/understand-diff: analizar qué partes del sistema se ven afectadas por los cambios actuales;/understand-explain: explicar en profundidad un archivo o función;/understand-onboard: generar una guía para nuevos miembros;/understand-domain: extraer dominios de negocio, flujos y pasos;/understand-knowledge: analizar una base de conocimiento o wiki.
Para una primera ejecución, usa este orden:
|
|
Así primero construyes una vista global y luego pasas a preguntas concretas.
Flujos de trabajo comunes
Entrar rápidamente en un proyecto desconocido
Ejecuta esto en la raíz del proyecto:
|
|
Después abre el Dashboard:
|
|
Revisa primero las capas de arquitectura y dependencias, y luego ejecuta:
|
|
Este flujo sirve para nuevos miembros y también para tareas temporales de mantenimiento.
Explicar un archivo clave
Si sabes que un archivo es importante pero no entiendes dónde encaja en el sistema, ejecuta:
|
|
Después usa el Dashboard para ver con qué módulos se conecta. Esto aclara mejor las relaciones aguas arriba y aguas abajo que leer el archivo aislado.
Analizar impacto antes de hacer commit
Después de cambiar código, ejecuta:
|
|
Ayuda a ver qué módulos podrían verse afectados por el cambio actual. No sustituye las pruebas, pero es útil como revisión estructural antes de hacer commit.
Compartir el mapa del proyecto con el equipo
El grafo generado por Understand Anything es JSON. Un equipo puede commitear los archivos necesarios de .understand-anything/ para que otros miembros eviten el primer análisis.
Normalmente es razonable commitear:
|
|
No se recomienda commitear:
|
|
Si el grafo es grande, usa Git LFS:
|
|
Al compartir grafos, recuerda dos cosas: primero, se quedan obsoletos cuando cambia el código y necesitan mantenimiento; segundo, pueden contener rutas de archivos, nombres de funciones, descripciones de negocio y resúmenes semánticos, así que conviene revisar si son apropiados antes de subirlos a un repositorio privado.
Diferencia con la documentación de arquitectura tradicional
La documentación de arquitectura tradicional suele ser estática. Su ventaja es que expresa bien el diseño objetivo, las restricciones, las decisiones y el contexto histórico. Su desventaja es que se desactualiza con facilidad. Tras unos meses de iteración, los límites de módulos, relaciones de llamada y estructura real del código pueden no coincidir con el documento.
Understand Anything se parece más a una capa de comprensión del proyecto generada automáticamente. Extrae relaciones estructurales de código y documentación, y las muestra como grafo de conocimiento. Su ventaja es que puede regenerarse para reflejar el estado actual del proyecto. Su limitación es que las explicaciones generadas siguen necesitando revisión humana y no sustituyen las decisiones de diseño, el contexto histórico ni las convenciones del equipo.
Una combinación práctica:
- Usar documentación tradicional para registrar diseño objetivo, restricciones, decisiones e historia de evolución;
- Usar Understand Anything para generar estructura actual del código, dependencias y grafo buscable;
- Tratar las diferencias entre ambos como deuda documental o arquitectónica.
Diferencias con Sourcegraph, DeepWiki y Cursor
Estas herramientas ayudan a entender código, pero sus puntos de entrada son distintos.
Sourcegraph está más orientado a búsqueda de código, navegación entre repositorios y búsqueda por símbolos. Es útil para localizar implementaciones en muchos repositorios. DeepWiki se centra más en convertir un repositorio en documentación automática legible, útil para obtener una visión documentada rápida. La comprensión de proyecto de Cursor está más cerca del flujo de trabajo dentro del editor, donde preguntas y modificas código sin salir del IDE.
Understand Anything destaca por convertir explícitamente la base de código en un grafo de conocimiento y ofrecer Dashboard, recorridos guiados, análisis de impacto y análisis de bases de conocimiento. Encaja cuando quieres ver primero el mapa del proyecto y luego entrar al detalle del código.
En resumen:
- Búsqueda de código entre repositorios: Sourcegraph;
- Documentación automática del proyecto: DeepWiki;
- Preguntar y programar dentro del editor: Cursor;
- Convertir estructura, dependencias y relaciones de negocio en un grafo: Understand Anything.
No es una comparación rígida. En el trabajo real, estas herramientas pueden combinarse.
Privacidad y riesgos en repositorios privados
Antes de usar este tipo de herramienta en una base de código privada, revisa la política de datos de la plataforma de IA conectada. Presta atención a:
- Si fragmentos de código, rutas de archivos o nombres de funciones se envían a modelos externos;
- Si los resúmenes y grafos generados contienen información sensible de negocio;
- Si las políticas de retención de datos cambian entre cuentas empresariales, de equipo y personales;
- Si el uso de LLM externos está permitido en el proyecto actual;
- Si los archivos generados en
.understand-anything/se subirán al repositorio remoto.
Si el proyecto incluye datos de clientes, secretos comerciales, lógica de producto no publicada o requisitos de cumplimiento, empieza con ejemplos anonimizados, proyectos open source o directorios internos aprobados antes de conectarlo a un repositorio privado real.
Cuándo no conviene usarlo
Understand Anything no es necesario para todos los proyectos. Puedes evitarlo cuando:
- El proyecto es pequeño y leer el código directamente es más rápido;
- La estructura del código es muy caótica y carece de nombres, módulos o documentación que ayuden a interpretar el resultado;
- Nadie del equipo mantendrá el grafo después de generarlo una vez;
- Solo necesitas revisar una función o un error concreto;
- La política de seguridad del repositorio privado no permite enviar contexto de código a servicios externos de IA;
- La tarea actual ya tiene un punto de entrada claro y la herramienta añade coste de proceso.
Lo más prudente es probar primero en directorios clave, confirmar calidad del grafo, tiempo de ejecución y límites de privacidad, y solo después decidir si analizar todo el repositorio.
Cómo funciona por dentro
Understand Anything combina Tree-sitter y LLM:
- Tree-sitter se encarga del análisis estructural determinista, como import/export, funciones, clases, puntos de llamada y herencia;
- Los LLM se encargan del contenido semántico, como resúmenes en lenguaje natural, etiquetas, capas de arquitectura, mapeo de dominios de negocio y explicaciones guiadas;
/understandcoordina varios agentes, incluyendo escaneo del proyecto, análisis de archivos, análisis de arquitectura, generación de recorridos y validación del grafo;- Las actualizaciones incrementales solo vuelven a analizar archivos modificados, lo que facilita mantener el grafo en el tiempo.
Esta combinación reduce el riesgo de depender solo de conjeturas del LLM sobre la estructura del proyecto, manteniendo a la vez explicaciones legibles en lenguaje natural.
Límites de uso
Estas herramientas sirven para ayudar a entender, pero no sustituyen el criterio de ingeniería:
- La calidad del grafo depende de la estructura del proyecto, el soporte de lenguaje y los resultados del análisis;
- Las explicaciones de negocio generadas por LLM necesitan revisión humana;
- El primer análisis de repositorios grandes puede tardar;
- Antes de usarlo con código privado, confirma las políticas de datos y privacidad de la plataforma de IA conectada;
- Los proyectos pequeños quizá no necesiten un grafo completo.
Resumen
El valor de Understand Anything está en convertir la lectura de código en exploración de un mapa del proyecto. Después de instalarlo, ejecuta /understand para generar el grafo, ábrelo con /understand-dashboard y usa /understand-chat, /understand-diff y /understand-explain para preguntas concretas.
Si trabajas a menudo con bases de código desconocidas, mantienes proyectos grandes o necesitas onboarding para el equipo, merece la pena probarlo. En entornos de programación con IA como Codex, Claude Code, Cursor y Copilot, las herramientas de grafo de conocimiento como esta pueden convertirse en parte del flujo de comprensión de código.