Inteligencia de Código Basada en Grafo y Memoria (`codebase-mem…

Memoria de Código e Inteligencia Basada en Grafo (codebase-memory)

Esta habilidad define los estándares de ingeniería, los procedimientos operativos y los contratos de uso de herramientas para explorar, buscar y comprender el código utilizando el grafo de conocimiento codebase-memory MCP.

---

Invariante Central: El Protocolo de Índice Primero

[!CRITICAL] INVARIANTE DE ÍNDICE PRIMERO: La re-indexación automática en segundo plano está permanentemente deshabilitada (auto_watch = false) en este espacio de trabajo para evitar thrashing del disco, sobrecarga de serialización zstd y tartamudeo del sistema durante la edición activa de archivos.

En consecuencia, el agente DEBE SIEMPRE verificar la frescura del índice o activar una re-indexación bajo demanda (index_repository) antes de ejecutar búsquedas contra el grafo de conocimiento del código.

Siempre que se te asigne la tarea de encontrar un símbolo, entender un módulo, investigar un error o preparar una refactorización, ejecuta la Puerta de Índice Primero antes de realizar llamadas de búsqueda.

---

Jerarquía de Herramientas: Grafo Primero, Grep Segundo

Al descubrir, navegar o revisar código, adhiérete estrictamente a esta jerarquía de precedencia:

flowchart TD
    Tarea[Tarea de Descubrimiento/Investigación de Código] --> Frescura{¿Índice Fresco?}
    Frescura -->|No / Desconocido / Después de Ediciones| Sync[index_repository modo: 'fast' o 'moderate']
    Frescura -->|Sí| Estrategia{Tipo de Consulta}
    Sync --> Estrategia

    Estrategia -->|Símbolo / Función / Interfaz| BuscarGrafo[search_graph BM25 o semantic_query]
    Estrategia -->|Llamantes / Llamados / Dependencias| RastrearRuta[trace_path callers / callees]
    Estrategia -->|Radio de Explosión de Cambios| DetectarCambios[detect_changes diff a conjunto de impacto]
    Estrategia -->|Código Fuente Exacto| ObtenerFragmento[get_code_snippet líneas precisas]
    Estrategia -->|Capas del Sistema y Módulos Hub| ObtenerArq[get_architecture nodos de alta centralidad]
    Estrategia -->|Cadenas Literales / No Código / Activos| RespaldoGrep[search_code o run_command grep]

1. search_graph > grep de texto: Búsqueda estructural clasificada BM25 con división camelCase, aumento de etiquetas (Funciones +10, Rutas +8, Interfaces +5) e incrustaciones de vectores.
2. trace_path > salto manual de archivos: Resolución instantánea de grafos de llamantes y llamados de múltiples saltos.
3. get_code_snippet > view_file en archivos grandes: Recupera la declaración y el cuerpo exactos de un símbolo con líneas de inicio/fin y recuentos de llamantes sin inflar el contexto del agente.
4. detect_changes > inspección manual de diff: Mapea los diffs de git (since: "HEAD~1", base_branch: "main") directamente a su radio de explosión transitivo.
5. Respaldo Grep: Usa search_code o run_command (git grep, rg) SÓLO para:
   • Texto literal en markdown (.md), configuración (.json) u hojas de estilo (.css).
   • Rangos de líneas explícitamente marcados bajo parse_partial en index_status.
   • Archivos excluidos por diseño a través de .cbmignore.

---

Flujo de Trabajo Operativo Estándar

Paso 1: Puerta de Sincronización de Índice (Acción Obligatoria Primera)

Antes de emitir consultas de búsqueda, determina el nombre del proyecto y asegúrate de que el grafo refleje las ediciones recientes del sistema de archivos.

1. Identificar el Nombre del Proyecto: Llama a list_projects si el identificador del proyecto es desconocido:

   {
     "ServerName": "codebase-memory",
     "ToolName": "list_projects",
     "Arguments": {}
   }
   

   _(En este espacio de trabajo, el nombre del proyecto derivado es "D-Scripts-aminwebsite").

2. Verificar Estado o Refrescar Índice: Si se crearon o modificaron archivos durante la sesión, llama a index_repository:

   {
     "ServerName": "codebase-memory",
     "ToolName": "index_repository",
     "Arguments": {
       "repo_path": "d:/Scripts/aminwebsite",
       "mode": "fast"
     }
   }
   

   • Selección de Modo:
     • mode: "fast": Análisis incremental, archivos filtrados, sin incrustaciones de vectores semánticos. Rápido y ligero para desarrollo activo.
     • mode: "moderate": Análisis incremental + incrustaciones de similitud de vectores para puente de conceptos en lenguaje natural.
   • Inspección de Cobertura: Verifica la respuesta para:
     • parse_partial: Archivos donde ciertos rangos de líneas tuvieron errores de análisis.
     • skipped: Archivos completamente omitidos (por ejemplo, binarios o de tamaño excesivo).

---

Paso 2: Descubrimiento de Símbolos y Estructura (search_graph)

Encuentra funciones, interfaces, tipos, componentes y definiciones de rutas.

{
  "ServerName": "codebase-memory",
  "ToolName": "search_graph",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "query": "LocaleSwitcher"
  }
}

• Descubrimiento en Lenguaje Natural: Usa query para búsqueda por palabra clave / BM25 (por ejemplo, "theme toggle transition", "locale routing").
• Patrón de Nombre Exacto: Usa name_pattern para filtrado regex (por ejemplo, ".*Provider.*", ".*Skeleton.*").
• Búsqueda Conceptual Semántica: Usa semantic_query: ["i18n", "language", "switch"] (requiere un array de cadenas) para puentear brechas de vocabulario.
• Manejo de Truncamiento (has_more): Si la respuesta devuelve "has_more": true, pagina agregando "offset": <current_offset + limit>.

---

Paso 3: Rastreo de Relaciones y Radio de Explosión

Nunca modifiques una función o interfaz sin inspeccionar sus dependientes.

1. Rastrear Llamantes y Llamados (trace_path):

   {
     "ServerName": "codebase-memory",
     "ToolName": "trace_path",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "function_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.handleSelectLocale",
       "direction": "both",
       "depth": 3
     }
   }
   

   • direction: "inbound": Identifica todos los llamantes que dependen de esta función (radio de explosión).
   • direction: "outbound": Identifica funciones aguas abajo llamadas por este símbolo.
   • direction: "both": Cadena de llamadas bidireccional completa.

2. Mapear el Conjunto de Impacto del Diff Git (detect_changes): Antes de confirmar o finalizar cambios, evalúa el radio de explosión:

   {
     "ServerName": "codebase-memory",
     "ToolName": "detect_changes",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "base_branch": "main",
       "scope": "impact"
     }
   }
   

---

Paso 4: Recuperación Quirúrgica de Código (get_code_snippet)

En lugar de consumir contexto viendo archivos completos con view_file, recupera implementaciones exactas de símbolos:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_code_snippet",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "qualified_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.LocaleSwitcher"
  }
}

La respuesta incluye:

• start_line y end_line exactos
• Código fuente limpio del símbolo
• Recuentos de llamantes y llamados directos

---

Paso 5: Exploración de Arquitectura de Alto Nivel (get_architecture)

Al orientarse en un nuevo subsistema o comprender la topología del sistema:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_architecture",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "aspects": ["layers", "hub_nodes"]
  }
}

Identifica los principales componentes arquitectónicos hub, dependencias centrales y jerarquía de capas.

---

Matriz de Referencia de Herramientas Perezosas MCP

Capacidad	Herramienta	Parámetros Requeridos	Parámetros Opcionales Clave
Verificar Estado	index_status	project	N/A
Activar Indexación	index_repository	repo_path	mode ("fast", "moderate", "full"), persistence
Listar Proyectos	list_projects	None	N/A
Buscar Símbolos	search_graph	project	query, name_pattern, semantic_query, limit, offset
Rastrear Cadena Llam.	trace_path	project, function_name	direction ("inbound", "outbound", "both"), depth, mode
Recuperar Fuente	get_code_snippet	project, qualified_name	include_neighbors
Radio de Explosión	detect_changes	project	base_branch, since, scope ("impact", "files"), depth
Arquitectura	get_architecture	project	aspects (["hub_nodes"], ["layers"], ["all"])
Texto Literal	search_code	project, query	file_pattern, case_sensitive, limit

---

Barreras de Protección y Antipatrones Comunes

Antipatrón	Estándar Operativo Correcto
Buscar sin verificar frescura del índice	Siempre llama a index_repository(mode: "fast") o verifica con index_status primero, ya que la auto-vigilancia en segundo plano está deshabilitada.
Usar grep para encontrar definiciones de funciones	Llama a search_graph con el nombre del símbolo; devuelve nombres completos, rutas de archivo exactas, rangos de líneas y recuentos de llamantes.
Leer 1000 líneas de un archivo para ver 1 función	Llama a get_code_snippet con el qualified_name del símbolo.
Leer manualmente cada archivo para encontrar llamantes	Llama a trace_path con direction: "inbound".
Asumir que el grafo está 100% completo	El grafo es de mejor esfuerzo. Si index_status lista archivos bajo parse_partial, usa grep de texto para esos rangos de líneas específicos marcados.
Habilitar auto_watch	Nunca habilites auto_watch; manténlo en false para mantener el rendimiento máximo del desarrollo interactivo.