Por qué no necesitas un «segundo cerebro» en 3D (y cómo estructurar documentación que entiendan tanto humanos como agentes de IA)
MarQ · 2026-11-18
Si pasas tiempo en redes técnicas, seguro que te has cruzado con esas capturas espectaculares de grafos de conocimiento: miles de nodos brillantes flotando en el espacio, nebulosas de enlaces cruzados y paneles laterales repletos de métricas.
Quedan muy bien en pantalla. El problema empieza cuando intentas trabajar con ellas a diario.
A partir de 200 o 300 documentos, un grafo global deja de ser un mapa y se convierte en una bola de pelo ilegible. Nadie navega haciendo zoom sobre una galaxia de puntos para encontrar una decisión de arquitectura tomada hace cuatro meses. En la práctica, muchos sistemas de «segundo cerebro» acaban convirtiéndose en una forma sofisticada de procrastinar: inviertes más horas manteniendo plugins, etiquetas y nodos huérfanos que escribiendo código o resolviendo problemas reales.
Pero hoy hay una razón todavía más importante para huir de esa complejidad accidental: tus documentos ya no los lees solo tú; los leen agentes de IA.
El coste oculto de la sobreingeniería en tus notas
Cuando una base de conocimiento crece alrededor de extensiones propietarias y vistas visuales, aparecen tres cuellos de botella inmediatos:
- Contaminación de la ventana de contexto: Llenar los archivos de sintaxis no estándar, bloques de consulta dinámicos y metadatos internos de plugins añade ruido puro cuando un modelo de lenguaje intenta leer el repositorio. Más tokens basura significan peor recuperación y más margen de error.
- Enlaces rotos silenciosos: En cuanto renombras o mueves archivos desde la terminal o fuera de la aplicación principal, las referencias internas se rompen sin que nadie lo note hasta que intentas seguirlas.
- Mezclar conocimiento con estado operativo: El error más habitual al usar herramientas de notas para ingeniería es intentar convertirlas en un gestor de proyectos a base de plugins de Kanban y listas de tareas diarias. El historial de Git se ensucia con cambios efímeros y la documentación pierde su función principal.
Una arquitectura determinista en tres capas
En lugar de delegar la estructura a una interfaz pesada, funciona mucho mejor aplicar los mismos principios que usamos para diseñar software: texto plano, contratos verificables y separación de responsabilidades.
1. CommonMark puro + archivos INDEX.md
Todo el conocimiento técnico vive en archivos .md estándar dentro de un repositorio Git. Sin formatos propietarios y con garantía de que dentro de diez años cualquier editor o script podrá leerlos.
Para evitar tanto las jerarquías de carpetas interminables como el caos de archivos sueltos, cada dominio mantiene un archivo INDEX.md que actúa como punto de entrada explícito:
docs/
├── INDEX.md
├── arquitectura/
│ ├── INDEX.md
│ ├── modelo-datos.md
│ └── autenticacion.md
└── proyectos/
├── INDEX.md
└── integracion-mcp.md
Este patrón resuelve dos formas de navegación a la vez:
- Top-down (estructurada): Tanto un desarrollador nuevo como un agente de IA leen primero
INDEX.mdpara obtener el mapa exacto del sistema sin tener que ingerir todo el directorio. - Bottom-up (búsqueda directa): Cuando buscas un símbolo, decisión o término concreto,
ripgrep(rg) recorre cientos de archivos en milisegundos sin necesidad de indexadores en segundo plano.
2. Enlaces bidireccionales auditados con lychee
Renunciar a los grafos visuales no significa renunciar a conectar ideas entre documentos. Los enlaces cruzados en Markdown estándar ([modelo de datos](../arquitectura/modelo-datos.md#esquema)) siguen siendo la forma más limpia de relacionar contexto.
La diferencia está en tratarlos como código: si un enlace apunta a un archivo que ya no existe o a un encabezado que cambió de nombre, el repositorio debe avisarte. Integrar lychee en local (como pre-commit hook) o en CI permite auditar todo el árbol de documentación al instante:
$ lychee "**/*.md"
🔍 Analyzing 42 Markdown files...
📝 Checking 138 links and references...
✅ All 138 links are valid! (142ms)
No broken links found.
En poco más de cien milisegundos tienes integridad referencial determinista, sin depender de que una aplicación gráfica mantenga un índice interno sincronizado.
3. Separar el conocimiento estático del estado vivo (MCP)
La pieza que termina de limpiar el flujo es sacar las tareas, los estados de avance y la coordinación entre agentes fuera de los archivos Markdown.
- Lo estático va a Git (
.md): Decisiones de arquitectura, especificaciones, guías de despliegue y documentación técnica consolidada. - Lo efímero va a una capa operativa dedicada: Qué tarea está en curso, qué agente está ejecutando qué bloque de trabajo y cuál es el estado actual del sprint.
Con MarQ (marqpm.com), esta separación se conecta directamente mediante MCP (Model Context Protocol): los agentes consultan la documentación limpia en local para entender cómo funciona el sistema y utilizan MarQ para coordinar qué hay que hacer y en qué estado se encuentra cada tarea, sin ensuciar los .md con estado transitorio.
Menos decoración, más durabilidad
Un buen sistema de documentación no se mide por lo espectacular que se ve en una captura de pantalla, sino por su fricción diaria: cuánto tarda en responder una búsqueda, qué ocurre cuando mueves un archivo de sitio y con qué facilidad puede consumirlo un agente sin perder el hilo.
Al final, volver al texto plano con índices explícitos y validación automática no es dar un paso atrás; es quitar capas innecesarias entre tus ideas y el trabajo real.