qmd: Búsqueda de documentos de rebajas locales para agentes de IA

Fri, 01 May 2026 03:12:57 +0800

qmd es una herramienta de búsqueda de documentos Markdown locales, con los agentes AI como sus principales usuarios objetivo.

Resuelve un problema específico: cuando un proyecto contiene muchos documentos .md, los asistentes de codificación de IA a menudo no saben qué archivo leer, qué sección citar o qué instrucciones están actualizadas. grep de texto completo puede encontrar palabras clave, pero no comprende bien el significado. Poner toda la documentación en contexto desperdicia espacio en la ventana e introduce fácilmente contenido irrelevante.

La idea detrás de qmd es indexar primero los documentos de Markdown y luego devolver los fragmentos más relevantes a través de una interfaz de búsqueda para que los utilice la IA. Puede usarse como una herramienta de línea de comandos, integrarse a través de un SDK o exponerse como un servidor MCP para clientes que admiten MCP.

¿Qué problema resuelve?

Los proyectos reales suelen tener más de uno o dos archivos README.

Es posible que tengas:

Notas de arquitectura
Documentación API
Convenciones de desarrollo
Procedimientos de implementación
Registros de decisiones de arquitectura.
Notas de solución de problemas
Documentos de requisitos
Instrucciones de uso de IA
Notas y recordatorios de la cadena de herramientas.

Los humanos pueden buscar documentos a través de directorios, pero los agentes de IA necesitan un punto de entrada de recuperación claro. En caso contrario, podrán:

Leer el documento equivocado
Falta de restricciones clave
Utilice instrucciones obsoletas
Poner el contenido irrelevante en contexto.
Inventar reglas en respuestas basadas en la experiencia.

Aquí es donde “qmd” resulta útil. Convierte los documentos locales de Markdown en una fuente de conocimiento con capacidad de búsqueda, de modo que la IA puede buscar primero cuando necesita contexto y luego responder o actuar en función de fragmentos coincidentes.

Enfoque de búsqueda

El archivo README dice que “qmd” combina varios métodos de recuperación:

Búsqueda de palabras clave BM25
Búsqueda de vectores
Reclasificación de LLM

BM25 es bueno para palabras clave claras. Si busca el nombre de una función, una clave de configuración, un código de error o un nombre de archivo, suele ser directo y eficaz.

La búsqueda de vectores es mejor para cuestiones semánticas. Por ejemplo, si pregunta “¿cómo maneja este proyecto la validación de permisos?”, es posible que la documentación no contenga esa frase exacta, pero puede contener descripciones relacionadas sobre autenticación, control de acceso y comprobaciones de roles.

La reclasificación de LLM se utiliza para reordenar los resultados de los candidatos. Los dos primeros pasos encuentran contenido potencialmente relevante y luego el modelo juzga qué fragmentos coinciden mejor con la pregunta actual.

Esta combinación es más adecuada para los agentes de IA que la simple búsqueda de palabras clave, porque las preguntas de los agentes suelen ser intenciones de tareas en lugar de palabras clave fijas.

¿Por qué rebajas?

Markdown es el formato de documentación más común en proyectos de desarrollo.

Es lo suficientemente simple como para almacenarlo en Git y lo suficientemente estructurado como para incluir encabezados, listas, bloques de código, enlaces y tablas. Para la IA, Markdown también es más fácil de analizar que los archivos PDF, las instantáneas web o las capturas de pantalla.

Debido a que qmd se centra en Markdown, puede procesar la documentación del desarrollador de forma más directa:

Dividir el contenido por títulos y párrafos.
Preservar bloques de código
Preservar rutas de documentos
Devolver fragmentos adecuados para citar
Informar al Agente de qué documento proviene una respuesta.

Esto es más estable que pedirle a la IA que escanee aleatoriamente un repositorio y ahorra más contexto que poner todos los documentos en un mensaje a la vez.

Tres puntos de entrada

qmd proporciona tres puntos de entrada: CLI, SDK y servidor MCP.

1. CLI

La CLI es adecuada para uso directo de terminal y para scripts.

Puede indexar un directorio de documentación y luego buscar contenido relacionado con comandos. Para los desarrolladores, la CLI es la forma más sencilla de validar la herramienta: primero vea si puede encontrar los documentos correctos y luego considere integrarla en flujos de trabajo más complejos.

Este tipo de herramienta es útil dentro de proyectos locales. Por ejemplo, antes de cambiar el código puedes buscar documentos de diseño; antes de depurar, busque notas de solución de problemas; Antes de escribir una API, busque las convenciones de la API.

2. SDK

El SDK es adecuado para integrar qmd en sus propias herramientas.

Si está creando un asistente de desarrollo interno, un sistema de preguntas y respuestas sobre documentación, un robot de revisión de código o una base de conocimiento del proyecto, puede llamar a la capacidad de búsqueda a través del SDK en lugar de pedir a los usuarios que ejecuten comandos directamente.

El SDK brinda más control sobre:

Buscar directorios
Consultar contenido
Número de resultados devueltos
Formato de resultado
Si se deben pasar los resultados a un modelo para su resumen.

Esto se adapta a escenarios que necesitan una integración más profunda.

3. Servidor MCP

MCP es el punto de entrada más valioso para los agentes de IA.

