Este capítulo es una guía visual de las dos vistas de grafo de AITM: el Contract Explorer (un mapa de todos los Behavioral Contracts de un proyecto) y App Flow (un mapa de cómo un elemento concreto de la aplicación se relaciona con todo lo demás). Explica qué muestra cada grafo, cómo leer los nodos, los colores y las líneas de conexión, qué significa la leyenda y para qué sirven realmente ambas vistas.

Contract Explorer & App Flow

Si todavía no se sabe qué es un Contract o el knowledge graph, conviene leer primero Contracts, Knowledge Graph & Hints. Este capítulo se apoya en él y se centra únicamente en cómo navegar las dos visualizaciones.

Contract Explorer: el mapa de Contracts del proyecto

Para qué sirve: el Contract Explorer es un grafo interactivo de todos los Behavioral Contracts de un proyecto: los hechos almacenados sobre cómo se comporta cada parte del código. En una sola pantalla se ve cuánto conocimiento tiene AITM sobre el proyecto, cómo de bien lo cubren las pruebas, qué módulos son los más grandes y cómo se conectan los Contracts con archivos, variables y documentación. Es la forma más rápida de responder a "¿qué sabe AITM de mi proyecto?" y de ver dónde están los puntos débiles (Contracts sin pruebas o con pruebas fallidas).

Dónde encontrarlo: en el panel del proyecto, hacer clic en la subpestaña Contracts (las subpestañas del proyecto son Develop, Testing, Archive, Setting, Optimize, Contracts, Graph y Multi Graph). La subpestaña vecina Graph dibuja el grafo de código del proyecto y Multi Graph lo dibuja para todos los proyectos de la pestaña a la vez (solo aparece cuando la pestaña tiene más de un proyecto).

Qué hay en la pantalla

La pantalla tiene cuatro áreas principales:

• Barra superior: pestañas de conjuntos de datos, estadísticas de resumen y botones de acción.
• Barra lateral izquierda: búsqueda, filtros de módulos y la lista de Contracts.
• Área principal del grafo: el grafo interactivo (zoom con la rueda del ratón, desplazamiento arrastrando; los nodos se pueden arrastrar).
• Leyenda (panel superpuesto en la parte inferior izquierda del grafo): explica los colores de los nodos y los tipos de línea.

Barra superior: pestañas y estadísticas

Niveles de visualización: Module View frente a All Contracts

Encima del grafo hay un selector de nivel de detalle:

• Module View (la opción predeterminada en proyectos grandes, de más de 500 Contracts): cada nodo es un módulo completo (p. ej., "AI Chat", "Backup Service"). El tamaño de la burbuja refleja el número de Contracts del módulo; las líneas entre módulos indican que comparten archivos de código fuente. Es la "vista aérea", el punto de partida ideal.
• Al hacer clic en un módulo se profundiza en el Module Detail: el grafo muestra los Contracts individuales del módulo seleccionado.
• All Contracts: el grafo completo de todos los Contracts a la vez. En proyectos grandes se limita a 500 nodos por rendimiento (una insignia muestra el recuento, con un enlace "Show all" para omitir el límite deliberadamente).

En la esquina superior derecha del grafo hay además un selector de renderizador: SVG, Sigma (predeterminado: WebGL, admite grafos grandes), 3D, Cosmo y deck.gl. No cambia la funcionalidad, solo cómo se dibuja el grafo; si el grafo va a tirones en un proyecto grande, conviene elegir Sigma.

Lectura del grafo: nodos

Cada nodo (círculo) es una entidad. El color indica el tipo y, en el caso de los Contracts, indica a la vez el estado de las pruebas:

Un nodo más grande indica una entidad más significativa (un módulo con más Contracts, un Contract de zona de peligro, etc.).

Lectura del grafo: líneas (relaciones)

Las líneas entre nodos significan "estas dos cosas están relacionadas". El tipo de relación se codifica en el estilo de línea:

