Blog de Maguyva

Un contexto que viaja

Mon, 07 Sep 2026 00:00:00 GMT

El indexador de Cursor es excelente dentro de Cursor. El autocompletado, la edición en línea, el chat y el agente en esa ventana ya se apoyan en un índice de proyecto que Cursor gestiona para el espacio de trabajo abierto. Si Cursor es la única superficie en la que escribes, y ese índice ya encuentra los archivos correctos, quédate ahí. Ese es el caso honesto de «quédate donde estás», y con razón es la primera frase de esta página.

Este artículo trata de la otra mitad de una semana común. El mismo repositorio también se abre en Claude Code, se consulta desde Codex CLI, se revisa en una segunda máquina, o lo consulta un agente que corre en CI. La pregunta no es «qué indexador es mejor». La pregunta es si el mapa en el que confía el agente en una ventana es el mismo en el que confía en la siguiente.

Maguyva es ese mapa que viaja. Es una capa de contexto de código MCP remota. El agente la consulta igual que consulta cualquier otra herramienta MCP. Los resultados vuelven como rutas clasificadas con números de línea. Cursor sigue siendo el editor. El contexto es lo que se mueve.

Para qué sirve el indexador de Cursor

La indexación integrada de Cursor existe para que el chat, el agente y la búsqueda dentro del editor puedan recuperar código relevante en lugar de depender solo de lo que cabe en la ventana de contexto en bruto del modelo. Ese es el diseño correcto para un IDE. El índice es nativo de Cursor. No es un servidor MCP y no es accesible desde ningún otro cliente.

Así funciona, según la documentación pública de Cursor y el propio relato de Cursor en el momento de escribir esto: la ruta de búsqueda principal ya no es un índice de embeddings en la nube. El equipo de Cursor declaró en su foro comunitario que la búsqueda semántica/basada en embeddings dedicada se está retirando en favor de la recuperación basada en grep, porque los modelos actuales buscan lo bastante bien en un árbol vivo por sí solos. En su lugar está Instant Grep, un índice de búsqueda local construido con n-gramas, listas invertidas y filtros de Bloom, mantenido en una tabla de búsqueda mapeada en memoria, de modo que las consultas se resuelven en la propia máquina del desarrollador en lugar de en un servidor.

El índice en sí vive dentro del propio directorio .git/cursor/ del repositorio, anclado a un commit de git específico; los cambios desde ese commit se superponen en lugar de disparar un nuevo escaneo, y el índice solo se reconstruye cuando el estado local se ha alejado mucho de aquello contra lo que se construyó. Como está dentro de .git, nunca se rastrea ni se sube — borra la carpeta y el índice desaparece. .gitignore se respeta por construcción, ya que solo el contenido rastreado por git es elegible, y .cursorignore se aplica en la ruta de lectura. Ya no hay ningún paso de embedding del lado del servidor ni base de datos vectorial remota en esa ruta. La documentación anterior describía un diseño asistido por la nube — cifrado de fragmentos, sincronización por árbol de Merkle, reutilización de índices entre compañeros de equipo — y el propio equipo de Cursor ha dicho desde entonces que ese diseño se está retirando, así que este artículo ya no lo describe como vigente.

Una característica destacada dentro del editor es el subagente Explore de Cursor. Puede lanzar varias búsquedas paralelas en su propia ventana de contexto, con un modelo más rápido, y devolver solo los hallazgos relevantes, de modo que la conversación principal no se llene de resultados de búsqueda. Es una fortaleza genuina dentro del editor. Consérvala.

Los espacios de trabajo multi-raíz están soportados: el contexto de cada carpeta abierta está disponible para el Agente. Algunas funciones dependientes de git, como los worktrees, están desactivadas en configuraciones multi-raíz, y los Cloud Agents no soportan en absoluto los espacios de trabajo multi-raíz.

Nada de esto es una razón para abandonar Cursor. Es una descripción precisa de un mapa que es excelente donde vive.

Qué significa realmente «viajar»

Un mapa viaja cuando las mismas preguntas devuelven el mismo tipo de respuesta, con citas que puedes abrir, desde más de un cliente.

En Cursor: «¿Dónde está definido parseConfig, y quién lo llama?»
En Claude Code, en el mismo repo: la misma pregunta.
En Codex CLI, en una máquina de revisión que nunca abrió la ventana de Cursor: la misma pregunta.
En un agente de CI que habla MCP: la misma pregunta, contra el mismo snapshot alojado.

Si cada superficie construye su propio índice privado, no tienes un mapa. Tienes varias cachés que divergen. El índice del editor puede estar al día para el árbol en disco. La sesión de CLI puede llevar un día de retraso. El trabajo de CI puede estar mirando un checkout distinto. El agente seguirá sonando seguro de sí mismo de todos modos.

El indexador de Cursor no está pensado para resolver eso. Como vive dentro del editor, el contexto que construye es para ese editor. Un lector que también necesita una CLI, un pipeline de CI o un editor distinto necesita una herramienta separada para esas superficies. Eso es un hecho de alcance, no un defecto. Maguyva es esa herramienta separada.

Un recuento publicado de lenguajes para el indexador de Cursor no aparece en las notas que este borrador puede usar. Maguyva publica más de 279 lenguajes y tecnologías basadas en texto. El precio de Cursor tampoco se copia aquí; consulta su página de precios. Maguyva cobra por espacio de trabajo, no por asiento, con planes publicados de $0, $19, $49 y $149 según la huella indexada y el tamaño del espacio de trabajo.

Un mapa alojado, todos los clientes MCP

Maguyva es un servidor MCP remoto. Conectas GitHub, eliges los repositorios, y el pipeline en la nube construye símbolos, aristas del grafo y un mapa clasificado. Añades una clave de API a la configuración MCP del cliente que ya usas. Maguyva tiene guías de configuración para 24 clientes MCP documentados — Cursor incluido — y puede conectarse a otros clientes compatibles con MCP que soporten la configuración estándar.

La página de configuración de Cursor es la ruta específica del editor si ahí es donde trabajas. El mismo servidor responde a Claude Code, VS Code, Windsurf, Codex CLI y el resto. No cambias de editor. Le das a cada agente la misma superficie de herramientas: 11 herramientas MCP de cara al cliente en búsqueda, símbolos, análisis de dependencias, recuperación de archivos, contexto de repositorio y flujos de trabajo utilitarios deterministas. La recuperación semántica, estructural, por grafo y de texto se fusionan en resultados clasificados.

Ese es el beneficio de la portabilidad. Las citas que evaluaste en Cursor esta mañana tienen la misma forma que las citas que Codex CLI devolverá esta noche. Ruta de archivo y número de línea. Ábrelas. Si están mal, lo ves. Si están bien, el siguiente cambio tiene un lugar donde aterrizar. La afirmación aprobada es menos ediciones alucinadas, no la promesa de que cada edición sea correcta.

La frescura está publicada. Los snapshots llevan marca de tiempo, así que el agente sabe qué versión del árbol está leyendo. La cadencia de reconstrucción es diaria en el plan gratuito y cada hora en los planes de pago. El límite honesto es el trabajo local no sincronizado: una edición que solo existe en un árbol de trabajo aún no está en el mapa alojado. Ese límite es el mismo sin importar desde qué cliente consultes, y ese es justamente el punto. La deriva entre clientes ya no es un segundo límite oculto.

La documentación da el bucle de activación que aplica a cada cliente: indexar un repo que ya conoces, conectar el cliente, hacer una pregunta que puedas verificar. Hazlo una vez en Cursor. Hazlo de nuevo desde la CLI que realmente usas en días de revisión. Si ambas respuestas citan el mismo handler, el mapa viajó.

Cómo conviven los dos mapas

Usa ambos. No son alternativas en el sentido de una página de comparación.

Mantén el indexador de Cursor activo para el proyecto en disco. Deja que Explore, Instant Grep y el agente dentro del editor lo usen. Ese bucle es nativo y rápido.
Añade Maguyva como servidor MCP en Cursor para que la misma sesión también pueda consultar el mapa alojado del espacio de trabajo. Cursor es un cliente Maguyva documentado. No eliges un índice y borras el otro.
Añade el mismo servidor Maguyva a Claude Code, Codex CLI, o cualquier otro cliente MCP que toque el repo. Una sola forma de clave de API. Un solo espacio de trabajo.
Si un agente de CI es compatible con MCP, apúntalo al mismo servidor. Leerá el mismo snapshot con marca de tiempo que leyó el portátil.

El índice del editor sigue siendo la mejor herramienta para «qué hay en disco en esta ventana, ahora mismo». El mapa alojado es la mejor herramienta para «cómo se ve este espacio de trabajo para cada agente que lo toque hoy». Esas frases no compiten.

Las cuotas de espacio de trabajo están publicadas en la página de precios: repos, líneas indexadas y usuarios, facturados por espacio de trabajo. Agentes y humanos comparten el mismo recuento de usuarios. Empieza gratis con un repo que ya sepas evaluar. Aumenta el espacio de trabajo solo después de que las citas sobrevivan al contacto con el árbol.

Lo que esta página no afirma

No afirma que el indexador de Cursor sea débil, incompleto, o una razón para cambiar de editor. La primera frase de este borrador es lo contrario.

No afirma que Maguyva reemplace a Instant Grep o al subagente Explore. Esas son funciones de Cursor. Se quedan en Cursor.

No inventa un recuento de lenguajes, una cifra de latencia, ni un ahorro de tokens para ninguno de los dos productos. Las cifras desconocidas permanecen sin publicar.

No finge que el trabajo local no subido está en el mapa alojado. Los snapshots con marca de tiempo hacen visible ese límite. No lo eliminan.

La prueba es ordinaria. Indexa un repo que ya conoces. Haz una pregunta que puedas verificar, primero en Cursor, luego en un segundo cliente MCP. Un contexto que viaja es la misma cita en ambos lugares.

// same map, wherever you opened it.

Primero el mapa, después la revisión

Mon, 07 Sep 2026 00:00:00 GMT

Dos trabajos distintos se sitúan a cada lado de un pull request. Antes de que el agente escriba, necesita un mapa del árbol que está a punto de cambiar. Después de que el agente abre un PR, algo debería leer ese cambio contra el resto del sistema y dejar comentarios sobre los que un humano pueda actuar.

Esos trabajos se parecen desde lejos porque ambos implican «entender la base de código». No son el mismo producto. Uno responde «¿dónde debería aterrizar este cambio?». El otro responde «¿qué rompió este diff que un linter línea por línea no verá?». Confundirlos produce un primer borrador peor y una revisión más ruidosa.

Este artículo es una guía de flujo de trabajo conjunto. Maguyva es el mapa que el agente consulta primero. Greptile es el agente de revisión que comenta el PR después. El dúo es complementario por construcción: Maguyva no revisa pull requests, y Greptile no reemplaza la capa de contexto que el agente usó para escribirlos.

Por qué es útil esta división

Un agente de código que parte de priors de entrenamiento más unos cuantos archivos pegados inventará una ruta plausible y la editará. Ese es el fallo del archivo equivocado, y es un problema de recuperación. Maguyva es una capa de contexto de código MCP remota: recuperación semántica, estructural (AST), por grafo/dependencia y de texto, fusionada en resultados clasificados, más búsqueda de símbolos y recuperación de archivos. Las respuestas fundamentadas vuelven como path/file.ext:line, así que puedes rechazar un fallo antes de que exista un parche. La afirmación se mantiene modesta: menos ediciones alucinadas. El modelo todavía puede adivinar. El primer paso simplemente deja de ser una suposición.

Greptile es un agente de revisión de código con IA. En sus propias palabras, revisa automáticamente cada pull request con comprensión completa de la base de código, y posiciona eso frente a los linters tradicionales que verifican archivos de forma aislada en lugar del sistema entero. La configuración consiste en instalar la app de GitHub o GitLab y seleccionar repositorios. No hay ningún índice local que tengas que gestionar. El alojamiento es Greptile Cloud (declaran cumplimiento SOC 2 Tipo II, con un informe disponible bajo solicitud), con una opción autoalojada ofrecida a empresas.

Su propio flujo numerado es: conectar y construir un grafo de dependencias de cada función, clase y dependencia; en cada pull request, analizar el cambio usando ese grafo completo del repo y publicar hallazgos como comentarios del PR con correcciones sugeridas, en unos tres minutos; cada comentario puede pasar el problema a un agente de código que el equipo ya usa. También declaran leer comentarios humanos anteriores de PRs a lo largo del tiempo para aprender los estándares de código de un equipo y reducir sugerencias ruidosas. Su sistema de aprendizaje, según declaran, necesita entre 2 y 3 semanas para adaptarse.

Eso es revisión, no redacción. La fortaleza de Greptile es el contexto de grafo completo del repo sobre el cambio que ya aterrizó en un PR, seguido de un bucle cerrado que envía el hallazgo a Claude Code, Codex, Conductor, Cursor o Devin. La fortaleza de Maguyva es el mapa clasificado que el agente consultó antes de que ese cambio se escribiera. Usa ambos. No le pidas a ninguno de los dos que haga el trabajo del otro.

Una integración de producto de primera parte Maguyva–Greptile no está declarada. No la necesitas. Maguyva habla con el agente por MCP. Greptile habla con GitHub o GitLab a través de su app. Se encuentran en el pull request. Sin script de pegamento, sin cron que canalice una herramienta hacia la otra. El dúo prescinde de bash porque cada producto ya ocupa la superficie que le corresponde.

Lo que esto no es

Esto no es un desmontaje de Greptile. No es una página de «cambia de revisor». Greptile se lanzó en Hacker News el 5 de marzo de 2024 como empresa de Y Combinator W24, y ese hilo es cómo mucha gente conoció el producto por primera vez. Si así fue como los encontraste, quédate con ellos. Esta página es la mitad delantera que falta en ese bucle: anclar al agente para que el PR que Greptile ve ya apunte a los archivos correctos.

Los materiales de marketing de Greptile encabezan con afirmaciones de velocidad de revisión y detección de bugs. Trátalas como afirmaciones propias de Greptile, no como cifras verificadas independientemente. Este borrador no las repite como hechos.

La cobertura de lenguajes es el mismo tipo de honestidad. Greptile enmarca su soporte como cobertura de todos los lenguajes de programación en lugar de una lista enumerada; no se indica una cifra precisa. Maguyva publica más de 279 lenguajes y tecnologías basadas en texto, con una división técnica (AST respaldado por parser frente a solo texto) en el sitio cuando la pregunta es técnica. Son productos distintos haciendo afirmaciones distintas. No los mezcles.