A través del servidor MCP, los clientes que admiten MCP pueden llamar a qmd como herramienta de búsqueda de documentos. Esto permite a un agente buscar documentos de Markdown locales antes de actuar, en lugar de adivinar las reglas del proyecto.

Un flujo de trabajo típico podría ser:

El usuario le pide a la IA que modifique una función.
AI llama a “qmd” para buscar documentos de diseño relacionados
qmd devuelve los fragmentos de Markdown más relevantes
La IA modifica el código en función de esas restricciones de documentos.

Esto es más natural que pegar manualmente todas las reglas en una nueva sesión y se adapta mejor a proyectos a largo plazo.

Escenarios adecuados

qmd es adecuado para:

Proyectos con muchos documentos Markdown.
Agentes de IA que a menudo necesitan buscar reglas del proyecto.
Equipos que quieran respuestas de IA para citar documentos locales.
Documentación distribuida en varios directorios.
Reutilizar la misma capacidad de recuperación en CLI, SDK y MCP
Reducir la tendencia de los asistentes de codificación de IA a adivinar las convenciones del proyecto.
Conexión de bases de conocimientos locales a Claude Desktop, Claude Code u otros clientes MCP

Si su proyecto solo tiene un README corto, pedirle directamente a AI que lea el archivo es suficiente.

Pero si la documentación ha crecido hasta llegar a docenas o cientos de archivos, o si desea que el Agente busque documentos antes de actuar, este tipo de herramienta de indexación adquiere sentido.

Diferencia de grep

Herramientas como grep y rg son excelentes para una búsqueda exacta.

Si sabe que necesita DATABASE_URL, authMiddleware, 404 o docker compose, la búsqueda de palabras clave suele ser la más rápida.

qmd es mejor cuando no sabes las palabras exactas.

Por ejemplo, puedes preguntar:

¿Cuál es el proceso de lanzamiento de este proyecto?
¿Qué convenciones se aplican al agregar una nueva API?
¿Se documentó antes la estrategia de almacenamiento en caché?
¿Qué documentos debería leer la IA antes de cambiar el código?
¿Dónde está la base de diseño de un módulo?

Estas preguntas suelen requerir una recuperación semántica en lugar de hacer coincidir una palabra. La combinación BM25 + vector + reclasificación en qmd tiene como objetivo hacer que estas preguntas encuentren el contexto correcto más fácilmente.

Relación con RAG

qmd puede verse como un componente RAG liviano para documentos Markdown. No intenta crear un sistema completo de preguntas y respuestas para usted. Se centra en un paso: encontrar fragmentos de documentos relevantes. La forma en que se utilizan esos fragmentos posteriormente puede ser manejada por CLI, SDK, un cliente MCP o su propio flujo de trabajo del Agente.

Este posicionamiento es práctico. Muchos proyectos no necesitan un gran sistema de base de conocimientos; solo necesitan IA para buscar documentos locales con mayor precisión y rapidez, y luego devolver los resultados a la tarea actual.

Notas de uso

En primer lugar, la calidad de la documentación sigue siendo importante.

Una herramienta de recuperación sólo puede encontrar contenido existente. Si los documentos están desactualizados, duplicados o contradictorios, es posible que la IA aún reciba un contexto incorrecto. Antes de conectar qmd a un Agente, primero limpie los documentos clave.

En segundo lugar, no amplíe demasiado el alcance del índice.

Indexar cada archivo Markdown en el repositorio no siempre es mejor. La documentación de dependencia, las notas temporales y los borradores de soluciones antiguos pueden contaminar los resultados. Un mejor enfoque es definir qué directorios son fuentes de documentación confiables.

En tercer lugar, los resultados de la búsqueda deben preservar las fuentes.

Cuando la IA utiliza fragmentos de documentos, debe saber de qué archivo y sección provienen. Esto hace que la revisión humana sea rastreable y reduce el riesgo de que “esto parezca la conclusión de un documento, pero es sólo un resumen modelo”.

Cuarto, no reemplacen completamente el juicio humano.

qmd puede mejorar la calidad de la recuperación del contexto, pero no reemplaza la fuente de la verdad. Los cambios importantes aún requieren código actualizado, resultados de pruebas y los requisitos más recientes.

Equipos adecuados

Si su equipo ya ha comenzado a incluir agentes de IA en los flujos de trabajo de desarrollo diarios, herramientas como qmd pueden resultar valiosas.

Están especialmente indicados para equipos que:

Escribir mucha documentación.
Tener una larga historia de proyectos.
Necesita gente nueva e inteligencia artificial para comprender rápidamente el contexto.
Mantener registros de decisiones de arquitectura.
Tener muchos documentos de convención de Markdown.
Quiero que AI verifique las reglas antes de modificar el código.

Su objetivo no es hacer que la IA lo sepa todo. Es hacer que la IA adivine menos y busque más.

Referencia

-tobi/qmd

Pensamiento final

El valor de qmd es que convierte los documentos Markdown locales en un punto de entrada de búsqueda al que los agentes de IA pueden llamar de manera confiable.

Cuando la documentación del proyecto pasa de “instrucciones para humanos” a “una fuente de contexto que pueden buscar tanto humanos como IA”, los asistentes de codificación de IA pueden seguir las reglas del proyecto más fácilmente.

Markdown on KnightLi Blog