Una sola base de conocimiento para todos los agentes de IA

Cuando empecé a usar Claude Code en serio, hice lo que hace todo el mundo: creé un CLAUDE.md en cada repo con convenciones del proyecto, notas de stack, y trucos aprendidos. Funcionaba, en su mayor parte. Pero algo seguía siendo frustrante.

En cada sesión nueva, el agente redescubría las mismas cosas. MusicKit no funciona en el simulador, otra vez. CloudKit exige propiedades opcionales en cada @Model, otra vez. El vault de Ansible es un solo blob cifrado que git no puede fusionar, otra vez. Escribía los mismos comentarios en mi tracker de tickets una y otra vez, o dependía de que el agente recordara cosas que no podía.

El problema es que CLAUDE.md es la herramienta equivocada para esto. Es excelente para convenciones estables del proyecto: decisiones de arquitectura, estructura de directorios, comandos de build. Es malo para acumular el conocimiento desordenado que se gana durante el trabajo real: comportamiento de límites de tasa observado, una estrategia de caché que funcionó, un truco que costó dos horas de investigación.

Ese conocimiento necesita vivir en algún lugar donde un agente pueda encontrarlo en la próxima sesión, sin tener que meterlo todo en el archivo que se supone es un documento de convenciones.

El patrón: un repositorio, muchos proyectos

Configuré un único repositorio de Obsidian respaldado por git en ~/Repos/vdaluz-kb/. Todos los proyectos apuntan a él. Las notas usan frontmatter YAML con un campo projects: para registrar la procedencia:

---
date: 2026-06-06
type: source
source: MusicKit / Apple Music catalog
tags: [musickit, apple-music, ios, swift]
projects: [deep-cut-atlas]
---

El campo projects: es procedencia, no un filtro de alcance. Un agente en cualquier repo puede hacer grep -ri "musickit" y encontrar la nota, sin importar qué proyecto la escribió originalmente. Los patrones transversales (comportamiento de fusión del vault de Ansible, rotación de llaves SSH) también viven ahí, etiquetados con todos los proyectos afectados.

La estructura es simple:

vdaluz-kb/
  patterns/       # recurring patterns and data source quirks
  infrastructure/ # service gotchas, runbooks, host-specific notes
  alerts/         # daily alert review findings

No hay directorios por proyecto. La procedencia vive en el frontmatter, no en el árbol de carpetas.

Conectar un proyecto

Cada CLAUDE.md de proyecto recibe una sección corta de KB:

## Knowledge base
Durable findings live in the central KB at ~/Repos/vdaluz-kb/.

- Before implementing anything: grep -ri "<topic>" ~/Repos/vdaluz-kb/
- Saving new findings: write to ~/Repos/vdaluz-kb/patterns/<slug>.md
  with frontmatter projects: [this-project], then commit and push
- Issue-scoped notes: go in the issue tracker, not the KB

Esa es toda la integración. El agente sabe que debe revisar antes de implementar, y sabe dónde guardar cuando aprende algo que vale la pena conservar.

Qué va en el KB, en el tracker y en CLAUDE.md

Me llevó un tiempo llegar a la regla correcta. La que terminé usando: CLAUDE.md contiene convenciones estables (arquitectura, stack, comandos de build, restricciones críticas) y cambia poco. El KB contiene conocimiento duradero pero descubierto en el camino, trucos, comportamiento de límites de tasa, modos de falla conocidos, patrones que se repiten entre tickets, y cambia cuando aparece algo nuevo que aprender. El issue tracker contiene notas acotadas a cada ticket, decisiones, pasos de investigación, evidencia de un trabajo específico, y es efímero por diseño.

Una buena prueba: “¿Alguien que toque esto dentro de seis meses necesitaría saberlo?” Si la respuesta es sí, va al KB. Si solo es relevante para el trabajo en curso en este momento, se queda en el ticket.

La trampa de la fragmentación

El ticket que originó todo esto pedía originalmente construir un repositorio de Obsidian por repo dentro del proyecto de iOS de Deep Cut Atlas, replicando lo hecho para el homelab. Pero para cuando llegué a eso, el repositorio por proyecto del homelab ya se había consolidado en el KB central. Construir un segundo repositorio por repo habría vuelto a fragmentar justo lo que se acababa de unificar.

La solución correcta fue conectar Deep Cut Atlas al KB existente y poblarlo con lo que ya se sabía de spikes anteriores. Dos archivos, dos commits, listo.

La lección: cuando hay varios proyectos activos a la vez, los repositorios de conocimiento por repo son una carga de mantenimiento. Un solo repositorio alcanza. La procedencia por frontmatter le gana a la estructura de carpetas siempre.