El precio de Greptile no se indica en las notas que este borrador puede usar. Existen planes de pago; consulta su página de precios. Maguyva cobra por espacio de trabajo, no por asiento. Los planes empiezan gratis. La página de precios lista los niveles publicados si necesitas las cifras de espacio de trabajo.

Flujo de trabajo

Tres etapas con nombre. Ejecútalas en este orden. No te saltes ninguna la primera vez que pruebes el dúo.

1. Contexto de Maguyva

Indexa un repositorio que ya conozcas. Conecta el cliente MCP en el que ya escribes — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, u otro cliente compatible con MCP. Maguyva tiene guías de configuración para 24 clientes MCP documentados y puede conectarse a otros clientes que soporten la configuración MCP estándar.

Haz una pregunta que puedas evaluar antes de que nadie escriba una línea. «¿Dónde se gestiona la expiración de sesión, y qué la llama?» es un mejor primer movimiento que «arregla la autenticación». Exige citas. Abre los resultados file.ext:line. Sigue el símbolo. Confirma la dependencia que estás a punto de tocar.

Maguyva expone 11 herramientas MCP de cara al cliente en búsqueda, símbolos, análisis de dependencias, recuperación de archivos, contexto de repositorio y flujos de trabajo utilitarios deterministas. Cuatro modos de recuperación se fusionan en resultados clasificados; find_symbol es una herramienta separada cuando ya conoces el nombre. Los docs describen el camino más corto: empezar gratis, indexar un repo que ya conoces, conectar el cliente, luego hacer una pregunta que puedas verificar.

Los snapshots llevan marca de tiempo, así que el agente puede saber qué versión del árbol está leyendo. El límite honesto es el trabajo local no sincronizado. Si la edición solo existe en un árbol de trabajo y no se ha subido, el mapa alojado todavía no la contiene. Los archivos de instrucciones (CLAUDE.md, AGENTS.md) siguen teniendo su lugar aquí, para convenciones y lo que no hay que tocar. No son un mapa vivo. Úsalos para el comportamiento. Usa Maguyva para los hechos.

No dejes que el agente abra un PR antes de que las citas sobrevivan al contacto con el repo. Esa barrera es todo el sentido de esta etapa.

2. PR del agente

El mismo agente ahora escribe el cambio en el cliente por el que ya pagas. Maguyva no es un editor ni un revisor. El agente sigue produciendo el diff. Sigues abriendo el pull request en GitHub o GitLab como ya lo haces.

Lo que debería ser distinto es el primer archivo. El PR debería nombrar el handler que realmente implementa el comportamiento, el llamador que se romperá, y la prueba que fallará si el cambio está mal. Si se saltó la etapa 1, la etapa 3 gastará sus comentarios en un cambio que aterrizó en el paquete equivocado. Greptile puede seguir encontrando problemas sistémicos. No debería tener que recuperarse además de una ruta alucinada.

Mantén el PR acotado. Un primer archivo fundamentado no es licencia para reescribir el módulo. El dúo complementario funciona cuando el agente hizo un trabajo con un mapa, y luego le pidió a un revisor que hiciera otro trabajo sobre un diff acotado.

3. Revisión de Greptile

Greptile ya está conectado al repositorio a través de la app de GitHub o GitLab. En el nuevo pull request analiza el cambio usando el grafo completo del repo que construyó y publica hallazgos como comentarios con correcciones sugeridas. Sus propios materiales sitúan ese pase en unos tres minutos.

Lee los comentarios como leerías a un compañero cuidadoso: abre la ubicación citada, decide si el hallazgo es real, luego actúa. Donde Greptile ofrece «Fix with your Agent», envía el problema — rutas de archivo, números de línea, código sugerido — a Claude Code, Codex, Conductor, Cursor o Devin. «Fix All» envía todos los problemas de la revisión de una vez. También ofrecen un MCP de Greptile y un plugin de Claude Code para ese traspaso. Maguyva no está en esa lista de destinos nombrados; esa ausencia no es un problema. Maguyva ya hizo su trabajo en la etapa 1. El agente de código que escribió el PR es el que debería recibir la carga útil de corrección.

Espera ruido durante las primeras 2 a 3 semanas mientras el sistema de aprendizaje de Greptile se adapta a los comentarios que tu equipo realmente deja. Ese es su calendario declarado, no un defecto en el dúo. La revisión humana sigue en el bucle. Greptile es el primer pase automatizado, no el botón de fusión.

Si un comentario de Greptile señala un archivo que el agente nunca consultó en la etapa 1, esa es una señal útil. O el mapa se perdió un llamador, o el agente se saltó una cita. Corrige el borrador contra el comentario. No desactives al revisor.

Cómo mantener honesto el complemento

Maguyva primero, siempre. Una revisión de un PR con el archivo equivocado sigue siendo una revisión del archivo equivocado.
Greptile después, siempre. Un borrador bien citado igual necesita una lectura del diff a escala del sistema entero.
No le pidas a Maguyva que publique comentarios en PRs. No lo hace.
No le pidas a Greptile que sea la primera capa de recuperación del agente mientras todavía está eligiendo una ruta. Ese no es el trabajo para el que está cableada su app de GitHub o GitLab.
No inventes un pipeline de bash que los «sincronice». El PR es la interfaz.
Verifica ambos lados de forma independiente. Indexa un repo que ya conoces. Haz una pregunta que puedas verificar. Luego abre un PR pequeño y lee lo que Greptile realmente comenta.

El bucle es ordinario una vez que se nombra. Primero el mapa. Luego el PR del agente. Luego la revisión. Cada producto se queda en el lado del pull request en el que es bueno.

// map first. review second. in that order.

Dar a un agente de IA el contexto de un repositorio grande sin indexador local

Fri, 14 Aug 2026 00:00:00 GMT

Un repositorio grande no cabe en una ventana de contexto, y si alguna vez has apuntado un indexador de portátil a un monorepo real, sabes que ahí tampoco cabe cómodamente — la RAM se dispara, el primer índice tarda una hora, y tu agente sigue empezando la siguiente sesión adivinando qué archivos importan.

La respuesta habitual es ejecutar un indexador junto al editor, y para un repo que cabe cómodamente en una sola máquina, es una buena respuesta. Si tu monorepo ya se indexa rápido en Cursor y ese es el único sitio donde necesitas el mapa, este artículo no tiene nada que añadir — sáltatelo.

Este artículo trata del otro caso — cuando un agente necesita un mapa consultable de un repo grande, y no quieres ejecutar un indexador local para conseguirlo.

Cuándo un indexador local es la herramienta equivocada

Un índice local asume que el código vive en la máquina que lo consulta, y a la escala real de un monorepo esa suposición se tensa incluso dentro de un solo editor. El repo es sencillamente más grande de lo que quieres mantener caliente en un portátil: trabajas en un paquete mientras el radio de impacto vive tres directorios más allá, y un primer índice en frío de un árbol de dos millones de líneas no es algo que quieras sufrir dos veces — ni en tu máquina, ni en un runner de CI que nunca clonó el árbol antes. O un compañero debería poder consultar el mismo mapa que tú, sin esperar a que su propia máquina se abra paso por el mismo índice.

Nada de esto es razón para desechar un buen indexador de editor. Es razón para tener también un mapa alojado que cualquiera de tus agentes pueda consultar por MCP.

Y el problema de escala va más allá de «demasiados archivos para pegar». En un árbol grande, la pregunta interesante casi nunca es «muéstrame este archivo» — es qué archivo, qué símbolo, qué llamadores, qué pruebas. Un agente que empieza listando src/ y leyendo los tres primeros resultados fallará alegremente el handler en apps/api y el cliente generado en packages/sdk. Lo que necesitas es una recuperación construida desde todo el árbol, luego clasificada, luego citada.

Qué significa realmente «contexto de un repo grande»

Volcar archivos en el prompt no es contexto — es una copia más pequeña y peor del árbol. Lo que tu agente realmente necesita es hacer preguntas y recibir respuestas citadas de vuelta: dónde está definido este símbolo y quién lo llama, qué depende del módulo que estoy a punto de cambiar, qué archivo de prueba cubre este comportamiento, y cómo se ve el árbol ahora, no el trimestre pasado.

Esas respuestas tienen que venir de un índice construido a partir de tu repo en lugar de la memoria del modelo sobre repos de otras personas, y el índice tiene que vivir en algún lugar distinto de la ventana de contexto del agente. Para este problema, también debería vivir en algún lugar distinto de tu portátil.

Otra cosa que los archivos de instrucciones no pueden hacer por ti: CLAUDE.md y AGENTS.md son el lugar correcto para las convenciones y el comportamiento, pero no son un mapa vivo, clasificado y consultable de un árbol de dos millones de líneas. Usa las reglas para el comportamiento; usa la inteligencia del repo para los hechos.

Construir el mapa en la nube, consultarlo desde cualquier cliente

Maguyva es una capa de contexto de código MCP remota. Conectas GitHub, eliges tus repositorios, y te marchas mientras los pipelines en la nube analizan el árbol, construyen los símbolos y las aristas del grafo, y mantienen un mapa clasificado — sin indexador local, nunca.

Cuando subes código, los archivos cambiados se analizan de forma incremental, y las capas de grafo y clasificación se reconstruyen según un calendario: diario en el plan gratuito, cada hora en los de pago. Cada snapshot lleva marca de tiempo, así que tu agente puede saber qué versión del árbol está leyendo. El límite honesto aquí es el trabajo local no sincronizado — una edición que solo existe en tu árbol de trabajo, nunca subida, aún no está en el mapa alojado.

Luego conectas el cliente que ya uses añadiendo una clave de API a su configuración MCP. Hay guías de configuración para 24 clientes MCP documentados, y cualquier otro cliente compatible con MCP que soporte la configuración estándar también puede conectarse. Si Cursor es donde vives, la página de Cursor recorre ese camino; el mismo servidor responde a Claude Code, VS Code, Windsurf, Codex CLI y el resto.

No cambias de editor. Le das a tu agente una superficie de herramientas — 11 herramientas MCP en búsqueda, símbolos, análisis de dependencias, recuperación de archivos y contexto de repositorio — con cobertura de más de 279 lenguajes y tecnologías basadas en texto, lo cual importa más de lo que crees en un monorepo que dejó de ser un solo lenguaje hace años.

Las respuestas vuelven fundamentadas, como rutas de archivo con números de línea. La recuperación semántica, estructural, por grafo y de texto se fusionan en resultados clasificados, de modo que una pregunta como «qué depende de parseConfig» no te da ni un volcado de grep ni un solo fragmento semántico, sino el puñado de lugares que realmente importan.

Una guía concreta

No empieces indexando toda la empresa. Este es el camino que funciona:

Elige un repositorio que ya conozcas bien — un paquete que puedas evaluar a mano vale más que el árbol más grande que tengas.
Empieza gratis: 3 repos, 50k líneas indexadas, las 11 herramientas, sin cuota mensual de consultas. Si tu repo representativo es más grande, la página de precios lista los niveles de espacio de trabajo ($0, $19, $49, $149) por huella indexada — no por número de asientos.
Conecta GitHub y espera a que termine el primer índice. No estás compilando nada localmente.
Conecta el cliente MCP — unas pocas líneas de configuración. Maguyva es un servidor MCP remoto, así que no hay plugins, ni extensiones, ni un segundo editor que adoptar.
Haz una pregunta que puedas verificar. «¿Qué depende de parseConfig?» o «¿Dónde se gestiona la expiración de sesión de inicio?» Luego abre los resultados citados file.ext:line y compáralos con el árbol que tienes delante.
Solo después de que las citas sobrevivan a ese contacto dejas que el agente edite.

Si el primer repo encaja bien y tu árbol es grande, sube el espacio de trabajo para que coincida con tus líneas indexadas y la cadencia de reconstrucción. Humanos y agentes comparten el mismo recuento de usuarios — Maguyva cobra por espacio de trabajo, no por asiento — así que añadir un tercer agente al bucle no te cuesta nada.

La prueba de activación es la misma que recomiendan los docs para cualquier primera ejecución: indexar un repo que ya conoces, hacer una pregunta que puedas verificar. Un repo grande no cambia la prueba; solo hace que un primer archivo equivocado salga más caro.

Qué vigilar una vez conectado

Vigila tres cosas. Frescura: los planes de pago se reconstruyen cada hora, los gratuitos a diario, y el trabajo local no subido no estará en el mapa — ese es el trato que aceptas. Alcance: indexa un conjunto representativo de repos, no cada fork archivado; el nivel gratuito está deliberadamente dimensionado para averiguar si las respuestas merecen la pena conservarse. Y verificación: un mapa de repo grande que no pueda citar rutas y números de línea es solo un motor de adivinanzas más lento, así que haz que tu agente muestre la ubicación antes de entregar el parche.

Luego ejecuta la misma prueba que ejecutarías en un repo pequeño. Indexa un repo que ya conoces. Haz una pregunta que puedas verificar. Si el mapa es real, tu agente deja de empezar desde un árbol frío.

// no laptop got hot building this map.

Por qué tu agente de código con IA alucina rutas de archivo

Fri, 14 Aug 2026 00:00:00 GMT

La señal delatora no es un cuerpo de función incorrecto. Es una edición segura de sí misma a un archivo que no existe, o a un archivo que existe pero no es el que implementa el comportamiento.

Pediste una corrección de expiración de sesión. El agente abrió src/auth/session.ts. Esa ruta es plausible. También está mal. El handler real vive en apps/api/src/middleware/expiry.ts, renombrado hace dos refactorizaciones. El agente no te mintió. Completó una cadena con forma de ruta a partir de priors de entrenamiento más lo que ya hubiera en la ventana de contexto.

Este es el modo de fallo común en un repositorio real. El modelo sabe escribir código. El error está en elegir el lugar equivocado para escribirlo.

Por qué los agentes inventan rutas

Un agente de código es un modelo de predicción del siguiente token con herramientas. Cuando dices «arregla la expiración de sesión», tiene que nombrar un archivo antes de poder leer o parchear nada. Si todavía no tiene un mapa fundamentado, construye una ruta a partir de:

Convenciones de nombres que ha visto en otros repositorios. src/auth/session.ts es una forma frecuente.
Archivos que ya están en la conversación, que quizá sean los que pegaste la semana pasada, no los que importan ahora.
Listados de directorios que ejecutó por casualidad, incompletos en un árbol grande.
Archivos de instrucciones. CLAUDE.md y AGENTS.md le dicen al agente cómo comportarse. No son un índice vivo de símbolos, llamadores o rutas actuales.

Ninguna de esas fuentes es un mapa de este repo, hoy. El modelo llena el vacío como llena cualquier vacío: con una continuación de alta probabilidad. Esa continuación a menudo se ve como una ruta real. A veces el archivo existe y está junto al correcto. A veces existió en una rama que se fusionó el mes pasado. A veces nunca existió.

