Markdown on KnightLi Blog

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.

Cómo elegir entre 8 formatos comunes de configuración: de INI, XML, JSON, YAML y TOML a Markdown

Wed, 22 Apr 2026 21:48:37 +0800

Si escribes código, administras servidores, ajustas opciones de juegos o mantienes toolchains, casi seguro no puedes evitar los archivos de configuración.

Muchas veces, lo que realmente rompe un programa no es el algoritmo ni el framework, sino una línea diminuta de configuración: un espacio faltante, una coma extra o un valor escrito de una forma que el sistema no esperaba. Mirar formatos comunes lado a lado nos devuelve a varias preguntas centrales:

¿Qué formatos son más amables para escribir por humanos?
¿Qué formatos son más amables para parsear por máquinas?
En la era de AI Agents, ¿empezará a cambiar el papel de los archivos de configuración?

Este artículo intenta organizar esa cuestión de forma concisa.

01 Un archivo de configuración es básicamente una negociación entre humanos y máquinas

Hay una forma de decirlo que me parece especialmente precisa: un archivo de configuración es un contrato de comportamiento entre humanos y programas.

Su valor es obvio. No necesitas reescribir lógica de negocio ni recompilar nada. Cambiando unas pocas líneas de texto puedes alterar el comportamiento de un sitio, la lógica de una aplicación, el despliegue o incluso gráficos y opciones ocultas de un juego.

El problema es que este contrato contiene una tensión incorporada.

Desde el lado humano queremos:

algo legible, escribible y estructuralmente claro
preferiblemente con comentarios para entenderlo después
la menor repetición posible, idealmente con reutilización y modularidad
un formato que no explote de inmediato por un pequeño error

Pero desde el lado máquina, la elegancia es irrelevante. Le importan principalmente dos cosas:

el parsing debe ser rápido
las reglas deben ser estrictas, los tipos claros y la ambigüedad mínima

Por eso los formatos de configuración siempre se tensan entre lo human-friendly y lo machine-friendly. Cuanto mejor es un formato para lectura humana, más trabajo suele necesitar la máquina para parsearlo. Cuanto más eficiente es para máquinas, más fácil suele ser que humanos cometan errores al editarlo.

02 INI: simple y directo, pero limitado

Empecemos con INI.

Sus fortalezas son muy directas:

estructura simple
secciones más pares clave-valor fáciles de entender
soporte de comentarios
adecuado para configuración ligera, como ajustes de juegos o entorno básico

Si alguna vez modificaste ajustes de juegos antiguos o parámetros de herramientas a mano, probablemente lo viste.

Pero INI también tiene limitaciones obvias. Su estructura es demasiado plana y no representa naturalmente anidamiento profundo o arrays. Además, normalmente carece de un sistema de tipos estricto, así que muchos valores son básicamente strings y el programa decide cómo interpretarlos.

Eso hace que INI se sienta como una herramienta vieja pero cómoda: excelente para trabajo ligero, fácil de superar cuando el proyecto crece.

Un INI típico:

[server]
host=127.0.0.1
port=8080

[feature]
enable_cache=true

03 XML: riguroso y estable, pero cansado de escribir

El segundo formato importante es XML.

Si mantuviste proyectos Java antiguos o viste archivos enormes llenos de tags de cierre, te resultará familiar.

Sus fortalezas incluyen:

estructura jerárquica clara
soporte de comentarios
reglas estrictas
validación fuerte cuando se combina con un schema

Eso permite a las máquinas conocer tipos, cardinalidad y restricciones estructurales antes de parsear de verdad, dando mucha seguridad.

Pero su coste humano es igual de clásico:

tags verbosos
mucho ruido visual
archivos que crecen rápido
un cierre faltante puede romperlo todo

Por eso XML se siente como un contrato formal sellado. A las máquinas les gusta; los humanos se cansan de mantenerlo. Muchos proyectos nuevos ya no lo eligen primero, pero en sistemas antiguos y entornos con reglas estrictas no ha desaparecido.

La misma configuración en XML:

<config>
  <server>
    <host>127.0.0.1</host>
    <port>8080</port>
  </server>
  <feature>
    <enable_cache>true</enable_cache>
  </feature>