Lectura práctica: las líneas continuas son relaciones en el código; las líneas discontinuas son relaciones a través de la documentación. Una línea discontinua que sale de un Contract significa que existe documentación escrita para él: al hacer clic en el nodo naranja se abre dentro de la propia aplicación.

Leyenda

La leyenda (panel en la parte inferior izquierda del grafo) resume exactamente lo descrito arriba: colores de nodos y tipos de conexión. Para los tres estados de Contract muestra además recuentos y porcentajes en vivo (p. ej., Tested (passing) 4/2403 (0%)): cuántos Contracts del conjunto mostrado actualmente están en cada estado. Los números se recalculan con el filtro activo: en Module View se refieren a los módulos en pantalla y, tras profundizar en un módulo, a sus Contracts.

Barra lateral izquierda

• Search: búsqueda de texto completo en los ids de Contract, las descripciones de comportamiento, los archivos y las variables.
• Filters / Groups: alterna entre el filtro de módulos (botones con los nombres de los módulos; All borra el filtro) y un árbol agrupado.
• Lista de Contracts (abajo): se rellena con los Contracts del módulo seleccionado. Cada fila tiene un punto de color con la misma semántica que los nodos del grafo (verde/rojo/ámbar), además de un icono para los Contracts en una zona de peligro (lugares donde un cambio pequeño causó históricamente un daño desproporcionado).

Detalle del Contract

Al hacer clic en un Contract (en el grafo o en la lista) se abre la ventana de detalle del Contract:

En la parte superior del detalle hay dos botones importantes:

• Assembled doc: abre el documento ensamblado completo del Contract.
• Flow: salta directamente a la vista App Flow (véase más abajo), centrada en la primera variable del Contract. Es el puente entre las dos visualizaciones: de "qué se cumple" (el Contract) a "cómo encaja en la aplicación" (el flujo).

App Flow: el mapa de relaciones de un elemento

Para qué sirve: mientras que el Contract Explorer muestra el proyecto desde arriba, App Flow responde a "¿cómo se relaciona este elemento concreto con el resto de la aplicación?". Se ven todas las variables del lenguaje de comunicación vecinas del elemento: por su namespace, por Contracts compartidos, por archivos compartidos y por navegación de la interfaz. Es la herramienta ideal para estimar el impacto de un cambio ("si toco esto, ¿qué más se ve afectado?") y para redactar prompts de Task precisos.

Dónde encontrarlo:

1. Desde el Dev Panel: en la aplicación en ejecución, hacer clic en un elemento; se abre su ventana de detalle con las pestañas Graph | Guide & Flow | App Flow.
2. Desde el Contract Explorer: mediante el botón Flow del detalle del Contract (véase arriba).

Qué hay en la pantalla

• Columna izquierda: los datos del elemento inspeccionado: nombre, descripción, capa y, sobre todo, la lista de Contracts que lo rigen (con id, estado de las pruebas, salud, archivos y puntuación). Es la misma información que en el Contract Explorer, pero desde el punto de vista de un único elemento.
• Centro: grafo: un grafo interactivo con el elemento inspeccionado en el centro y las variables relacionadas a su alrededor.
• Panel derecho: filtros por tipo de relación (casillas de verificación) y la lista de variables relacionadas, que refleja el grafo en forma de lista legible.

Lectura del grafo: nodos

Lectura del grafo: colores de las aristas (tipos de relación)

Cada línea se colorea según por qué están relacionadas las variables:

Panel derecho: filtros y lista

En la parte superior hay cuatro casillas de verificación (Namespace, Contract, File, Navigation) que filtran tanto el grafo como la lista. De forma predeterminada están marcadas Namespace + Contract (las relaciones más útiles y con menos ruido); File y Navigation se activan cuando hace falta rastrear conexiones a través del código o del flujo de la interfaz.