Grep no te salva aquí si el agente nunca busca la cadena correcta. El agente adivinó una ruta, luego leyó lo que esa ruta devolvía, luego la editó. El primer paso equivocado fue la ruta, no el parche.

Leer archivos tampoco es lo mismo que encontrar los correctos. Claude Code, Cursor, Codex y herramientas similares pueden abrir lo que sea que les señales. La pregunta es si encuentran de forma fiable los archivos correctos, los símbolos importantes, las dependencias, las pruebas y el radio de impacto antes de editar. El acceso a archivos sin un mapa sigue empezando con una suposición.

La edición del archivo equivocado es un problema de recuperación

Trata la ruta inventada como un fallo de recuperación, no como un defecto de personalidad.

Si el agente tuviera que devolver path/file.ext:line antes de que se le permitiera editar, sucederían dos cosas. Primero, podrías abrir la cita y rechazar el trabajo en diez segundos. Segundo, el agente tendría que consultar algo que realmente conoce el árbol.

Ese es el trabajo de una capa de contexto de código. La búsqueda semántica sola no basta. Un fragmento que «suena a expiración de sesión» puede aterrizar igualmente en un paquete obsoleto. También necesitas texto exacto cuando conoces la cadena, búsqueda de símbolos cuando conoces el nombre, búsqueda estructural cuando conoces la forma, y un grafo de dependencias cuando necesitas llamadores y radio de impacto.

Maguyva es esa capa para agentes de código compatibles con MCP. No es un editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf y otros clientes MCP se quedan donde están. El agente consulta un mapa clasificado antes de tocar una línea.

La afirmación es modesta a propósito: menos ediciones alucinadas. Maguyva no le quita al modelo la capacidad de adivinar. Cambia el primer paso por defecto de «inventar una ruta plausible» a «pedir ubicaciones clasificadas y citadas».

Cómo se ve una respuesta fundamentada

Una respuesta útil a «dónde se gestiona la expiración de sesión» no es un párrafo. Es una lista corta de ubicaciones:

apps/api/src/middleware/expiry.ts:48 - el handler
apps/web/src/lib/auth-client.ts:112 - el llamador
apps/api/tests/expiry.test.ts:20 - la prueba que fallará si el cambio está mal

Puedes abrir esas líneas. Si están mal, te detienes. Si están bien, el agente puede editar. La verificación es el punto, no un eslogan.

Maguyva expone 11 herramientas MCP de cara al cliente en búsqueda, símbolos, análisis de dependencias, recuperación de archivos, contexto de repositorio y flujos de trabajo utilitarios deterministas. Cuatro modos de recuperación (semántico, estructural, grafo/dependencia y texto) se fusionan en resultados clasificados; la búsqueda de símbolos es una herramienta MCP separada (find_symbol). Las respuestas fundamentadas vuelven con rutas de archivo y números de línea, así que puedes evaluarlas contra el árbol que tienes delante.

Los docs describen el camino más corto: empezar gratis, indexar un repo que ya conoces, conectar el cliente, luego hacer una pregunta que puedas verificar.

Un bucle que cambia la primera edición

No necesitas una nueva religión de flujo de trabajo. Necesitas un paso extra antes de la primera escritura.

Haz una pregunta que ya puedas evaluar. «¿Qué código gestiona el inicio de sesión y la expiración de sesión?» es mejor que «arregla la autenticación».
Exige citas. Ruta de archivo y número de línea, no un resumen de «el módulo de autenticación».
Abre los archivos citados. Sigue el símbolo. Confirma la dependencia que estás a punto de tocar.
Solo entonces dejas que el agente parchee.

Si el paso 2 no devuelve nada útil, el agente no tiene permiso para improvisar una ruta. Busca de nuevo, o tú se lo indicas. Esa única barrera es lo que produce menos ediciones alucinadas. El modelo es el mismo modelo. El mapa es lo que cambió.

Los archivos de instrucciones siguen importando. Consérvalos. Úsalos para convenciones, reglas de revisión y lo que no hay que tocar. No les pidas que sean el índice. Un CLAUDE.md que lista tres directorios importantes quedará obsoleto la semana siguiente a una división de paquete. Un mapa consultable se actualiza cuando el repo se actualiza.

Un fallo relacionado es el archivo casi-correcto: el agente abre auth.ts cuando el comportamiento vive en auth-client.ts, o parchea un archivo generado en lugar de la fuente, o edita la copia en packages/legacy porque el nombre coincidía. Las citas no hacen esos errores imposibles. Los hacen visibles antes de que el diff aterrice.

Lo que un mapa no arreglará por ti

Sé claro sobre lo que estás obteniendo. Un mapa fundamentado no hará correcta cada edición — tu agente puede seguir escribiendo un mal parche en exactamente el archivo correcto. Si tu base de código se apoya en despacho dinámico, reflexión o monkey-patching, algunas búsquedas de símbolos volverán más pobres de lo que te gustaría, porque eso es lo que la indirección en tiempo de ejecución le hace a cualquier índice estático. Y si esperas un porcentaje — «rutas alucinadas reducidas en X%» — no lo encontrarás aquí, porque nadie puede medir honestamente esa cifra para tu repo salvo tú.

Lo que puedes esperar es más estrecho y más útil: el agente deja de abrir sus ediciones con una ruta adivinada. Ese primer paso queda fundamentado en un mapa real, y de ahí vienen las menos ediciones alucinadas. Todo lo que viene después de la cita — leer el diff, juzgar el parche — sigue siendo tu trabajo, igual que siempre lo fue.

La prueba casi no te cuesta nada: indexa un repo que ya conoces y haz una pregunta que puedas verificar. Empieza con una ruta con la que ya te hayan quemado antes. Si las citas están mal, lo verás de inmediato. Si están bien, la siguiente edición de tu agente tiene un lugar mejor donde aterrizar.

// it doesn't know the file. it knows how to find it.

Por qué actualizamos la búsqueda de código a voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Las cifras de benchmark en esta publicación reflejan las tablas de RTEB al momento de la publicación (junio de 2026). Las tablas cambian; trata las clasificaciones como una instantánea, no como un hecho permanente.

La búsqueda semántica es tan buena como los embeddings que hay detrás.

Cuando un agente le pregunta a Maguyva «dónde manejamos los reintentos», no está haciendo grep de la palabra «retry». Está pidiendo el significado — el bucle de backoff, el circuit breaker, la cosa que envuelve una llamada inestable. Esa pregunta la responde un modelo vectorial que convierte el código en un punto en el espacio y encuentra a sus vecinos. Elige un mejor modelo y cada consulta semántica del producto gana precisión discretamente.

Así que cambiamos el nuestro. Desde junio de 2026, los embeddings de código de Maguyva corren sobre voyage-4-large, en reemplazo de voyage-code-3.

El benchmark

No tomamos esta decisión por intuición. El Retrieval Embedding Benchmark (RTEB) público clasifica modelos de embeddings en tareas reales de recuperación, y en su tabla de Code, voyage-4-large ocupa el #1 general (90.86) — por delante de gemini-embedding-2-preview (90.26) y, notablemente, por delante del modelo que ya estábamos usando, voyage-code-3 (89.73, #3).

Esa es una brecha absoluta pequeña. Pero es una brecha en la dirección correcta, en un benchmark público, en la tarea exacta que nos importa: recuperar código por significado.

El compromiso que aceptamos: cuantización binaria

Aquí está la parte que la mayoría de las publicaciones de «actualizamos nuestro modelo» se saltan.

Maguyva no almacena vectores de precisión completa. Almacenamos embeddings cuantizados en binario: cada vector de 2048 dimensiones se colapsa a una firma de 2048 bits — 256 bytes por vector. Esas firmas se buscan con distancia de Hamming, indexadas y particionadas por tenant.

Ese es un compromiso deliberado. La cuantización binaria cede algo de precisión de recuperación a cambio de un almacenamiento dramáticamente más pequeño y un cálculo de distancia rápido y barato, sin necesidad de operar una base de datos vectorial separada. Para un producto que indexa repositorios completos por espacio de trabajo, esa economía importa más que exprimir la última fracción de un punto de benchmark.

voyage-4-large encaja en este diseño sin forzar una migración de la capa de almacenamiento: produce una salida de 2048 dimensiones, igual que voyage-code-3, así que nuestras columnas bit(2048) y la ruta de búsqueda por Hamming no cambiaron. El modelo mejoró; el esquema se quedó igual.

El código fue solo el comienzo

Maguyva es una herramienta de inteligencia de código. Pero también somos el cliente cero, y lo apuntamos a otra cosa: el markdown que vive en nuestros repositorios junto al código. Registros de decisiones de arquitectura, runbooks, contratos, documentos de finanzas y políticas — todo bajo control de versiones en Git, todo detrás del mismo servidor MCP, un índice semántico sobre los documentos, no solo sobre el código fuente.

Por eso importa exactamente la amplitud de voyage-4-large. En la misma familia de tablas de RTEB es #1 en finanzas, #1 en salud y #1 en recuperación general de texto — por delante de Gemini Embedding de Google, Embed v4 de Cohere y text-embedding-3-large de OpenAI. (Voyage es cocreador de RTEB, así que lo leemos como una señal pública fuerte más que como un árbitro perfectamente neutral, pero se compara cabeza a cabeza contra todos los modelos comerciales importantes, en conjuntos de reserva privados). El mismo índice que encuentra la función correcta para un agente encuentra la cláusula correcta en un contrato o la línea correcta en una política — y en esos dominios, voyage-4-large no es un compromiso, es el líder.

Por qué pagamos por embeddings premium

Hay una forma más barata de hacer búsqueda, y gran parte de ella es gratis. La búsqueda léxica — BM25 y sus parientes — busca coincidencias de palabras clave, corre localmente y no cuesta nada. Los modelos de embeddings de código abierto como BGE, Nomic y embeddinggemma dan una recuperación semántica genuinamente decente, y puedes alojarlos tú mismo por el precio de una GPU. Maguyva también usa el lado gratuito: cada consulta fusiona búsqueda de texto, AST, grafo y semántica. En lo que no escatimamos es en la capa semántica.

Pagamos por token por embeddings premium — voyage-4-large — en lugar de autoalojar un modelo gratuito, por dos razones. Primero, la búsqueda por palabras clave sola no puede responder «dónde manejamos los reintentos» cuando el código dice backoff y circuit breaker y nunca dice la palabra «retry» — el significado es la razón de ser del embedding, y en los dominios a los que servimos los modelos abiertos van a la zaga de los premium: un par de puntos por detrás en texto general, y más atrás todavía en nichos como código, contratos y finanzas. Segundo, en nuestra experiencia la calidad de la recuperación moldea la respuesta final más que el modelo del otro lado — un agente fuerte al que le dan el contexto equivocado de todas formas responde mal, y nunca ve el documento que nunca le dieron.

Así que los embeddings premium son una factura por token que escala con cada repositorio y documento que indexamos — y la pagamos a propósito. Por el resultado que obtienen nuestros usuarios, la función correcta o la cláusula correcta, creemos que ese compromiso vale la pena.

La parte honesta

La propia documentación de Voyage todavía etiqueta a voyage-code-3 como el modelo optimizado para código. Entonces, ¿por qué cambiar?

Porque leímos el benchmark público, no solo la tabla de modelos del proveedor, y el benchmark puso a voyage-4-large en la cima para recuperación de código. Esta fue una decisión con visión de futuro: tomar el modelo más nuevo y generalmente más fuerte y validarlo contra una tabla pública en las tareas que importan. Nos sentimos cómodos haciendo esa apuesta porque la evidencia es amplia — voyage-4-large no solo gana en código, también lidera en finanzas, salud y recuperación general.

Los cimientos discretos

Cada herramienta que exponemos — búsqueda semántica, recopilación de contexto de tareas, preguntas y respuestas fundamentadas — termina apoyándose en la recuperación. Cuando el recuperador mejora, el agente del otro lado obtiene mejor evidencia, toma menos decisiones equivocadas, y fundamenta sus respuestas en el código correcto — o en la cláusula correcta, o en la política correcta. Un modelo de embeddings más preciso no es una función vistosa. Son los cimientos de todo lo demás, y acabamos de reforzarlos. No lo vas a notar. Ese es el punto.

Mejora recursiva del soporte de lenguajes: afinando la inteligencia de código en ~280 lenguajes

Tue, 26 May 2026 00:00:00 GMT

Las cifras de esta publicación reflejan el sistema al momento de su publicación (mayo de 2026). Consulta nuestra página del equipo para ver las cifras actuales.

Maguyva extrae símbolos, referencias y un grafo de dependencias del código fuente en aproximadamente 280 lenguajes. Cada lenguaje es un handler de tree-sitter personalizado — consultas, heurísticas, casos extremos — y cada handler puede estar sutilmente equivocado a su propia manera. Una llamada a método emitida como una lectura. Una función atribuida al alcance envolvente equivocado. Una relación que simplemente no existe.

Eso no se puede auditar a mano. Ningún equipo puede leer la salida de extracción en 280 gramáticas y detectar las aristas malas. Así que la pregunta interesante no es «¿nuestra extracción es correcta?» — es «¿cómo descubres que está mal, a esta escala, sin un humano en cada ciclo?». Nuestra respuesta es la mejora recursiva del soporte de lenguajes: un bucle de calidad impulsado por agentes de lenguaje, un LLM que actúa como juez, y una regla que seguimos reaprendiendo: verde no es lo mismo que correcto.

Verde no es correcto

Cada lenguaje tiene un conjunto de fixtures, y un control previo al lanzamiento lo evalúa en cinco dimensiones — exactitud, integridad estructural, completitud, calidad y rendimiento. Un lenguaje pasa a VERDE solo cuando, en sus fixtures, la precisión es ≥ 0.95, el recall ≥ 0.99 y el F1 ≥ 0.97, con al menos 20 aristas esperadas para tener confianza estadística. Por debajo de eso es AMARILLO o ROJO, y no se publica.

Ese control es necesario, pero no suficiente. Los fixtures se validan contra fixtures que nosotros escribimos. Codifican los casos que ya se nos ocurrieron. Un handler puede ser impecable en sus fixtures y aun así estropear un patrón que solo aparece en código real — un modismo de macro, un método con restricciones sobre sus tipos genéricos, una característica del lenguaje para la que nadie escribió un fixture. VERDE significa que los fixtures pasan. No significa que un repositorio real se extraiga limpiamente. Así que el bucle tiene que dejar atrás los fixtures y mirar el mundo real.

El bucle interno: verificación puntual, juicio, corrección, prueba

