La Biblioteca: el grafo de conocimiento de CreaRack-Pro
Parte de la colección [[concept—workspace—supercontexto-00-vision]]. Cubre: qué es el grafo, cómo consultarlo, el flujo obligatorio antes de cada commit, y el panel Pulse.
¿Qué es exactamente el grafo?
Imagina un mapa donde cada “lugar” es un trozo de código (una función, un modelo de base de datos, un endpoint de la API) y las “carreteras” entre ellos representan relaciones: “esta función llama a aquella”, “este modelo tiene este campo”, “este endpoint usa este schema”, “este endpoint está documentado en esta wiki”.
Ese mapa es la Biblioteca. Vive en una base de datos en Cloudflare (D1) y tiene herramientas (bib_*) para consultarlo desde Claude Code en tiempo real.
Estado actual del grafo (abril 2026)
| Métrica | Valor |
|---|---|
| Nodos totales | 3.090 |
| Edges (relaciones) | 4.450 |
| Comunidades detectadas | 255 |
| Cohesión de módulos | 78% |
| Ciclos | 0 |
| God nodes | 0 |
| Dead code | 0 |
| Salud Biblioteca | 100% |
¿Para qué sirve en el día a día?
Antes de que Claude Code modifique cualquier archivo, consulta la Biblioteca. Esto evita tres problemas clásicos:
- Duplicar código que ya existe en otro módulo
- Romper dependencias que no eran obvias a simple vista
- Dejar docs desactualizados porque nadie sabía que estaban vinculados
flowchart LR
A["Edu pide\nuna nueva feature"] --> B["Claude consulta\nbib_ask · bib_context_query"]
B --> C["Biblioteca devuelve:\n• qué modelos existen\n• qué endpoints hay\n• qué docs se verán afectadas"]
C --> D["Claude edita código\n(sin duplicar, sin romper)"]
D --> E["bib_report_change\nantes del commit"]
E --> F["Grafo actualizado\npara el próximo dev"]
Las herramientas disponibles (bib_*)
Claude Code tiene acceso a estas herramientas para consultar la Biblioteca:
Consulta de contexto (usar ANTES de editar)
| Herramienta | Para qué sirve | Ejemplo de uso |
|---|---|---|
bib_ask | Pregunta en lenguaje natural, respuesta sintetizada con fuentes | “¿Cómo funciona el sistema de permisos de organizaciones?” |
bib_search_semantic | Búsqueda vectorial: devuelve chunks rankeados por relevancia | “rack device add endpoint” |
bib_context_query | Briefing completo de un módulo: modelos, endpoints, docs | topic=“monitoring” |
bib_app_summary | Resumen ejecutivo de una app Django | app=“blueprints” |
bib_get_node | Detalle de un nodo concreto con todas sus relaciones | node_id=“models.py::Device” |
Impacto y reporte (usar ANTES de commitear)
| Herramienta | Para qué sirve |
|---|---|
bib_impact_query | Qué docs y nodos se verán afectados por un cambio en un archivo |
bib_report_change | Obligatorio — marca los docs vinculados para revisión posterior |
Análisis avanzado
| Herramienta | Para qué sirve |
|---|---|
bib_call_graph | Traza quién llama a qué función (callers y callees) |
bib_doc_coverage | Qué código tiene/no tiene documentación vinculada |
bib_stale_report | Qué nodos llevan más de N días sin actualizarse |
bib_stats | Estado general del grafo (nodos, edges, comunidades, salud) |
bib_god_nodes | Detecta nodos con demasiadas dependencias (code smell) |
bib_dead_code | Código que ya no se usa |
bib_cycle_report | Dependencias circulares entre módulos |
bib_coupling_report | Acoplamiento entre comunidades del grafo |
bib_compute_communities | Recalcula los clusters del grafo (Label Propagation) |
El flujo obligatorio en cada commit (Regla 0)
Hay tres pasos que Claude Code debe seguir cuando toca código. No son opcionales:
sequenceDiagram
participant C as Claude Code
participant B as Biblioteca MCP
participant Git as git commit
Note over C,B: ANTES de editar cualquier archivo
C->>B: bib_context_query(topic="monitoring")
B-->>C: Modelos · endpoints · docs del módulo
Note over C,B: DESPUÉS de editar, ANTES de commitear
C->>B: bib_impact_query(file_path="monitoring/views.py")
B-->>C: "Estas 3 docs quedarán desactualizadas"
C->>B: bib_report_change(file_path="monitoring/views.py", change_type="modified")
B-->>C: ✅ Marcado para revisión
Note over C,Git: AHORA sí
C->>Git: git commit -m "feat: ..."
Git-->>C: ✅ Pre-commit hook no bloqueó
¿Qué pasa si me salto el bib_report_change?
El pre-commit hook claude-method/harness/bib_report_check.py (fuente única: el hook de cada repo lo ejecuta desde ahí) bloquea el commit. Si el MCP está caído o sin token, degrada con warning y deja pasar (no rompe el flujo productivo).
Para saltarlo puntualmente: BIB_SKIP=1 git commit. Queda registrado en el Pulse y se puede auditar.
Cómo está organizado el grafo: nodos y edges
Tipos de nodos
| Tipo | Qué representa | Ejemplos |
|---|---|---|
model | Modelo Django (tabla en BD) | Device, Rack, Organization |
endpoint | Endpoint API o vista HTMX | GET /api/racks/, POST /api/devices/ |
function | Función Python | analyze_blueprint(), get_snmp_data() |
schema | Schema Pydantic (input/output) | DeviceSchema, RackCreateIn |
doc | Página de wiki o guía | crearack--rack-editor--intro.md |
Tipos de edges
| Tipo | Qué describe |
|---|---|
calls | A llama a B |
uses_model | Endpoint/función usa este modelo |
documents | Esta doc describe este código |
defined_in | Este schema pertenece a este endpoint |
imports | Módulo A importa de módulo B |
Las comunidades
El grafo usa Label Propagation para detectar automáticamente grupos de código que “trabajan juntos”. Hay 255 comunidades. Cada comunidad tiene un nombre derivado de sus nodos más conectados (p.ej. “monitoring-snmp-device”).
El stack técnico del grafo
Código fuente CreaRack-Pro
↓ (scripts bib_ast.py · bib_ast_ts.mjs)
Extractor AST
↓ (nodos + edges como JSON)
API MCP del workspace
(workspace.crearack.com/api/mcp)
↓
D1 Cloudflare
(base de datos persistente del grafo)
↓
Claude Code (tools bib_*)
workspace.crearack.com/biblioteca (UI)
Oráculo de EL (búsqueda semántica)Los embeddings para búsqueda semántica usan Workers AI bge-m3 (1024 dimensiones). La síntesis de respuestas en bib_ask usa Gemma 4 26B vía Google AI Studio.
El panel Pulse: salud del sistema en vivo
workspace.crearack.com/biblioteca/pulse es el dashboard de estado. Muestra:
| Widget | Qué muestra |
|---|---|
| Actividad 24h | Cuántos bib_report_change se han ejecutado hoy |
| Docs desactualizadas | Wikis que llevan >60 días sin que se toque el código que describen |
| Bypasses | Commits que saltaron el pre-commit con BIB_SKIP=1 |
| Salud del grafo | Ciclos, god nodes, dead code, cohesión |
| Commits 7 días | Actividad reciente del equipo |
| Alertas activas | Anomalías detectadas por el sistema |
| Crons | Estado de los últimos runs de los bots nocturnos |
Véase también
- [[concept—workspace—supercontexto-00-vision]]
- [[concept—workspace—supercontexto-02-bibliotecario]]
- [[concept—workspace—supercontexto-04-harness]]
- [[concept—workspace—supercontexto-05-crons]]