Cada fila de la lista muestra el código de la variable, el nombre y las insignias de tipo de relación. El botón (insert into prompt) fija el código de la variable directamente en el prompt de Task que se está redactando; así, el flujo de trabajo típico es: encontrar el elemento en la aplicación → inspeccionar su App Flow → fijar las variables relacionadas → describir el cambio. El Agent de IA recibe entonces las direcciones exactas de los lugares a los que afecta el cambio y no tiene que buscarlos.

Leyenda y ayuda

En la parte inferior izquierda del grafo está la leyenda, que resume los estilos de nodo y los colores de arista (exactamente como se describe arriba). En la parte superior derecha está el botón (?), que abre una ventana emergente de ayuda donde se explica qué muestra App Flow y cómo se deriva cada tipo de relación:

Guide & Flow: el flujo de lógica de negocio

Junto a App Flow, el detalle del elemento tiene una pestaña Guide & Flow. Explica el elemento seleccionado de arriba abajo en pasos sencillos (el propio elemento de interfaz y después los Contracts de negocio que describen su comportamiento, cada uno con las variables a las que afecta), y el botón Copy as Markdown copia toda la explicación al portapapeles, lista para pegar en un prompt de Task.

AITM Dev Panel

Qué es: una pequeña barra de herramientas flotante que AITM puede inyectar en la aplicación web de un proyecto que gestiona. Mientras se usa la aplicación en el navegador, el panel actúa como los ojos de AITM dentro de ella: registra los elementos de interfaz etiquetados que ve (construyendo el mapa del proyecto con pantallas, botones y diálogos del que se alimentan el Contract Explorer y App Flow) y captura los errores de JavaScript de la consola del navegador y los envía a AITM, donde aparecen para el proyecto y pueden convertirse en Tasks de error.

Cómo llega hasta allí: el panel es un único script servido por el servidor de AITM e incluido en la página de la aplicación en modo de desarrollo. El New Project Wizard lo añade automáticamente a los proyectos web que crea; el propio Dashboard de AITM también lo tiene.

Qué se ve: cuatro pestañas:

• Elements: los elementos en los que se hizo clic o que se fijaron, cada uno con su código de variable, los Contracts y archivos que hay detrás, y las advertencias de los Contracts de zona de peligro. Overlay resalta todos los elementos etiquetados de la página; Pin / One Pin reúnen elementos para un prompt; los iconos de cada fila copian el código, abren el detalle del elemento (Graph, Guide & Flow, App Flow) y quitan el pin. Clear Pins vacía la lista.
• Records: los elementos de interfaz que el panel ha registrado de la página.
• Errors: errores de JavaScript y de consola capturados en este navegador, con el recuento en el nombre de la pestaña.
• Settings: las opciones propias del panel.

El panel solo aparece en modo de desarrollo y está pensado para las personas desarrolladoras y los Agents de IA, no para los usuarios finales de la aplicación. Su documentación completa se abre desde el menú de la cabecera: Help → AITM Dev Panel. Los tamaños de fuente del panel se pueden ajustar en Settings → Font & Style.

Flujos de trabajo prácticos

Encontrar los puntos débiles de un módulo: Contracts → Module View → clic en un módulo → buscar en el grafo los nodos ámbar (sin pruebas) y rojos (con pruebas fallidas). La leyenda ofrece los porcentajes de un vistazo.

Estimar el impacto de un cambio antes de crear una Task: encontrar el elemento en la aplicación mediante el Dev Panel (o un Contract en el Contract Explorer y el botón Flow) → App Flow → activar las relaciones contract y file → todo lo conectado puede verse afectado por el cambio.

Redactar un prompt preciso: en App Flow, fijar las variables relevantes en el prompt; la Task habla entonces un lenguaje que entienden tanto la persona usuaria como los Agents de IA del Pipeline (el lenguaje de comunicación).

Comprobar si un comportamiento está documentado: en el Contract Explorer, seguir las líneas discontinuas desde un Contract: conducen a documentos (nodos naranjas) que se abren con un clic dentro de la propia aplicación.