El bucle central se ejecuta para un lenguaje a la vez:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Hay algunas cosas que hacen que esto funcione en lugar de dar vueltas sin avanzar.

El juez es el agente, no una llamada a una API. Cuando decimos «LLM como juez», nos referimos a que el propio agente de lenguaje lee cada arista muestreada contra la fuente real y la clasifica con una rúbrica fija de cinco categorías: ¿esta arista es correcta, es un falso positivo, es la relación correcta con el tipo equivocado, está unida al alcance equivocado, o lleva metadatos equivocados? Esa rúbrica es todo el juego — un «23% de tasa de error» no significa nada hasta que sabes si son defectos reales o el juez contando mal.

Corrige una cosa, y luego pruébalo. Cada iteración cambia exactamente un activo editable, luego se vuelve a ejecutar con un entorno de pruebas fijo y conserva el cambio solo si el F1 mejora y la reclasificación se ve mejor. Si no, se revierte. Nada de lotes de ediciones especulativas, nada de «debería estar mejor». Un cambio se gana su lugar o desaparece. Y cuando una corrección se mantiene, se promueve al conjunto de fixtures — para que el bug que corrigió nunca pueda volver en silencio. Ese paso de promoción es lo que hace que el bucle sea recursivo y no simplemente repetitivo: cada pasada endurece el oráculo contra el que se valida la siguiente pasada.

La lección que seguimos reaprendiendo: las métricas sobrerreportan

Aquí está la trampa, y caímos de lleno en ella. Las métricas secundarias del corpus — con qué frecuencia un destino extraído no tiene un símbolo resoluble, cuántos símbolos parecen «huérfanos», etcétera — sobrerreportan masivamente los problemas. En su mayoría son artefactos de paradigma, no bugs.

El ejemplo más claro: llvm mostró en un momento una tasa del 73% de «fuente sin símbolo» y fue tildado de catastrófico. Investigamos. La precisión real era del 98.5%. Los «símbolos faltantes» eran casi todos referencias externas legítimas — llamadas a la biblioteca estándar, a frameworks, a código que vive fuera del repositorio. La métrica estaba midiendo una propiedad del lenguaje, no un defecto del handler. Lenguajes como Zig, COBOL y Odin muestran tasas de «huérfanos» del 65–70% y son totalmente correctos; COBOL tuvo cero errores reales.

Si hubiéramos dejado que esos números guiaran el trabajo, habríamos pasado semanas «arreglando» handlers que ya estaban bien e ignorando los lenguajes con bugs reales y silenciosos. La conclusión es tajante: las métricas agregadas son, en el mejor de los casos, una señal aproximada de triaje. La señal de calidad real es la verificación puntual con clasificación de aristas — mirar aristas reales en repositorios reales y juzgarlas una por una. Datos por encima de la intuición, pero solo una vez que sabes qué datos están diciendo la verdad.

El bucle externo: una flota, no un maratón

Hacerlo de a un lenguaje a la vez tomaría una eternidad en 280 de ellos, así que el bucle interno se envuelve en uno externo que ejecuta muchos en paralelo.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Cada agente trabaja en un worktree desechable para que no se pisen entre sí. El orquestador integra sus correcciones de a una, cada una detrás de una verificación de regresión de manifiesto completo: un cambio que ayuda a su propio lenguaje pero rompe silenciosamente otros tres no se integra. La integración está controlada y confirmada antes de que se publique nada — el control de regresión decide qué es seguro, un humano sigue decidiendo qué se lanza. Luego el pool rota hacia el siguiente conjunto de lenguajes y todo el proceso se repite.

Lo que todavía es imperfecto

El juez puede equivocarse, y el error tiene una dirección: un agente que corre con muy poco contexto sobrerreporta. En un lote, ocho lenguajes fueron marcados con un 5–20% de error; al inspeccionarlos, solo uno de esos lenguajes tenía un bug real — el resto eran errores del juez por no captar la semántica propia del lenguaje (una línea de fuente que legítimamente emite varias aristas, enlaces de parámetros modelados como asignaciones, lenguajes con una referencia por identificador). Por eso muestreamos con dos semillas y hacemos verificación cruzada, y por eso un desacuerdo entre el juez y los fixtures se trata como la señal más interesante, no como un veredicto definitivo — a veces lo que está mal es el fixture.

También somos honestos sobre el objetivo. La meta es cero errores reales, punto — pero «cero» es una dirección hacia la que nos esforzamos, lenguaje por lenguaje, no una casilla que se marca. Siempre hay otro repositorio con otro modismo.

Ganado, no afirmado

Todo lo que Maguyva hace por un agente — encontrar un símbolo, rastrear una dependencia, responder una pregunta con código citado — descansa en que la extracción de base sea correcta. En 280 lenguajes, «correcto» no se puede simplemente afirmar; hay que ganárselo continuamente contra código real. El bucle es cómo nos lo ganamos: un ciclo autónomo de verificación puntual y corrección que trata sus propias métricas con sospecha, prueba cada cambio, y convierte cada corrección en una protección contra la próxima regresión. No es glamoroso. Es el trabajo que nos permite decir «damos soporte a tu lenguaje» y decirlo en serio. Verde es fácil. Correcto se gana.

Búsqueda por fusión multimodal: eligiendo el recuperador correcto para cada consulta

Wed, 15 Apr 2026 00:00:00 GMT

Nota sobre el diseño histórico: este artículo de abril de 2026 describe el diseño de enrutamiento de entonces, no el comportamiento predeterminado actual. La corrección de septiembre que figura más abajo solo trata una afirmación sobre mediciones. Para conocer el enrutamiento, los preajustes y los controles explícitos de modalidades actuales, consulte Cómo funciona.

Una consulta de búsqueda no es una sola cosa.

«dónde está definido parseConfig» quiere un símbolo exacto — una ubicación precisa, rápido. «cómo funciona la autenticación» quiere significado — el conjunto de código relacionado que explica un concepto. «qué se rompe si cambio esta función» quiere el grafo de dependencias. «encontrar la cadena ECONNREFUSED» quiere una coincidencia literal, nada elaborado.

Grep es excelente para coincidencias literales y útil para algunas búsquedas de referencias, pero no es un grafo de dependencias y no entiende el significado. Los embeddings cubren el lado semántico, pero son la herramienta equivocada para cadenas exactas y análisis de impacto. La mayoría de las herramientas de búsqueda de código eligen un solo motor y hacen que cada consulta viva con esa elección. Maguyva no elige. Determina qué tipo de pregunta hiciste y luego combina cuatro recuperadores en la proporción que esa pregunta merece.

Cuatro modalidades

Por debajo hay cuatro formas independientes de encontrar código:

semántica — búsqueda vectorial sobre embeddings binarios de Voyage; encuentra código por significado.
texto — coincidencia por trigramas; encuentra literales, cadenas de error, identificadores exactos.
estructural — consultas AST; encuentra definiciones, firmas y construcciones del lenguaje.
grafo — el grafo de dependencias; encuentra quién llama, a quién se llama, y el radio de impacto.

Cada una es fuerte en una clase distinta de pregunta. El truco está en decidir cuánto confiar en cada una para la consulta que tienes delante.

Clasificación de intención

Antes de que corra cualquier recuperación, un clasificador ligero ordena la consulta en una de seis intenciones, con un puntaje de confianza. Es deliberadamente barato — heurísticas ordenadas, gana la primera coincidencia — porque corre en la ruta crítica y solo agrega uno o dos milisegundos:

empieza con def , class , func , import … → find_definition (confianza 0.95)
«who calls» (quién llama), «usages of» (usos de), «references to» (referencias a) → find_references (0.90)
«impact» (impacto), «blast radius» (radio de impacto), «what depends on» (qué depende de) → impact_analysis (0.90)
un "string" entre comillas o un token de error como traceback → exact_match (0.85–0.90)
un identificador CamelCase o snake_case → find_definition (0.60–0.80)
«how» (cómo), «why» (por qué), «explain» (explica), «architecture» (arquitectura) → understand_code (0.75)
nada coincide → understand_code, confianza baja (0.40)

Cada intención lleva un perfil de ponderación entre las cuatro modalidades. Estos son los números reales:

Intención	semántica	texto	estructural (AST)	grafo
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

Así que «dónde está definido parseConfig» se apoya fuerte en AST (0.6). «cómo funciona la autenticación» se apoya en vectores semánticos (0.5). «qué depende de esto» es casi todo grafo (0.7). «encontrar ECONNREFUSED» es casi todo trigramas (0.9), con el modelo de embeddings completamente apagado — porque la similitud semántica es exactamente la herramienta equivocada para una cadena exacta.

La ruta rápida y la ruta fusionada

Cuando el clasificador tiene confianza — puntaje ≥ 0.85 — y la consulta es normal, Maguyva se salta la fusión por completo y enruta directo a la única modalidad dominante. «dónde está definido X» no necesita cuatro recuperadores; necesita el índice AST, ya. Esa ruta directa se reporta como fusion_strategy: "direct".

Todo lo ambiguo pasa por la fusión. Las cuatro modalidades (o tres, en el preajuste predeterminado) corren en paralelo, cada una devolviendo su propia lista clasificada, y las combinamos.

Reciprocal Rank Fusion ponderada

Fusionar recuperadores heterogéneos es más difícil de lo que suena: una similitud coseno de 0.82, un puntaje de trigramas de 137 y una centralidad de grafo de 0.004 no están en la misma escala, así que no puedes simplemente sumarlos. Reciprocal Rank Fusion evita el problema descartando los puntajes crudos y conservando solo la posición que cada motor asignó. La contribución de un resultado desde una modalidad es:

contribution = weight × 1 / (k + rank + 1)

donde rank es su posición en la lista de esa modalidad y k es una constante de suavizado. Las contribuciones se suman entre modalidades para cualquier resultado que más de un motor encontró — el acuerdo entre recuperadores flota naturalmente hacia arriba. Usamos k = 40 en el preajuste predeterminado y 60 en thorough (quick corre solo en modo semántico, así que la fusión nunca entra en juego ahí). El trabajo original de RRF llegó a k = 60 para recuperación de propósito general; nuestro valor predeterminado acentúa un poco más las primeras posiciones, lo que le da al acuerdo entre modalidades sobre los resultados mejor clasificados un poco más de peso — y no recomendamos ajustarlo a mano.

Además de eso, los resultados llevan un impulso de importancia de grafo. Un hub — una función de la que depende toda la base de código — debería superar a un nodo hoja poco conocido incluso con la misma relevancia textual, así que multiplicamos cada contribución por:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

La centralidad viene de las métricas precalculadas de PageRank/grado del pipeline, y el impulso está limitado a 1.5× para que una función popular no pueda enterrar por completo a una más relevante pero poco conocida. Finalmente degradamos los resultados de rutas de vendor, build y archivo, y deduplicamos al mejor fragmento por archivo.

Lo que todavía es imperfecto

El clasificador de intención es un conjunto de expresiones regulares, no un modelo entrenado. Maneja las formas habituales de consulta mediante heurísticas, y una consulta ambigua recurre a understand_code y a una combinación con mayor peso semántico. Una versión anterior de este artículo describía como conseguida una reducción de la tasa de consultas sin resultados de aproximadamente el 15% a menos del 5%. En realidad, la propuesta de diciembre de 2025 indicaba una tasa inicial estimada y un objetivo; no se proporciona un conjunto de consultas ni un registro de medición que lo respalde. Retiramos esa afirmación de mejora conseguida; consulte las evidencias de origen y la corrección. No hemos sustituido el clasificador por un modelo entrenado porque la versión económica es rápida y suficiente para la función de enrutamiento prevista, y porque un clasificador equivocado pero seguro de sí mismo es peor que una alternativa predeterminada honesta. Los pesos son supuestos previos elegidos a mano, no aprendidos de datos de clics que no recopilamos.

Pregunta lo que necesitas, no la herramienta

Un agente no debería tener que saber si recurrir a grep, a embeddings o al grafo de llamadas — debería hacer su pregunta en términos simples y obtener la respuesta correcta. La fusión multimodal es lo que permite que find_symbol, la búsqueda semántica y el análisis de dependencias convivan detrás de una sola interfaz de consulta: el sistema lee la forma de la pregunta y ensambla en silencio el recuperador correcto para ella. El modelo que puntúa los embeddings importa, pero también importa saber cuándo no usarlos. Elegir la herramienta correcta para cada consulta es su propio tipo de calidad, y es una que preferimos asumir nosotros en lugar de delegarla a quien hace la llamada.

// you bring the question. it brings the tools.

Observabilidad de agentes: hooks, Alloy y Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Los sistemas de agentes fallan de formas extrañas.

A veces el modelo es el problema. A veces la herramienta es el problema. A veces tu servidor MCP está bien, pero el agente eligió al especialista equivocado, o pasó la mitad de la sesión haciendo trabajo de shell que no esperabas, o consumió presupuesto silenciosamente en un bucle que desde afuera parecía productivo.

Si no puedes ver la diferencia, en realidad no estás operando un sistema de agentes. Estás adivinando.

Así que construimos un stack de observabilidad para nuestro propio flujo de trabajo: Claude Code, Codex, eventos de hooks de Claude, eventos de notify de Codex, OpenTelemetry nativo, Grafana Alloy y Grafana Cloud del otro lado.

La parte interesante no es «hicimos un dashboard». La parte interesante es que tuvimos que dividir la telemetría en dos flujos distintos porque ninguna fuente única nos daba el panorama completo.

El problema: la telemetría de agentes está fragmentada

Los agentes de codificación modernos ya emiten algo de telemetría. Eso ayuda, pero no es suficiente.

OTEL nativo es bueno para responder preguntas como:

¿Cuántas solicitudes hicimos?
¿Cuánto costó una sesión?
¿Dónde están los spans y las trazas?
¿Hubo un pico de latencia?

Es mucho peor para responder preguntas como:

¿En qué servidor MCP se apoyó el agente?
¿Esta falla ocurrió en Bash, en una herramienta de archivos integrada o en una llamada MCP?
¿Qué skill se activó realmente?
¿Qué tipo de subagente se despachó?
¿La sesión estaba haciendo trabajo útil o solo dando vueltas?

Esa segunda clase de pregunta vive más cerca de los hooks que de las trazas.

Pero lo inverso también es cierto: algunas de las preguntas de rendimiento más importantes viven más cerca de las trazas que de los hooks.

Si quieres saber dónde se acumuló realmente la latencia, qué spans fueron lentos, o si la sesión gastó tiempo en llamadas al modelo o en ejecución de herramientas, necesitas datos de trazas además de eventos semánticos.

La arquitectura a la que llegamos

Ejecutamos dos rutas de telemetría en paralelo.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Esa división es deliberada.