</config>

04 JSON: dominante para intercambio de datos, incómodo para configuración editada a mano

En desarrollo moderno, JSON es casi inevitable.

El juicio clásico es: excelente como formato de intercambio de datos, algo incómodo como configuración mantenida por humanos.

Sus ventajas:

estructuras claras de objetos y arrays
transmisión amigable para red
parsers maduros
encaje fuerte con APIs web y comunicación frontend-backend

Frente a XML, JSON se ve mucho más ligero. La misma estructura suele ser más corta y más fácil de enviar por red.

Pero tiene un defecto grande: JSON estándar no soporta comentarios.

Su sintaxis también es estricta:

las claves deben ir entre comillas dobles
el último elemento no puede tener coma final
un símbolo faltante rompe todo de inmediato

Así que JSON es excelente para APIs e intercambio entre servicios, pero no siempre ideal para configuración que humanos editan, explican y revisan a menudo.

Por ejemplo:

{
  "server": {
    "host": "127.0.0.1",
    "port": 8080
  },
  "feature": {
    "enable_cache": true
  }
}

05 YAML: muy legible, pero la indentación y los tipos implícitos pueden traicionarte

Si trabajaste con Docker, CI/CD, Kubernetes o automatización de despliegues, casi seguro trataste con YAML.

Su mayor atractivo es lo limpio que se ve:

menos llaves y comillas
la indentación expresa jerarquía
soporta comentarios
anchors para reutilización

Desde una primera mirada humana, YAML suele parecer más amable que JSON.

Pero el problema está justo ahí. Oculta mucha complejidad y en uso real produce dos fallos clásicos:

infierno de indentación
conversión implícita de tipos

Los problemas de indentación son fáciles de entender: un espacio extra o faltante puede romper la config. Peor aún, la conversión implícita hace que valores que parecen strings simples puedan interpretarse automáticamente como booleanos u otros tipos.

Por eso tanta gente elogia lo bien que se ve YAML y al mismo tiempo sufre con él. Es realmente bueno para lectura humana, pero las máquinas no lo parsean sin esfuerzo, e incluso distintas librerías pueden discrepar en detalles sutiles.

La misma configuración en YAML:

server:
  host: 127.0.0.1
  port: 8080

feature:
  enable_cache: true

06 TOML: equilibrio entre legibilidad y determinismo

TOML suele presentarse como una respuesta moderna equilibrada.

Su atractivo combina parte de la claridad de INI con parte de la claridad de tipos de JSON:

soporte de comentarios
estructura clara
tipado más fuerte y explícito
manejo más natural de tipos comunes como fecha y hora
muchas menos trampas de conversión implícita que YAML

También se ha vuelto cada vez más común en toolchains modernas, como pyproject.toml en Python.

No es perfecto. En estructuras profundamente anidadas, TOML puede volverse verboso, y la escritura por rutas puede sentirse repetitiva. Pero para config de proyectos pequeños y medianos, herramientas y package management, la experiencia suele ser muy estable.

Si quieres un formato con comentarios, significado claro y bajo dolor de parser, TOML es un candidato fuerte.

Ejemplo común:

[server]
host = "127.0.0.1"
port = 8080

[feature]
enable_cache = true

07 `.conf` y configuración Apache: no es un formato universal, sino un lenguaje de dominio

Vale la pena enfatizar que mucha gente ve .conf y asume que es un formato estándar único. No lo es.

.conf es solo un sufijo de archivo para “configuration”. El contenido depende por completo de las reglas del sistema concreto. Es más una categoría amplia que una sintaxis estándar.

Toma Apache como ejemplo. Su estilo es representativo:

parte parece una lista de directivas de una línea
parte parece bloques etiquetados con comportamiento acotado
encaja naturalmente en el dominio de servidores web

Sus fortalezas son prácticas para operaciones, especialmente al expresar permisos, routing y virtual hosts. La desventaja es que sirve a su propio ecosistema y no tiene mucha portabilidad general.

