Crea una herramienta local de grafo de código que los agentes de IA puedan consultar

## Construye el grafo de código en local desde el árbol de sintaxis, no con resúmenes de IA Mantén el análisis del proyecto local y determinista. Deriva los símbolos, las relaciones y los archivos de los árboles sintácticos en lugar de resúmenes generados por modelos de lenguaje, almacena el estado limitado al proyecto en una base de datos local indexada y expón el grafo de conocimiento resultante mediante una biblioteca, una interfaz de línea de comandos o un protocolo para agentes. Organiza el sistema como una canalización por capas: - la extracción analiza el código fuente y emite símbolos canónicos; - la resolución conecta importaciones, nombres, frameworks y otras relaciones; - las consultas del grafo responden sobre llamadores, llamados, rutas e impacto; - el formateo del contexto prepara Markdown o JSON compacto para los consumidores. Mantén el análisis pesado fuera del hilo principal. Conduce las capas por un único punto de entrada público y haz que este sea la única superficie admitida de la biblioteca. Si un ejecutable actúa intencionadamente como instalador, indexador y servidor de protocolo, prueba todas esas funciones mediante el mismo artefacto. Mantén una única fuente de verdad para las instrucciones de las herramientas destinadas a agentes, preferiblemente la respuesta de inicialización del protocolo. No dupliques las mismas instrucciones en el archivo de repositorio de cada cliente, porque las copias divergen y dejan incompletas las actualizaciones o la desinstalación. ## Fija la versión del entorno de ejecución e incluye en la build los archivos que no son código Descubre y utiliza los comandos documentados del repositorio de compilación, desarrollo, limpieza, prueba, evaluación y CLI local. Respeta el intervalo fijado del entorno de ejecución y produce un error claro fuera de él; una versión principal más reciente no es compatible de forma automática, y la ejecución desde el código fuente puede exigir un mínimo más estricto que una distribución empaquetada. Trata los recursos de ejecución como parte del contrato de compilación. Copia los esquemas de base de datos, las gramáticas de los analizadores, los módulos WebAssembly y otros archivos que no sean código en la distribución. Cada vez que añadas un recurso, actualiza el paso de copia o no se incluirá en la distribución. Empieza la verificación con un archivo de prueba o un patrón de nombre específico y luego ejecuta la suite directamente afectada. Mantén separadas las suites de evaluación cuando construyan fixtures o puntúen el comportamiento, en lugar de ejecutar pruebas unitarias ordinarias. Usa el comportamiento real del almacenamiento cuando su semántica sea importante. Crea directorios temporales aislados, límpialos después de cada prueba y verifica el modo real de la base de datos en vez de ocultarlo con simulaciones. ## Unifica los tipos de nodos y aristas y mantén pequeña la API pública Define los tipos canónicos de nodo y arista en un solo esquema. Los extractores y los mecanismos de resolución deben emitir exactamente esas cadenas; no introduzcas variantes casi duplicadas que dividan silenciosamente las consultas, el recorrido o los datos serializados. Mantén reducida la API pública. Vuelve a exportar los tipos admitidos desde el punto de entrada público y exige que los adaptadores de línea de comandos y protocolo utilicen el mismo servicio central en vez de eludirlo. Haz que las afirmaciones sobre el almacenamiento sean explícitas y verificables. Si el producto solo admite un backend de base de datos con registro de escritura anticipada y búsqueda de texto completo, informa de ese backend activo, mantén delgado cualquier adaptador de compatibilidad y no insinúes que existe un mecanismo alternativo nativo o WebAssembly que no se haya implementado. Al añadir un lenguaje, un framework, una consulta o un campo de esquema, actualiza conjuntamente el extractor o mecanismo de resolución responsable, el contrato público, la serialización, las pruebas y las instrucciones para usuarios. ## Instala en varios clientes de IA sin romper su configuración y desinstala sin dejar rastro Modela cada cliente admitido como un destino con su propia ubicación de configuración, formato y argumentos de protocolo. Añade un cliente nuevo mediante una implementación de destino y una entrada de registro, en lugar de dispersar condiciones por el instalador. Edita la configuración de forma selectiva. Conserva las tablas y los arreglos TOML no relacionados, mantén el formato y los comentarios del JSON con comentarios, prefiere una variante de archivo compatible que ya exista y crea el valor predeterminado documentado únicamente para una instalación nueva. La instalación debe ser idempotente, la reinstalación debe reparar por sí sola un estado parcial y la desinstalación solo debe revertir los cambios que pertenezcan al instalador. Utiliza marcadores estables para retirar bloques de instrucciones obsoletos, pero conserva las instrucciones actuales para agentes en su única fuente en tiempo de ejecución en vez de escribir otra copia. Cubre cada destino con pruebas de contrato parametrizadas sobre conservación de configuraciones adyacentes, repeticiones idénticas byte a byte, desinstalación reversible y recuperación de estados parciales. Conserva las correcciones del directorio de trabajo propias de cada cliente, como inyectar una ruta de proyecto explícita cuando el cliente inicia subprocesos de protocolo desde un directorio incorrecto. ## Mejora las herramientas de búsqueda que los agentes ya usan Antes de crear una función de recuperación de información, comprueba si permite que una herramienta que el agente ya utiliza haga más con la entrada que el agente ya proporciona. No dependas de que el agente aprenda una herramienta nueva, adopte otro estilo de consulta o advierta ejemplos y explicaciones de inicialización poco visibles. Usa entradas precisas para obtener respuestas precisas. Una herramienta principal de exploración debe aceptar un conjunto compacto de nombres de símbolos, incluidos nombres cualificados, y conectar el flujo entre ellos. Una herramienta secundaria de nodos debe devolver el código fuente completo junto con el contexto de llamadores y llamados; si un nombre es ambiguo, debe devolver todas las sobrecargas plausibles en una sola respuesta. No integres respuestas precisas sobre flujos en una herramienta imprecisa de lenguaje natural que no pueda desambiguar los extremos. Mejora la cobertura bajo las herramientas que los agentes ya eligen, incluida la extracción estática y las relaciones dinámicas basadas en pruebas. Optimiza la latencia de extremo a extremo y la cantidad de llamadas a herramientas, además del uso de tokens. Mide el uso total de todos los turnos, no solo la respuesta final, porque el ahorro procede de menos turnos sobre un contexto acumulado más pequeño. ## Devuelve respuestas para que el agente no vuelva a leer archivos directamente Da a las condiciones esperadas una forma de éxito. Un proyecto sin indexar, un símbolo ausente o un archivo fuera del índice deben devolver orientación práctica sin una marca de error. Reserva los errores reales para rechazos de seguridad y fallos auténticos, y adjunta una instrucción de reintento limitada solo cuando proceda reintentar. Expón la superficie de herramientas incluso cuando la raíz actual no esté indexada. Explica cómo seleccionar un proyecto indexado, pero deja que el usuario decida si debe indexarse. Ocultar las herramientas al iniciar puede romper monorepos y sesiones que comenzaron antes de la indexación. Aumenta de forma monotónica los presupuestos de llamadas de exploración y de salida según el tamaño del repositorio: - menos de 500 archivos: 1 llamada, unos 18,000 caracteres y 3,800 caracteres por archivo; - 500–4,999 archivos: 2 llamadas, unos 28,000 caracteres y 6,500 caracteres por archivo; - 5,000–14,999 archivos: 3 llamadas, unos 35,000 caracteres y 7,000 caracteres por archivo; - 15,000–24,999 archivos: 4 llamadas, unos 38,000 caracteres y 7,000 caracteres por archivo; - 25,000 archivos o más: como máximo 5 llamadas, unos 38,000 caracteres y 7,000 caracteres por archivo. Un nivel mayor nunca debe recibir un presupuesto por archivo menor que un nivel inferior. Nunca indiques al agente que vuelva a la lectura directa de archivos; dirígelo a otra llamada al grafo y aclara que debe considerar ya leído el código fuente devuelto. ## Conecta de principio a fin los flujos de callbacks y eventos El análisis estático omite callbacks, observadores, emisores de eventos, renderizado reactivo, descriptores y otros tipos de despacho indirecto. Añade sintetizadores de alcance reducido o mecanismos de resolución de frameworks solo cuando puedan conectar el flujo canónico con pruebas defendibles. Marca cada arista sintetizada como heurística, registra qué mecanismo la produjo e incluye el punto de registro o conexión. Muestra esa procedencia junto con el flujo para que los consumidores distingan los hechos analizados de las relaciones inferidas. La cobertura parcial es peor que no tener ninguna cuando muestra un salto indirecto pero deja roto el límite siguiente. Cierra el flujo desde la acción inicial hasta su efecto visible, vuelve a medir el agente y no distribuyas una ruta conectada a medias que todavía obligue a reconstruirla manualmente. Prefiere el silencio a una arista incorrecta en límites del entorno de ejecución que no puedan inferirse de forma segura. Verifica que la reindexación no infle la cantidad de nodos y comprueba una muestra de la precisión de las aristas sintetizadas antes de ampliar un mecanismo de resolución. ## Prueba el comportamiento del agente en repositorios reales, Windows y Linux Para cada lenguaje y framework, prueba repositorios reales pequeños, medianos y grandes con al menos 3 preguntas de flujo diferentes. Elige un flujo canónico de extremo a extremo para cada framework, en lugar de símbolos aislados que eviten sus límites difíciles de despacho. Ejecuta sondeos deterministas sobre el artefacto compilado. Confirma que la exploración conecta los extremos esperados dentro del presupuesto, que la cantidad de nodos permanece estable tras reindexar y que las aristas heurísticas incluyen una procedencia precisa. Ejecuta pruebas A/B del agente al menos 2 veces por grupo con el mismo modelo de capacidad mínima elegido deliberadamente y el mismo esfuerzo de razonamiento. Registra la duración, el total de llamadas a herramientas, las lecturas directas de archivos y las búsquedas de texto; informa de intervalos en lugar de elegir una única ejecución favorable. Precalienta un proceso de protocolo persistente cuando la latencia de arranque pudiera ocultar la herramienta y determina la conexión por las llamadas reales, no por una instantánea de inicialización. Exige aproximadamente cero lecturas directas y búsquedas dentro del presupuesto de exploración del repositorio, una finalización más rápida que el control y ninguna regresión en un repositorio de control. Valida el comportamiento específico de cada plataforma en la plataforma real. Separa explícitamente las aserciones exclusivas de Windows de las exclusivas de plataformas distintas de Windows. En Linux, compila con dependencias nuevas y nativas de la plataforma dentro de un contenedor desechable, y usa un proceso init para recoger los procesos secundarios terminados. En Windows, utiliza un sistema de archivos local y dependencias nuevas dentro de una máquina virtual real; compara los fallos sospechosos con la rama predeterminada antes de atribuirles una causa. ## Escribe las notas de versión y deja la publicación al flujo de publicación automático Escribe los próximos cambios en una sección Unreleased. No crees por adelantado el bloque de la versión siguiente cuando el flujo de publicación ascienda automáticamente el contenido de Unreleased. Haz que las notas de publicación resulten útiles: - agrupa el contenido bajo encabezados de funciones, correcciones, seguridad o cambios incompatibles orientados al usuario solo cuando corresponda; - escribe una frase sencilla por viñeta que explique la capacidad o el síntoma resuelto; - omite rutas internas, símbolos de implementación, detalles de pruebas de rendimiento y secciones vacías; - conserva referencias útiles a incidencias, nombres de plataformas compatibles y comandos que los usuarios realmente introducen. Deja que el flujo de publicación automatizado sincronice las versiones del archivo de bloqueo, ascienda el registro de cambios, compile paquetes para cada plataforma, genere sumas de comprobación, publique la versión y publique los paquetes. No incrementes versiones salvo que se solicite explícitamente, y no publiques paquetes, envíes commits de publicación ni crees etiquetas de forma manual cuando esas acciones pertenezcan al flujo de trabajo. Antes de actuar sobre una incidencia, un comentario de revisión o un informe externo, vincúlalo a una fecha y compara el estado publicado, el estado fusionado pero aún no publicado y la rama actual. No atribuyas una corrección en curso a lo que el informante podía ver anteriormente. Trata los requisitos del producto como decisiones del usuario, no como hechos inferidos del grafo de código. Añade una versión a cada URL de imagen de la documentación e incrementa su etiqueta de consulta cada vez que cambie el recurso para impedir que las cachés sigan sirviendo bytes obsoletos.