También es asimétrica. Claude Code nos da una interfaz de hooks de ciclo de vida mucho más rica. Codex nos da OTEL nativo más una interfaz de notify, así que normalizamos eventos de finalización de turno menos detallados hacia el mismo esquema de logs, en lugar de fingir que ambos runtimes exponen los mismos controles.

OTEL nativo nos da el flujo base: logs y trazas del runtime mismo, además de métricas donde el runtime realmente las emite.

Los eventos de hooks y notify nos dan la capa semántica: cosas como PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated y los metadatos clasificados que realmente nos importan al depurar el comportamiento de los agentes. Claude Code aporta aquí el flujo de eventos más rico. Codex aporta un flujo normalizado menos detallado, pero igualmente útil.

Por qué existen los hooks en primer lugar

Nuestro pipeline de hooks enriquece los eventos antes de que lleguen a Loki.

En lugar de simplemente decir «se ejecutó una herramienta», clasificamos el evento en campos como:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: qué backend MCP manejó la llamada
bash_cli: la familia de comandos de shell
subagent_type: qué tipo de especialista se despachó
agent_tool: si el origen fue Claude Code o Codex

Eso significa que podemos hacer preguntas que importan operativamente:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Esos no son campos decorativos. Son la diferencia entre «el agente se sintió lento» y «el agente pasó los últimos diez minutos en operaciones de git intensivas en shell con una alta tasa de fallos de herramientas».

Un detalle de implementación que parece más raro de lo que es: el flujo compartido de Loki sigue usando service_name="claude-code-hooks" como etiqueta incluso cuando el evento viene de Codex. La verdadera división entre runtimes ocurre en agent_tool.

Por qué Alloy está en el medio

Grafana Alloy no es solo un reenviador en esta configuración. Es el punto de aplicación de las políticas.

Apuntamos el flujo OTEL nativo de Claude Code y Codex a un proxy local de Alloy en localhost:4318, y luego dejamos que Alloy limpie el payload antes de reenviarlo a Grafana Cloud.

Eso importa porque la telemetría cruda de agentes está llena de campos de alta cardinalidad que son útiles para el análisis, pero terribles como etiquetas indexadas:

session_id
prompt_id
conteos de tokens
duraciones
blobs de parámetros de herramientas

Si indexas todo, obtienes una explosión de etiquetas y un mal día.

Así que Alloy hace tres cosas por nosotros:

Mantiene indexado un conjunto muy pequeño de etiquetas de baja cardinalidad.
Mueve los campos ruidosos pero útiles a metadatos estructurados.
Descarta por completo el ruido puro.

La idea importante es simple: observar más, indexar menos.

Por qué el flujo de hooks evita a Alloy

El flujo de hooks ya viene formado para Loki.

Para cuando send_event.py envía un evento, ya hemos decidido qué campos merecen tratamiento de etiqueta y cuáles pertenecen al cuerpo JSON estructurado. Ese flujo va directo a la puerta de enlace OTLP de Grafana Cloud en lugar de pasar de nuevo por Alloy.

Así que el sistema tiene una división de trabajo clara:

Alloy doma el flujo OTEL nativo en bruto.
El enriquecimiento de hooks hace que los eventos semánticos sean consultables.

Eso mantiene la arquitectura más simple que intentar forzar todo por una sola ruta.

Qué muestra realmente el dashboard

La captura de pantalla de abajo es de uno de los dashboards de observabilidad detrás de nuestro flujo de trabajo con agentes. No es un benchmark, y los números son solo una instantánea en el tiempo. Lo importante es la forma de los datos: feed de actividad, llamadas a herramientas, fallos, prompts y desgloses por agente, herramientas integradas, uso de MCP, comandos de shell y skills.

La parte útil es que este dashboard vive en el mismo stack de Grafana que el resto de la telemetría de agentes. Podemos filtrar por agente de origen y familia de herramientas, y mirar entre runtimes sin inventar una historia de observabilidad distinta para cada sistema.

Uno de los dashboards en vivo detrás de nuestro flujo de trabajo con agentes. Esta captura es solo una porción de un stack de Grafana compartido que también recibe telemetría de nuestros otros runtimes y sistemas de agentes. Haz clic en la imagen para ver la versión en resolución completa.

Por qué las trazas importan más de lo que parece a primera vista

Los logs nos dicen qué categoría de trabajo ocurrió. Las trazas nos dicen cómo se desarrolló el trabajo a lo largo del tiempo.

Esa distinción importa en los sistemas de agentes porque «lento» es demasiado impreciso para ser útil.

Una traza puede decirnos si el problema vino de:

la latencia del modelo
el tiempo de ejecución de herramientas
reintentos repetidos
una interacción MCP especialmente costosa
una larga cola de operaciones pequeñas que por separado parecían inofensivas

En la práctica usamos juntos el flujo de hooks y las trazas de Tempo.

Los logs de hooks responden: ¿qué tipo de cosa ocurrió?
Las trazas responden: ¿a dónde se fue el tiempo?

La combinación es lo que convierte la observabilidad de un dashboard en una explicación.

Dónde encaja Codex

Codex es parte del mismo stack, pero no es idéntico a Claude Code.

Para Codex conectamos dos piezas:

OTEL nativo de Codex hacia Alloy
Un webhook de notify hacia codex_notify.py, que mapea las finalizaciones de turno al mismo esquema de Loki que usamos para los eventos de hooks

Eso nos da un filtro unificado como agent_tool="codex-cli" dentro del mismo flujo de logs.

La salvedad honesta: el payload de notify de Codex es actualmente menos detallado que el payload de hooks de Claude Code porque no es el mismo tipo de interfaz de integración. En nuestra configuración actual, las finalizaciones de turno de Codex se pueden normalizar hacia el esquema compartido, pero la extracción detallada herramienta por herramienta sigue siendo mejor en el flujo OTEL nativo que en el bridge de notify.

Eso no es una razón para evitar esta publicación. Es justamente el punto de la publicación. Los sistemas de observabilidad reales se ensamblan a partir de señales imperfectas.

Grafana a través de MCP cambia las reglas del juego

El cambio más grande es que Grafana ya no es solo un lugar que los humanos visitan en un navegador.

En este repositorio también exponemos Grafana a través de MCP. Eso significa que un agente puede consultar Loki, Prometheus y Tempo directamente, en lugar de esperar a que un humano inspeccione manualmente los dashboards primero.

Eso convierte la observabilidad en una entrada activa del flujo de trabajo.

Un agente puede preguntar:

¿Qué familias de herramientas fallaron más en la última hora?
¿Qué servidor MCP dominó una sesión?
¿Los cambios recientes redujeron los fallos de herramientas o solo movieron el trabajo a rutas más intensivas en shell con los mismos errores?
¿Qué trazas muestran la latencia más alta o reintentos repetidos?

Una vez que tienes eso, estás muy cerca de un bucle de autosuperación.

Del dashboard al bucle de retroalimentación

Esta es la parte que encontramos más interesante.

Una vez que el stack de observabilidad es consultable desde la capa de agentes, la telemetría deja de ser un medio pasivo de consulta de informes y se convierte en una señal de control.

El bucle se ve así:

La actividad de los agentes emite trazas, métricas y logs de hooks enriquecidos.
Grafana almacena la evidencia en Loki, Tempo y Prometheus donde existen métricas.
Los agentes consultan esa evidencia a través de MCP de Grafana.
El sistema identifica una mala mezcla de herramientas, skills frágiles, enrutamiento débil o flujos de trabajo intensivos en shell que siguen produciendo errores evitables.
Los agentes u operadores ajustan prompts, configuraciones de agentes, descripciones de skills, reglas de enrutamiento o acceso a herramientas.
La siguiente sesión produce una nueva forma de telemetría, y el ciclo se repite.

Así es como pasas de un «dashboard interesante» a un «sistema de mejora medible».

El objetivo no es maximizar una sola categoría de herramientas. Es llegar a la mezcla correcta de CLI, herramientas integradas, llamadas MCP y skills para el trabajo que realmente se está haciendo.

Qué nos permite responder esto

Una vez que ambos runtimes aterrizan en el mismo stack de Grafana, podemos responder preguntas operativas mucho más rápido:

¿Los fallos se concentran en una sola familia de herramientas?
¿Los flujos de trabajo intensivos en shell están creando errores evitables donde debería existir una herramienta de más alto nivel?
¿Qué servidores MCP cargan con la mayor parte del trabajo?
¿Estamos pagando por actividad de agentes que no produce avances significativos?
¿Una sesión no está sana por culpa del modelo, de las herramientas o de la capa de orquestación?

Esto es especialmente útil en flujos de trabajo multiagente, donde «el agente estuvo ocupado» no dice casi nada.

Si un especialista sigue siendo despachado y produciendo altas tasas de fallo, eso es un problema de enrutamiento o de diseño de prompts.

Si un servidor MCP domina todas las llamadas, eso puede ser buena arquitectura o una señal de que todo lo demás es peso muerto.

Si los fallos de herramientas se disparan mientras el costo se mantiene alto, tienes un problema operativo, no un problema de calidad.

Si el trabajo de shell sigue fallando de formas predecibles y evitables donde debería existir una herramienta de más alto nivel, esa es una señal de producto.

Si una skill se activa constantemente pero no mejora los resultados, esa es una señal de prompt o de enrutamiento.

La verdadera lección

La lección más profunda aquí es que la observabilidad de agentes necesita tanto telemetría de runtime como telemetría de flujo de trabajo.

La telemetría de runtime te dice qué hizo el sistema.

La telemetría de flujo de trabajo te dice qué creía el agente que estaba haciendo.

Necesitamos ambas.

Si solo conservas trazas y contadores, te pierdes la capa semántica. Si solo conservas eventos de hooks, te pierdes la latencia, los spans y el panorama más amplio del runtime.

Y si conservas ambas pero nunca las retroalimentas hacia la capa de agentes, tienes monitoreo, no adaptación.

La combinación es lo que hace que el sistema sea lo bastante explicable para operarlo y lo bastante ajustable para mejorarlo.

Lo que todavía es imperfecto

Todavía quedan asperezas.

No todos los eventos de hooks incluyen los datos de duración y tokens que quisiéramos.
Algunas de las mejores vistas de tiempos siguen viniendo de las trazas de Tempo, no de los logs de hooks.
Hoy Codex es semánticamente menos rico que Claude Code en el flujo de eventos enriquecido.
La captura del dashboard es una vista de operaciones en vivo, no una pieza de marketing pulida.

Ese último punto es intencional. Preferimos mostrar el panel de instrumentos real antes que fingir que los sistemas de agentes se explican mágicamente por sí solos.

Por qué esto le importa a Maguyva

Maguyva trata de darles a los agentes mejor inteligencia de código. Pero en cuanto los agentes empiezan a hacer trabajo realmente útil, aparece de inmediato un nuevo requisito: necesitas ver cómo se están comportando.

La calidad de la búsqueda, la calidad del enrutamiento, la selección de herramientas y la eficiencia del contexto se convierten todas en problemas observables.

Por eso creemos que vale la pena escribir sobre esto. El stack de agentes del futuro no es solo prompts y herramientas. Es prompts, herramientas y la capa de instrumentación que te dice si todo el conjunto está funcionando.

Si estás construyendo flujos de trabajo de agentes serios, la observabilidad no es infraestructura opcional. Es parte del producto.

Extraer conocimiento para cerrar el bucle: cómo los cambios se convierten en memoria institucional

Tue, 03 Feb 2026 00:00:00 GMT

Las cifras de esta publicación reflejan el sistema al momento de su publicación (febrero de 2026). Consulta nuestra página del equipo para ver las cifras actuales.

Todo equipo de ingeniería enfrenta el mismo desafío: los cambios ocurren constantemente, pero el por qué detrás de esos cambios desaparece. Seis meses después, alguien pregunta «¿por qué adoptamos DuckDB para las etapas del pipeline?» y la respuesta solo vive en la cabeza de quien tomó esa decisión, si es que todavía sigue por ahí.

Construimos un flujo de trabajo de minería que cierra este bucle. Los cambios fluyen a través de commits de Git, se procesan mediante nuestro pipeline de minería, se convierten en entradas de changelog estructuradas y registros de decisiones arquitectónicas, y luego retroalimentan a nuestros agentes de IA mediante consultas por CLI. El resultado: memoria institucional a la que tanto humanos como IA pueden acceder.

El problema: las decisiones se evaporan

Considera un escenario típico. Un desarrollador hace commit:

feat(canonical): add DuckDB runtime for pipeline stages

Este commit representa una elección arquitectónica significativa. El equipo evaluó opciones, consideró los compromisos, y se decidió por DuckDB por razones específicas. Pero todo ese contexto vive en:

Un hilo de Slack (probablemente borrado)
La memoria de alguien (definitivamente se va desvaneciendo)
Un comentario en el código (tal vez, si tienes suerte)

Tres meses después, un nuevo integrante del equipo pregunta: «¿debería usar DuckDB o SQLite para esta nueva etapa?». Sin memoria institucional, o reinventa la rueda o toma decisiones inconsistentes.

El bucle: de los commits al contexto

Nuestro flujo de trabajo de minería transforma el historial de Git en conocimiento consultable:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

La idea clave: tanto los changelogs como las decisiones arquitectónicas fluyen del mismo historial de Git, procesado a través de un pipeline unificado. Esto garantiza que nada se escape.

Cómo funciona la minería

Paso 1: sincronizar el índice

uv run orkestra mine sync

Este comando escanea el historial de Git y construye un índice de todos los commits. Extrae señales estructuradas de cada commit:

Tipo de commit según Conventional Commits (feat, fix, chore, docs)
Alcance (qué paquete o área)
Marcadores de cambios disruptivos
Archivos tocados y métricas de complejidad

Paso 2: verificar el estado de cobertura

uv run orkestra mine status

Así se ve nuestro estado actual:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15,637 commits procesados. 476 se convirtieron en decisiones arquitectónicas. 6,799 se convirtieron en entradas de changelog. Cada commit está clasificado.

Paso 3: obtener candidatos para revisión

uv run orkestra mine candidates --limit 50 --full

Esto muestra los commits que todavía no se han procesado, con el contexto completo para su clasificación:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Las señales ayudan a guiar la clasificación: is_releasable_type: true sugiere que esto debería aparecer en el changelog. El gran número de inserciones y los archivos de infraestructura sugieren que también podría ser una decisión arquitectónica.

Paso 4: clasificar commits

Aquí se bifurcan dos caminos: entradas de changelog y decisiones arquitectónicas.

Para entradas de changelog:

uv run orkestra mine classify abc123 --changelog added

Esto registra que el commit abc123 debería aparecer en el changelog bajo la categoría «Added».