Eso lo acerca a un lenguaje específico de dominio: excelente dentro del sistema para el que fue diseñado, no algo que tratar como formato universal.

Ejemplo mínimo estilo Apache:

Listen 80

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/var/www/html"
</VirtualHost>

08 Protocol Buffers: tipado industrial, pero mayor barrera

Protocol Buffers ya no son realmente “solo escribir una config a mano”. Se parecen más a un sistema formal de definición y serialización de datos.

Sus fortalezas son importantes:

tipado fuerte
schema explícito
buena compatibilidad hacia adelante y atrás
transmisión binaria compacta
procesamiento eficiente por máquinas

Pero los costes también son claros:

hay que definir archivos .proto
se necesitan herramientas y paso de compilación
la barrera es relativamente alta para proyectos pequeños

Así que no son ideales si solo quieres configurar una herramienta pequeña. Pero si construyes sistemas grandes, servicios RPC, sistemas distribuidos o protocolos de datos de larga vida, suelen ser mucho más fiables que formatos ligeros.

Su estilo se acerca a “define primero la estructura y luego genera código”:

syntax = "proto3";

message ServerConfig {
  string host = 1;
  int32 port = 2;
  bool enable_cache = 3;
}

09 En la era de AI Agents, Markdown puede volver a ser formato de configuración

La parte más interesante es poner Markdown dentro de la categoría de “formatos de configuración”.

Desde una perspectiva tradicional, suena extraño, porque Markdown parece más bien documentación. Pero si el objetivo ya no es un parser rígido sino un LLM o AI Agent, el argumento tiene sentido.

¿Por qué?

Porque los programas tradicionales dependen de sintaxis estricta y campos fijos, mientras los modelos grandes entienden mejor significado, estructura y contexto. Para ellos:

los encabezados son jerarquía
las listas son pasos
el texto en negrita es énfasis
el lenguaje natural puede portar reglas

Cuando el objetivo de configuración cambia de “parser rígido” a “agente que entiende significado”, Markdown, como texto estructurado amigable para humanos, puede volverse una configuración más natural.

Esto lleva a un juicio importante: en la era tradicional del software, muchos formatos existían para hacer que humanos se adaptaran a máquinas; en la era AI, las máquinas empiezan a adaptarse a la expresión humana.

Por ejemplo, una configuración de tarea para un agente podría ser:

# Goal

Write a welcome email for a new user.

## Requirements

- Friendly tone
- No more than 150 words
- Mention the product's 3 core features

## Forbidden

- Do not promise features that do not exist
- Do not use exaggerated marketing language

10 Entonces, ¿cómo elegir?

Si comprimimos toda la discusión:

si quieres configuración extremadamente simple, ligera y plana: INI
si quieres estructura fuerte, validación fuerte y compatibilidad legacy: XML
si quieres transmisión de red e intercambio de interfaces: JSON
si quieres alta legibilidad más cloud-native y config de despliegue: YAML
si quieres una experiencia moderna generalista más estable: TOML
si quieres reglas internas específicas de dominio: .conf / DSLs estilo Apache
si quieres diseño industrial de protocolos y evolución a largo plazo: Protocol Buffers
si quieres expresión natural y orquestación de tareas para AI Agents: Markdown

No hay un único mejor formato. Depende de para quién escribes:

humanos que mantienen el sistema
máquinas que parsean a alta velocidad
servicios que se comunican entre sí
o AI Agents que necesitan entender y ejecutar

Conclusión breve

La historia de los archivos de configuración es, en el fondo, la historia de humanos y máquinas renegociando constantemente dónde debe caer el coste de entender.

Antes, los humanos tenían que adaptarse a las máquinas, así que memorizábamos llaves, reglas de indentación, comillas y sintaxis rígida. Ahora que los modelos de lenguaje y sistemas de agentes entienden cada vez mejor la expresión natural, la propia “configuración” empieza a cambiar.

Quizá en el futuro muchos escenarios de configuración ya no giren alrededor de una sintaxis fija, sino de declaraciones estructuradas de intención. Hasta entonces, formatos como JSON, YAML, TOML, INI y XML seguirán coexistiendo, cada uno en el rol que mejor le encaja.