Para decisiones arquitectónicas:

Primero, obtén un ID de decisión real:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Luego clasifica con el ID de decisión:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Esto vincula el commit a un registro de decisión que se creará o actualizará.

Para procesamiento por lotes (lo que en realidad hacemos):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

El formato JSONL admite ambos dominios en una sola pasada:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Paso 5: renderizar las salidas

uv run orkestra registry changelog render --package <pkg>

Esto genera archivos CHANGELOG.md por paquete a partir del ledger. Los changelogs son artefactos derivados: bórralos y se regeneran perfectamente a partir del ledger fuente.

La estructura del registro de decisiones

Las decisiones extraídas se convierten en archivos YAML con metadatos ricos:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Cada decisión enlaza de vuelta a sus commits de origen. Cada decisión especifica qué archivos afecta. Las relaciones entre decisiones son explícitas.

Integración con la CLI: consultando la memoria institucional

Aquí es donde se cierra el bucle. Los agentes pueden consultar decisiones a través de la CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Devuelve decisiones sobre lógica de reintento, manejo de errores, patrones de recuperación.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Devuelve el registro de decisión completo con contexto, justificación e impacto.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Muestra qué elecciones arquitectónicas se tomaron recientemente.

Cómo usan esto los agentes

Las instrucciones base de nuestro orquestador incluyen:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Cuando se le pide a un agente que implemente algo relacionado con DuckDB, primero puede verificar:

uv run orkestra registry decisions search --query "DuckDB"

Y descubrir DEC-PL-142, aprendiendo:

Por qué elegimos DuckDB (context)
Cómo usarlo correctamente (agent_guidance)
Qué archivos revisar (files)
Qué decisiones relacionadas existen (related)

El agente no reinventa la rueda. Construye sobre patrones ya establecidos.

La prueba de las tres preguntas

No todo commit merece un registro de decisión. Usamos la prueba de las tres preguntas para filtrar:

¿Fue difícil de tomar? ¿Requirió un análisis significativo, evaluación de compromisos o debate?
¿Es costoso de cambiar? ¿Revertir esta decisión requeriría un retrabajo significativo?
¿Tiene impacto en todo el sistema? ¿Afecta a varios paquetes o establece patrones que otros seguirán?

Si un commit responde «sí» a al menos una de estas preguntas, es candidato para la extracción de una decisión. Nuestra tasa típica: 1-4 decisiones por cada 100 commits (alrededor del 1-4%).

Para las entradas de changelog, el umbral es más bajo: cualquier cambio visible para el usuario (funciones, correcciones, mejoras) se registra. Las tareas internas, las actualizaciones de documentación y las refactorizaciones normalmente se omiten. Nuestra tasa típica: 30-50 entradas de changelog por cada 100 commits.

Almacenamiento de datos: ledgers de solo anexado

El sistema de minería usa ledgers JSONL de solo anexado para una operación multiagente sin conflictos:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

El formato JSONL con merge=union en .gitattributes significa que varios agentes pueden clasificar commits simultáneamente sin conflictos de fusión. Cada línea es independiente.

Controles de validación

Antes de cualquier sesión de minería, ejecutamos una validación:

uv run orkestra mine validate --quick

Esto verifica:

Validez del formato del SHA
Cumplimiento del formato del ID de decisión
Ausencia de entradas duplicadas para el mismo SHA
Que las decisiones referenciadas realmente existan

Después de la clasificación, validamos de nuevo antes de hacer commit de los cambios.

Por qué esto importa

El bucle de retroalimentación que construimos resuelve varios problemas:

Para nuevos integrantes del equipo: en lugar de preguntar «¿por qué hicimos X?», pueden buscar en el registro de decisiones. El contexto se conserva.

Para los agentes de IA: no operan en el vacío. Pueden consultar el conocimiento institucional antes de hacer recomendaciones. Cuando se les pide agregar una nueva etapa al pipeline, pueden descubrir el patrón de DuckDB y seguirlo.

Para la consistencia arquitectónica: las decisiones son explícitas y consultables. Cuando alguien propone un enfoque que contradice una decisión existente, el sistema puede sacar a la luz el conflicto.

Para la generación del changelog: las notas de la versión no son una carrera de último minuto. Son un subproducto de la clasificación continua durante el desarrollo.

Para la incorporación de nuevos integrantes: los nuevos agentes heredan el contexto completo de la base de código. No solo ven el código, ven las decisiones que lo formaron.

Estado actual

A la fecha:

15,637 commits procesados a través del pipeline
476 decisiones arquitectónicas extraídas y documentadas
6,799 entradas de changelog registradas
100% de cobertura en ambos dominios

Cada commit desde que empezamos ha sido clasificado. La memoria institucional está completa y es consultable.

Cómo empezar

Si quieres implementar algo similar:

Empieza con commits en el formato Conventional Commits. El pipeline de minería funciona mejor cuando los commits tienen prefijos estructurados (feat:, fix:, chore:).
Define tus dominios. Nosotros usamos dominios como pipeline, agent-design, observability, data-modeling. Estos organizan las decisiones por área.
Construye el hábito de la clasificación. La minería funciona cuando los equipos clasifican commits regularmente. El procesamiento por lotes con asistencia de LLM ayuda a escalar.
Haz que las decisiones sean consultables. El valor se multiplica cuando los agentes pueden buscar decisiones vía CLI. Estructura tu salida para consumo por máquinas.
Cierra el bucle. Las decisiones deberían influir en el trabajo futuro. Incluye referencias a decisiones en las instrucciones de los agentes y en las listas de verificación de revisión de código.

El objetivo no es una documentación perfecta. Es hacer que el por qué detrás de los cambios sea accesible tanto para humanos como para IA, hoy y dentro de seis meses. Cuando los cambios se convierten en memoria institucional, los equipos construyen sobre patrones establecidos en lugar de reinventarlos.

El flujo de trabajo de minería es parte de nuestro motor de orquestación, específicamente el módulo de motor de contexto dentro de nuestro paquete de orquestación.

Minería de skills: de 3,500 candidatas a 466 capacidades

Tue, 27 Jan 2026 00:00:00 GMT

Las cifras de esta publicación reflejan el sistema al momento de su publicación (enero de 2026). Consulta nuestra página del equipo para ver las cifras actuales.

El problema de las 3,500 skills

Cuando empezamos a construir un sistema de orquestación de agentes, enfrentamos un desafío interesante: hay miles de skills potenciales dispersas por todo el ecosistema de IA. Repositorios de GitHub, documentación de proveedores, proyectos comunitarios, patrones internos: las skills existen en todas partes. Pero ¿cuáles importan? ¿Cuáles funcionan? ¿Y cómo mantienes una biblioteca de skills coherente que los agentes realmente puedan usar?

Nuestra respuesta: un bucle sistemático de minería e ingesta.

Los números de hoy

Apenas tres meses después de que Anthropic lanzara Agent Skills el 16 de octubre de 2025, así estábamos parados cuando se publicó esta entrada el 27 de enero de 2026:

Métrica	Cantidad
Candidatas identificadas	3,500+
Skills adoptadas	466
Skills de proveedores	373
Skills internas	93
Proveedores activos	25+
Tokens promedio por skill	2,834
Herramientas referenciadas	89
Etiquetas únicas	635

Revisamos más de 3,500 skills candidatas. Adoptamos 466. Eso es una tasa de adopción del 13% — y esa selectividad es deliberada.

El sistema de niveles de conocimiento

No todas las skills son iguales. Las organizamos en cinco capas de conocimiento (K0-K4), cada una representando un alcance de aplicabilidad distinto:

K0: fundamentos (universal)

Skills que todo agente debería tener. Representan capacidades de «buen pensador» que funcionan en cualquier lugar.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Las skills K0 son portables a cualquier proyecto, cualquier dominio, cualquier stack. Codifican patrones cognitivos universales.

K1: identidades (disciplina)

Skills de «buen ingeniero» o «buen investigador» que aplican en distintos proyectos dentro de una disciplina.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: dominios (experticia temática)

Skills de «buen experto en bases de datos» o «buen ingeniero de seguridad» portables dentro de un campo.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: stacks (tecnología)

Skills de «buen usuario de Supabase» o «buen desarrollador de Cloudflare» para stacks tecnológicos específicos.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: proyecto (organización)

Skills específicas de nuestra organización y nuestros flujos de trabajo.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

El bucle de minería

Fase 1: descubrimiento

Las skills vienen de todas partes:

Repositorios de proveedores: AWS, Anthropic, Cloudflare, Supabase y colaboradores de la comunidad publican colecciones de skills. Rastreamos más de 25 raíces de proveedores.

Proyectos comunitarios: GitHub está lleno de plantillas de Claude Code, patrones de agentes y definiciones de flujos de trabajo.

Patrones internos: a medida que nuestro equipo resuelve problemas, emergen patrones. Estos se formalizan en skills.

Minería de documentación: la documentación técnica a menudo contiene skills implícitas — procedimientos, listas de verificación, árboles de decisión.

El descubrimiento es continuo. Usamos un backlog de skills para rastrear candidatas antes de la evaluación formal.

Fase 2: evaluación

Cada candidata pasa por la misma rúbrica:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Deben cumplirse los cinco criterios de producto. Por eso se rechaza el 87% de las candidatas.

Luego cada candidata pasa por una revisión de confianza separada. No tratamos un repositorio oficial de un proveedor, un mantenedor de la comunidad bien conocido y un repositorio aleatorio de GitHub como fuentes de verdad equivalentes.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Los proveedores confiables reciben una revisión de procedencia más ligera, pero no un pase libre. Las fuentes no confiables o desconocidas reciben una auditoría manual más profunda, y no ejecutamos scripts incluidos hasta que hayan sido leídos, delimitados y clasificados como seguros.

Análisis de brechas: antes de adoptar, buscamos en nuestro registro:

uv run orkestra skills search "<capability>"

Si ya lo tenemos, no lo necesitamos. Si tenemos algo cercano, podríamos fusionar en lugar de adoptar.

Puntuación de profundidad y estándares: también puntuamos qué tan a fondo una candidata usa el modelo agent-skill. Un solo SKILL.md todavía puede ser útil, pero las skills más profundas son más valiosas cuando separan las instrucciones de las referencias, scripts y assets de la manera que agentskills.io recomienda.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Las estrellas de GitHub pueden elevar un poco un puntaje de credibilidad, pero nunca rescatan a una skill superficial o insegura. Un repositorio con muchas estrellas y un solo SKILL.md vago y scripts opacos puntúa por debajo de un repositorio más pequeño con una descripción precisa, referencias cuidadosamente seleccionadas en references/, y helpers atómicos que realmente aprovechan toda la capacidad de la skill.

Análisis estructural: verificamos la calidad de la skill:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Si una candidata incluye scripts, esa revisión se vuelve más estricta. Una buena skill no solo es útil; tiene que ser legible, acotada y segura de entregar a un agente. Ese filtro de seguridad por sí solo descalifica una porción significativa de candidatas por lo demás interesantes.

Fase 3: ingesta

Cuando una skill pasa la evaluación, entra al registro. Pero las skills nunca se adoptan sin cambios. Se modifican para encajar en nuestro sistema.

Modificaciones al adoptar:

Normalización de metadatos: cada skill recibe nuestro esquema de frontmatter
Asignación de nivel K: las skills se colocan en la capa de conocimiento correspondiente
Enriquecimiento de etiquetas: se agregan etiquetas para facilitar el descubrimiento
Declaración de herramientas: las herramientas permitidas se declaran explícitamente
Alineación de secciones: el contenido se reestructura para coincidir con nuestra plantilla

Un YAML de skill típico después de la ingesta:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Fase 4: asignación de alcance

Las skills se asignan a alcances (scopes) — categorías que determinan qué agentes cargan qué skills:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Los agentes declaran sus alcances, y las skills se asignan automáticamente:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Fase 5: materialización

Las skills no viven como YAML en producción. Se renderizan en archivos SKILL.md que Claude Code puede cargar:

uv run orkestra sync

Este comando:

Lee todas las definiciones YAML de skills
Las renderiza mediante plantillas Jinja
Escribe archivos SKILL.md en .claude/skills/
Organiza por nivel K (foundations/, identities/, domains/, stacks/, project/)

La estructura de salida final:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

El patrón de alcance latente

Uno de nuestros patrones más poderosos son las skills «adoptadas pero no cargadas». Las llamamos alcances latentes (dormant scopes).

Considera las skills de computación científica del repositorio k-dense-scientific. Adoptamos más de 120 skills que cubren bioinformática, química, computación cuántica e informática clínica. Pero la mayoría de nuestros agentes no necesitan acoplamiento molecular ni análisis de expresión génica.

En lugar de cargar las 120 skills en cada agente (inflando las ventanas de contexto), nosotros:

Adoptamos las skills con un alcance específico (por ejemplo, bioinformatics)
Las mantenemos latentes — registradas pero no cargadas
Las habilitamos solo cuando un agente declara ese alcance

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Este patrón nos permite tener 466 skills en el registro mientras los agentes típicos solo cargan entre 40 y 60 relevantes.

Tipos de skills

Las skills vienen en tres patrones cognitivos:

Workflow (flujo de trabajo)

Pasos procedimentales ordenados: «1. Haz X, 2. Luego Y, 3. Finalmente Z»

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Discipline (disciplina)

Salvaguardas de comportamiento: «Siempre X», «Nunca Y», «Prefiere Z»

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist (lista de verificación)

Criterios de verificación: «Confirma X», «Verifica Y», «Revisa Z»

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Controles de calidad

Cada skill debe pasar la validación antes de lanzarse:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Las descripciones deben tener entre 50 y 400 caracteres con frases de activación («Usar cuando…», «Cuando necesites…») para que Claude Code sepa cuándo sugerirlas.

Validamos continuamente:

uv run orkestra validate --show-warnings

El ecosistema de proveedores

Nuestras 373 skills de proveedores vienen de:

Proveedor	Skills	Dominio
AWS Agent	19	Servicios en la nube
Anthropic	12	Generación de documentos
Cloudflare	8	Edge computing
Supabase	5	Bases de datos
k-dense	100+	Computación científica
silvainfm	4	Ciencia de datos
Java Developer Kit	45+	Spring/Java
Vercel	1	Automatización de navegador

Cada raíz de proveedor se declara en metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Cuando se ejecuta orkestra sync, las skills de proveedores se enlazan simbólicamente en .claude/skills/vendor/ con su espacio de nombres de proveedor.

Lo que hemos aprendido

La selectividad rinde frutos. Es tentador adoptar todo lo que parece útil. Pero cada skill cuesta tokens. Con un promedio de 2,834 tokens por skill, el exceso duele rápido. Nuestra tasa de adopción del 13% mantiene a los agentes ligeros.

La estructura habilita el descubrimiento. El sistema de niveles K no es solo organización, se trata de portabilidad. Las skills K0 se pueden reutilizar en cualquier lugar. Las skills K4 son deliberadamente específicas del proyecto. Esta claridad ayuda tanto a humanos como a agentes a encontrar lo que necesitan.

Los alcances latentes escalan. Puedes adoptar cientos de skills sin cargarlas todas. Los alcances te permiten construir un registro exhaustivo mientras mantienes manejables las ventanas de contexto de cada agente.

La modificación al adoptar es esencial. Las skills de proveedores en bruto rara vez encajan en tu sistema. El proceso de ingesta — agregar metadatos, asignar niveles, enriquecer etiquetas — hace que las skills externas funcionen internamente.

La minería es continua. El número 3,500 sigue creciendo. Aparecen nuevos repositorios de proveedores. Emergen patrones comunitarios. Se solidifican flujos de trabajo internos. El bucle nunca se detiene.

Qué sigue

Estamos trabajando en varias mejoras:

Detección automatizada de brechas: alertar cuando fallos comunes de agentes podrían resolverse con una skill no adoptada
Flujos de desuso de skills: proceso formal para retirar skills que fueron reemplazadas o que no se usan
Dependencias entre skills: declaración explícita de los prerrequisitos de una skill
Analítica de uso: rastrear qué skills invocan realmente los agentes frente a cuáles solo cargan

El bucle de minería de skills es infraestructura. No es glamoroso. Pero es lo que hace que 41 agentes funcionen de forma coherente con 466 capacidades mientras se mantienen dentro de los límites de contexto.

Esa es la historia de cómo 3,500 se convierte en 466. No ignorando 3,000, sino evaluándolas sistemáticamente y adoptando solo lo que funciona.

¿Quieres ver el sistema de skills en acción? Consulta uv run orkestra skills list para explorar nuestro registro actual.

Divulgación progresiva: ventanas CLI hacia los sistemas de agentes

Tue, 20 Jan 2026 00:00:00 GMT

Las cifras de esta publicación reflejan el sistema al momento de su publicación (enero de 2026). Consulta nuestra página del equipo para ver las cifras actuales.

Los sistemas de agentes son opacos por diseño. Toman decisiones, invocan herramientas y coordinan trabajo entre decenas de especialistas. Pero cuando algo sale mal, o cuando simplemente quieres entender qué está pasando, ¿dónde miras?

La respuesta es la divulgación progresiva: una interfaz en capas que revela exactamente tanta complejidad como necesitas, exactamente cuando la necesitas.

El problema de la opacidad

Un sistema moderno de orquestación de agentes puede tener:

Más de 40 agentes especialistas, cada uno con capacidades distintas
Más de 700 skills que abarcan automatización interna e integraciones con proveedores
Más de 470 decisiones arquitectónicas que moldean el comportamiento
Decenas de servidores de herramientas MCP que proporcionan capacidades externas

Esta complejidad es intencional. Los agentes necesitan acceso a contexto rico — conocimiento de dominio, inteligencia de código, esquemas de bases de datos — para tomar buenas decisiones. Pero esa misma riqueza crea un problema de visibilidad.

¿Cómo sabes qué agente maneja las migraciones de bases de datos? ¿Qué decisiones moldearon el comportamiento de clasificación del sistema de búsqueda? ¿A qué herramientas tiene acceso el asesor de arquitectura?

Sin acceso estructurado, te queda leer el código fuente o esperar que la documentación esté al día.

La divulgación progresiva como arquitectura

La divulgación progresiva no es solo un patrón de interfaz de usuario. Es un principio arquitectónico: organizar la información en capas, cada una más profunda que la anterior, para que los usuarios puedan detenerse en el nivel que responde su pregunta.

Para los sistemas de agentes, esto se traduce en comandos de CLI con profundidad creciente:

Nivel	Comando	Pregunta que responde
1	`orkestra system status`	¿Todo está sano?
2	`orkestra agents list`	¿Qué agentes existen?
3	`orkestra agents info <name>`	¿Qué hace este agente?
4	`orkestra decisions search`	¿Por qué funciona así?
5	Herramientas MCP de Maguyva	Muéstrame el código.

Cada nivel responde una pregunta de seguimiento natural. Rara vez necesitas saltar directo al nivel 5.

Nivel 1: salud del sistema

La primera pregunta siempre es: ¿todo está funcionando?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Un comando. Cuatro números. Suficiente para saber que el sistema está configurado y que los registros están poblados.

Si el conteo de agentes cae inesperadamente o las skills fallan al cargar, lo ves aquí primero. No hace falta bucear en los logs.

Nivel 2: inventario de agentes

Una vez que sabes que el sistema está sano, la siguiente pregunta es: ¿qué hay disponible?

$ orkestra agents list

Esto devuelve datos estructurados — nombres de agentes, descripciones, preferencias de modelo, cobertura de dominio. La salida es JSON por defecto, lo que facilita canalizarla hacia jq para filtrar:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

¿Quieres agentes que manejen trabajo de bases de datos? El comando de búsqueda lo acota:

$ orkestra agents search "database"

Esto escanea nombres, descripciones y capacidades. Encuentras al especialista correcto sin leer 40 definiciones de agentes.

Nivel 3: análisis profundo del agente

¿Encontraste un agente que parece relevante? El comando info lo revela todo:

$ orkestra agents info architecture-advisor

La salida incluye:

Metadatos: nombre, categoría, preferencia de modelo, descripción
Dominios: qué áreas de conocimiento cubre este agente
Identidad: rasgos de carácter (architect, strategist, knowledge-architect)
Guías de herramientas: qué documentación de herramientas se inyecta en el contexto
Herramientas: la lista completa de herramientas MCP disponibles para este agente

Aquí tienes una muestra de lo que ves:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Esto te dice exactamente qué puede hacer el agente. No hace falta leer el código fuente.

Nivel 4: arqueología de decisiones

Los agentes se comportan de acuerdo con decisiones documentadas. Cuando necesitas entender por qué algo funciona de una manera particular, el registro de decisiones es la fuente de verdad.

$ orkestra decisions search "agent"

Esto devuelve las decisiones arquitectónicas que coinciden:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Cada decisión tiene procedencia completa — cuándo se tomó, por qué, qué compromisos se consideraron, qué commits la implementaron:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Esta es documentación arquitectónica que se mantiene al día porque se extrae de los commits, no se mantiene manualmente.

Nivel 5: inteligencia de código directa

Cuando necesitas ver la implementación real — no metadatos sobre ella — las herramientas MCP de Maguyva dan acceso directo.

Desde dentro de una sesión de agente:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Esto enruta automáticamente entre búsqueda semántica, de texto y AST para encontrar código relevante. Para símbolos específicos:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Para análisis de dependencias:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Estas no son solo reemplazos de grep. Tienen en cuenta el grafo, están indexadas semánticamente, y están integradas con la misma inteligencia de código que impulsa a los propios agentes.

Búsqueda unificada entre registros

A veces no sabes qué registro tiene la respuesta. La búsqueda unificada abarca todo:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 coincidencias en cinco registros. El resumen te dice dónde profundizar. Elimina --summary para resultados detallados, o agrega --limit 5 para mantener la salida manejable.

Por qué esto importa

La divulgación progresiva no se trata solo de conveniencia. Cambia cómo interactúas con sistemas complejos.

La depuración se vuelve manejable. Cuando un agente toma una decisión inesperada, no haces grep en los logs. Verificas a qué herramientas tiene acceso (agents info), qué decisiones moldean su comportamiento (decisions search), y rastreas la implementación si hace falta (intelligent_search).

La incorporación se acelera. Los nuevos integrantes del equipo no necesitan leer toda la base de código. Empiezan con system status, exploran con agents list, y profundizan solo cuando se topan con algo que no entienden.

La documentación se mantiene al día. Como la CLI lee de los mismos registros que configuran a los agentes, la salida siempre es precisa. No hay desfase entre lo que dice la documentación y lo que hace el sistema.

La CLI como interfaz

Podríamos haber construido un dashboard web. Podríamos haber escrito documentación extensa. En cambio, construimos una CLI que lee de la fuente de verdad.

La CLI tiene ventajas:

Componible: canaliza la salida a través de jq, intégrala con scripts
Automatizable: automatiza verificaciones, genera reportes
Rápida: sin cargas de página, sin flujos de autenticación
Precisa: lee la configuración real, no una representación en caché

Para sistemas donde la corrección importa más que la estética, la CLI gana.

Construyendo tu propia divulgación progresiva

Si estás construyendo sistemas de agentes, considera cómo los usuarios los van a inspeccionar:

Empieza con verificaciones de salud. Un comando que te diga si las cosas están funcionando.
Ofrece vistas de inventario. Lista lo que existe antes de explicar qué hace.
Habilita consultas dirigidas. La búsqueda le gana a la navegación a gran escala.
Expón la procedencia. Deja que los usuarios rastreen las decisiones hasta sus orígenes.
Conecta con la inteligencia de código. Tarde o temprano, los usuarios necesitan ver la implementación.

Cada capa responde una pregunta de seguimiento. Constrúyelas en orden de frecuencia — la mayoría de los usuarios se detienen en la capa 2 o 3. Solo los usuarios avanzados llegan a la capa 5.

El objetivo no es exponer todo. Es exponer exactamente lo necesario, exactamente cuando se necesita. Eso es la divulgación progresiva aplicada a la arquitectura de agentes.

Ground Truths: anclando a los agentes de IA en la realidad

Tue, 13 Jan 2026 00:00:00 GMT

Las cifras de esta publicación reflejan el sistema al momento de su publicación (enero de 2026). Consulta nuestra página del equipo para ver las cifras actuales.

Los agentes de IA son notablemente capaces. Pueden razonar, sintetizar y generar. Pero tienen una debilidad fundamental: se inventan cosas. No maliciosamente, sino con confianza. Un agente puede inventar parámetros de API que no existen, hacer referencia a configuraciones que nunca se definieron, o aplicar patrones de sus datos de entrenamiento que contradicen tu arquitectura real.

La mitigación estándar es «dale más contexto al agente». Pero el contexto puede ser contradictorio. La documentación se desvía de la implementación. Los comentarios mienten. Incluso el código puede engañar cuando se lee sin entender la intención.

Necesitábamos algo más explícito. Algo que no pudiera ignorarse ni malinterpretarse. Algo que anclara a los agentes a una realidad verificable.

Los llamamos Ground Truths: hechos de referencia.

¿Qué es un Ground Truth?

Un ground truth es una declaración de hecho explícita y versionada que los agentes deben respetar. No es documentación. No es un comentario. Es una entidad de primera clase en el sistema con:

Un identificador único (como GT-MAG-015 o GT-MAG-036)
Un estado de ciclo de vida (vigente, tentativo o en desuso)
Un alcance (de toda la plataforma, específico de un paquete o acotado a un dominio)
Evidencia (rutas de archivo, URLs o referencias que respaldan la declaración)
Guía para el agente (instrucciones explícitas de qué hacer y qué evitar)

Aquí hay un ejemplo de nuestra plataforma de inteligencia de código Maguyva:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Esto no es prosa. Es un contrato. Cuando un agente se encuentra con este ground truth, sabe que:

El comportamiento predeterminado es determinista (resultados vacíos, no conjeturas difusas)
Hay parámetros específicos (find_similar, exact_match) con comportamientos definidos
Existe evidencia en archivos específicos que se pueden verificar
La declaración se verificó en una fecha específica

La anatomía de un registro de Ground Truths

Los ground truths viven en registros YAML bajo ai_assets/reference/ground_truths.yaml. Cada paquete o dominio puede tener su propio registro. La estructura es:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

El registro incluye metadatos sobre la colección misma, configuración de renderizado para la generación de documentación, y las declaraciones en sí. Cada declaración sigue un esquema estricto validado por modelos de Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Cómo acceden los agentes a los Ground Truths

Los ground truths se exponen a través de múltiples canales:

1. Documentación renderizada

El comando orkestra sync transforma los registros YAML en markdown legible:

uv run orkestra sync

Esto genera archivos GROUND_TRUTHS.md que se incluyen en el contexto del agente. La salida renderizada agrupa las declaraciones por estado y categoría:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Búsqueda por CLI

Los agentes con acceso a shell pueden buscar ground truths mediante programación:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

La función de búsqueda puntúa las coincidencias en varios campos con relevancia ponderada:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Composición de contexto

Cuando los agentes se renderizan a partir de definiciones YAML, su contexto puede hacer referencia a registros de ground truths:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Esto garantiza que los ground truths relevantes se carguen antes de que el agente comience a trabajar.

Categorías de Ground Truths

Mirando nuestros registros en conjunto, los ground truths se agrupan en varios patrones:

Principios del producto

Restricciones sobre qué es y qué no es el producto:

«Maguyva es de solo lectura respecto de los repositorios de los usuarios; el único activo que no se puede reconstruir es la caché de embeddings pagada». (GT-MAG-001)

Límites de arquitectura

Dónde viven las responsabilidades y por qué:

«Los límites entre pipeline y Maguyva son intencionales: pipeline es reutilizable, Maguyva contiene la lógica específica de código, y CQRS separa las escrituras de las etapas del pipeline de las lecturas del servidor». (GT-MAG-006)

Reglas antialucinación

Mandatos explícitos que mantienen los contratos de herramientas deterministas en lugar de inferidos:

«La coincidencia difusa de símbolos es opcional mediante find_similar=true. El comportamiento predeterminado devuelve resultados vacíos para símbolos inexistentes; exact_match=true impone coincidencia estricta y desactiva todos los mecanismos de respaldo difusos». (GT-MAG-015)

Controles de calidad

Estándares que deben mantenerse:

«Los cambios a la infraestructura compartida (post_filters.py, extractores de relaciones, handlers compartidos) DEBEN validarse contra TODOS los lenguajes compatibles mediante la generación de un manifiesto completo antes de hacer commit. Una validación de un solo lenguaje es insuficiente para código compartido». (GT-MAG-036)

Patrones de código

Requisitos de implementación:

«Usa asyncio.to_thread() para trabajo limitado por CPU en contextos asíncronos; el patrón en desuso loop.run_in_executor() no debe usarse en código nuevo». (GT-MAG-018)

El ciclo de vida de un Ground Truth

Los ground truths no son estáticos. Evolucionan a través de un ciclo de vida definido:

Tentativo

Una verdad propuesta bajo evaluación. La declaración se registra, pero puede cambiar:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Vigente

Una verdad verificada que los agentes deben respetar. La evidencia ha sido validada:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

En desuso

Una verdad que ya no aplica. Se conserva como referencia histórica con un puntero a lo que la reemplazó:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

¿Por qué no simplemente documentación?

La documentación cumple un propósito distinto. Explica. Enseña. Puede ser vaga, puede usar calificadores como «generalmente» o «típicamente».

Los ground truths no pueden ser vagos. Son afirmaciones. O aplican, o no aplican.

Considera la diferencia:

Documentación: «La API generalmente devuelve resultados vacíos cuando no se encuentra un símbolo, aunque la coincidencia difusa puede estar habilitada en algunas configuraciones».

Ground Truth: «El comportamiento predeterminado devuelve resultados vacíos para símbolos inexistentes; exact_match=true impone coincidencia estricta y desactiva todos los mecanismos de respaldo difusos».

La primera es útil para que los humanos aprendan el sistema. La segunda es accionable para que los agentes tomen decisiones.

Guía para el agente: qué hacer y qué evitar

Algunos ground truths incluyen guía explícita para el agente:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Esto elimina la ambigüedad. Un agente que lee esto sabe no solo qué es verdad, sino qué acciones implica esa verdad.

Verificación y mantenimiento

Los ground truths requieren mantenimiento. Rastreamos:

last_verified: cuándo alguien confirmó que la declaración sigue siendo válida
evidence: archivos que respaldan la declaración (se puede verificar si existen)
source: de dónde se originó la verdad (inspección por CLI, revisión de arquitectura, aprendizaje posterior a un incidente)

Un ground truth con fechas de verificación desactualizadas o enlaces de evidencia rotos es una señal para investigar. O la verdad sigue siendo válida y necesita reverificación, o la realidad cambió y la verdad necesita actualizarse.

Ejemplos reales de producción

Límite de seguridad

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Este ground truth evita una clase de «mejoras de seguridad» mal orientadas que romperían el producto.

Precisión en tiempo de extracción

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Esto surgió de una experiencia dolorosa. Los agentes solían parchar paquetes de lenguaje fallidos agregando filtros que solo actuaban en el validador, lo que hacía que el arnés de pruebas se viera más verde, mientras que el extractor real de Maguyva seguía emitiendo las aristas equivocadas. La regla obliga a que las correcciones vuelvan a la ruta real: configuración YAML, consultas o handlers.

Filtrado en múltiples niveles

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Esto evita que los agentes agreguen filtros en el lugar equivocado, un error común que causaba regresiones de precisión.

Integración con el sistema de orquestación

Los ground truths son una capa de un sistema de contexto más amplio:

Decisiones arquitectónicas (ADRs) - Registran por qué elegimos el enfoque A sobre el B
Ground Truths - Indican qué está establecido con certeza en este momento
Patrones de dominio - Describen cómo hacer las cosas correctamente
Antipatrones - Describen qué evitar y por qué

Un agente que trabaja en el sistema tiene acceso a los cuatro. Los ground truths proporcionan el ancla factual, mientras que las decisiones explican la historia, los patrones guían la implementación y los antipatrones advierten sobre los riesgos.

Midiendo el impacto

Desde que introdujimos los ground truths, hemos observado:

Menos ciclos de «corregir la corrección alucinada»
Toma de decisiones más segura por parte de los agentes cuando los hechos son claros
Mejores revisiones de PR porque las expectativas son explícitas
Menor tiempo de incorporación para nuevos agentes (y humanos)

La inversión en mantener los ground truths se paga sola con menos depuración y límites de sistema más claros.

Cómo empezar

Para agregar un ground truth a tu sistema:

Crea un ground_truths.yaml en el directorio ai_assets/reference/ de tu paquete
Define los metadatos y la configuración de renderizado
Agrega declaraciones siguiendo el esquema
Ejecuta uv run orkestra sync para generar la documentación
Incluye el registro en la composición de contexto del agente

Empieza con los hechos que causan más confusión o las restricciones que se violan con más frecuencia. Esos son tus ground truths de mayor valor.

Conclusión

Los agentes de IA van a alucinar. Es su naturaleza. Pero podemos crear entornos donde la alucinación esté acotada, donde ciertos hechos sean innegociables, donde los agentes puedan contrastar sus suposiciones con una realidad verificada.

Los ground truths no son una solución completa. Requieren mantenimiento. Pueden quedar desactualizados. Agregan sobrecarga al proceso de desarrollo.

Pero aportan algo valioso: un vocabulario compartido de hechos en el que tanto humanos como agentes pueden confiar. En un mundo donde los agentes participan cada vez más en el desarrollo de software, esa base compartida se vuelve esencial.

La alternativa son ciclos interminables de agentes cometiendo errores con total confianza y humanos corrigiéndolos. Los ground truths rompen ese ciclo al hacer que las correcciones sean explícitas y duraderas.

Tus agentes merecen saber qué es verdad. Díselo.

Orkestra: orquestando agentes de IA a gran escala

Tue, 06 Jan 2026 00:00:00 GMT

Las cifras de esta publicación reflejan el sistema al momento de su publicación (enero de 2026). Consulta nuestra página del equipo para ver las cifras actuales.

Cuando empezamos a construir con Claude Code, nos topamos con un problema que todo equipo que usa asistentes de codificación con IA termina enfrentando: un solo agente no puede hacer todo bien.

Puedes indicarle a un agente que sea un especialista en bases de datos. O un auditor de seguridad. O un ingeniero de frontend. Pero en el momento en que le pides ser los tres a la vez, la calidad sufre. El contexto se diluye. Las instrucciones entran en conflicto. El agente se convierte en un generalista que es mediocre en todo.

Así que construimos Orkestra.

¿Qué es Orkestra?

Orkestra es un sistema de orquestación de agentes para Claude Code y herramientas de codificación con IA similares. Coordina múltiples agentes especializados, cada uno con experticia distinta, bajo un único orquestador que enruta el trabajo hacia el especialista correcto.

Piénsalo como una agencia de personal para agentes de IA. El orquestador recibe una tarea, identifica qué especialista debería encargarse de ella, y delega con el contexto correcto. Cuando el trabajo está terminado, los resultados vuelven al orquestador para su síntesis.

Los números cuentan la historia:

Componente	Cantidad
Agentes especialistas	46
Skills reutilizables	466
Arquetipos de identidad	27
Mentalidades	11
Estilos de comunicación	10
Dominios de conocimiento	21

El sistema de personajes: D&D para agentes

La idea central detrás de Orkestra es que el comportamiento de un agente emerge de tres primitivas componibles:

Identidad define qué es el agente. Un arquitecto diseña estructuras de sistemas. Un depurador rastrea fallos hasta sus causas raíz. Un guardián vela por el cumplimiento normativo y los límites de seguridad. Tenemos 27 arquetipos de identidad que se pueden combinar.

Mentalidad define cómo piensa el agente. Una mentalidad analítica fundamenta las afirmaciones en evidencia y cuantifica la incertidumbre. Una mentalidad escéptica cuestiona los supuestos y busca evidencia que los desmienta. Una mentalidad exploratoria abraza la ambigüedad y prueba múltiples enfoques.

Estilo define cómo se comunica el agente. Un estilo técnico incluye valores exactos y hace referencia a archivos específicos. Un estilo conciso elimina el relleno y va directo a la respuesta. Un estilo diplomático equilibra la honestidad con el tacto.

Un agente combina estas primitivas:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Esta composición crea un agente que diseña sistemas (architect), conecta conocimiento entre dominios (knowledge-architect), fija la dirección estratégica (strategist), piensa en evidencia y datos (analytical), y se comunica sin relleno (concise).

El poder está en la explosión combinatoria. 27 identidades por 11 mentalidades por 10 estilos arrojan casi 3,000 personalidades de agente posibles. Pero solo defines las combinaciones que importan para tu trabajo.

Skills: módulos de capacidades reutilizables

Las skills son el conocimiento y los flujos de trabajo que los agentes pueden invocar. Siguen un sistema por niveles basado en el alcance:

Nivel	Nombre	Alcance	Ejemplo
K0	Fundamentos	Metodología universal	Disciplina test-first, finalización basada en evidencia
K1	Identidades	Flujos basados en rol	Estándares de interfaz CLI, guía de rendimiento
K2	Dominios	Conocimiento específico de dominio	Patrones de migración de bases de datos, validación de autenticación
K3	Stacks	Específico de tecnología	Despliegue en Cloudflare, operaciones de Supabase
K4	Proyecto	Solo esta base de código	Flujos y convenciones específicos del proyecto

Las skills se cargan bajo demanda (lazy-loaded). Un agente ve los nombres y descripciones de las skills al iniciar, pero el contenido completo de una skill solo se carga cuando se activa. Esto mantiene el contexto ligero mientras hace que cientos de skills sean descubribles.

Cada skill incluye:

Condiciones de activación claras («Usar al migrar esquemas de bases de datos»)
Guía paso a paso
Herramientas permitidas para el flujo de trabajo
Criterios de éxito y rutas de recuperación ante fallos

Las 466 skills de nuestro registro cubren de todo, desde el aislamiento de worktrees de Git hasta flujos de investigación web y validación de salud de despliegues.

Por qué importa la orquestación

Las arquitecturas de un solo agente chocan con paredes rápidamente:

Dilución de contexto. Una ventana de contexto de 200k tokens suena grande hasta que cargas esquemas de bases de datos, documentación de API, fixtures de pruebas y conocimiento de dominio. Los especialistas pueden trabajar con contexto acotado.

Conflictos de instrucciones. Decirle a un agente que sea «minucioso pero rápido» y que «verifique todo pero sin sobrediseñar» crea tensión. Los especialistas resuelven esto teniendo un alcance claro.

Profundidad de experticia. Un agente generalista sabe un poco de todo. Un agente especialista, compuesto con la identidad y las skills correctas, conoce su dominio a fondo.

Orkestra implementa una orquestación plana: un orquestador coordina múltiples especialistas. Los especialistas no pueden generar subespecialistas. Esto evita una explosión de complejidad mientras habilita el trabajo en paralelo.

El orquestador tiene acceso a 2.2 millones de tokens de capacidad efectiva: su propia ventana de 200k más 10 subagentes concurrentes con 200k cada uno. Trabajo que agotaría a un solo agente corre cómodamente a través de la flota.

El pipeline de renderizado

Las definiciones de agentes viven en YAML. Claude Code lee Markdown. Orkestra tiende un puente sobre esa brecha con un pipeline de renderizado determinista:

YAML Registries → Jinja Templates → .claude/agents/*.md

Los operadores editan la fuente YAML. Ejecutan orkestra sync. El Markdown renderizado aparece en .claude/agents/. Claude Code recoge los cambios.

Esta separación sirve a audiencias distintas:

La fuente YAML incluye metadatos de ciclo de vida, etiquetas, reglas de validación y notas de desuso para las herramientas
El Markdown renderizado incluye solo lo que el modelo necesita: descripción, herramientas, skills y guía de comportamiento

El pipeline compone identidades, mentalidades, estilos y skills en un solo prompt coherente. Un agente architect-analytical-concise recibe un system prompt muy distinto al de un agente debugger-skeptical-technical, incluso si comparten algunas skills subyacentes.

Conocimiento de dominio: el patrón de cuatro archivos

Cada dominio de conocimiento sigue una estructura consistente:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Esta estructura sirve para la carga de contexto de los agentes. Un agente que trabaja en autenticación carga authentication/patterns.md para orientarse y authentication/anti-patterns.md para evitar errores conocidos. Los archivos tienen un tamaño pensado para una carga de contexto eficiente: lo bastante enfocados para ser útiles, lo bastante completos para ser autoritativos.

Mantenemos 21 dominios de nivel superior que incluyen analítica, autenticación, ciencia de datos, infraestructura, machine learning, rendimiento, seguridad y más. Cada dominio puede tener subdominios para una granularidad más fina.

Valores: el sistema operativo

Todos los agentes comparten una capa base de valores que define cómo operan:

La simplicidad primero. Usa la solución más simple que funcione. Agrega complejidad solo cuando esté justificada.

Corrige las causas raíz. Nunca te limites a poner parches sin resolver la causa del fallo. Si un pipeline falla, depura el pipeline. Si una prueba falla, corrige el código o la prueba.

Basado en evidencia. Etiqueta las afirmaciones como «verificadas» (con benchmarks) o «estimadas» (con supuestos). Un patrón detectado no equivale a un problema confirmado.

Economía de contexto. Las herramientas MCP cuestan 0.1% del contexto. Las lecturas de archivos cuestan 2% cada una. Aplica experticia de dominio antes de explorar el código.

Estos valores se propagan a cada especialista a través del pipeline de renderizado. Un agente no puede eludirlos mediante composición.

CLI: el plano de control

Orkestra viene con una CLI para gestionar el ecosistema de agentes:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

La CLI es la fuente de verdad sobre qué agentes existen, qué skills tienen, y si el sistema está sano. Ejecuta la validación antes de la sincronización para detectar problemas temprano.

Consideraciones sobre código abierto

Construimos Orkestra para resolver nuestro propio problema: coordinar agentes de IA a gran escala para una base de código compleja. Los patrones que descubrimos no son específicos de nuestro dominio.

El sistema de composición de personajes (identidad + mentalidad + estilo) aplica a cualquier equipo que defina personalidades de agentes.

El sistema de niveles de skills (K0-K4) ofrece un modelo mental para organizar capacidades reutilizables por alcance.

El patrón del pipeline de renderizado (fuente YAML + plantillas + artefactos generados) separa las responsabilidades entre las herramientas y el consumo del modelo.

El modelo de orquestación plana (un coordinador, muchos especialistas) evita la complejidad mientras habilita el paralelismo.

Si Orkestra se vuelve código abierto depende de si estos patrones tienen valor para otros que construyen con Claude Code. Si estás chocando con las paredes que describimos, la arquitectura podría ayudar.

Lo que aprendimos

Construir Orkestra nos enseñó que la orquestación no se trata de hacer a los agentes más inteligentes. Se trata de hacerlos más enfocados.

Un solo agente con instrucciones perfectas de todas formas se queda sin contexto. Un solo agente con todas las skills de todas formas se confunde sobre cuáles aplicar. Un solo agente que intenta ser todo produce resultados mediocres en todas partes.

Cuarenta especialistas, cada uno excelente en su dominio, coordinados por un orquestador que sabe cuándo delegar: así es como lanzamos.

Los números importan menos que la arquitectura. Podrías necesitar cinco agentes o cincuenta. El principio se mantiene: composición sobre capacidad, especialización sobre generalización, coordinación sobre heroísmos individuales.

Orkestra impulsa el ecosistema de agentes detrás de Maguyva, nuestra plataforma de inteligencia de código. ¿Quieres saber más? Contacta al equipo.