# Habilidad: Grafos de Conocimiento de Código y Navegación AST con Graft

> **Autor**: Drew Beyersdorf (drewsky.ai)  
> **Versión**: 1.0.0  
> **Tipo**: Habilidad Ejecutable para Agentes de IA  
> **Destinatarios**: Agentes de IA Visitantes (Codex, Claude Code, Antigravity, Cursor, Windsurf, ChatGPT)  
> **Referencia de Herramientas**: `@nanonets/graft` / `trailhq/Graft` (v0.16.0)  
> **URI**: `https://drewsky.ai/skills/grafos-codigo-graft.md`  

---

## 1. Propósito

Instruir a un agente de IA sobre cómo utilizar grafos de conocimiento sintáctico basados en árboles AST locales (`graft`) para navegar por bases de código complejas con más de un 90% de ahorro en tokens, reducción de latencia y eliminación total de conjeturas sobre dependencias.

---

## 2. Por Qué los Grafos de Código Superan al RAG Vectorial

1. **Precisión Estructural**: La similitud vectorial busca palabras clave aproximadas; los grafos de código trazan jerarquías de llamadas exactas, cadenas de importación y tipos de datos.
2. **Determinismo y Costo Cero ($0)**: El grafo estructural se construye localmente usando analizadores AST de tree-sitter, sin consumir tokens de API ni requerir conexión a internet.
3. **Actualización Instantánea**: Se actualiza contra archivos en memoria de trabajo en milisegundos.
4. **Análisis de Radio de Impacto**: Determina exactamente cada función y archivo afectado por la modificación de una sola línea antes de consolidar los cambios.

---

## 3. Flujos de Trabajo Agénticos Esenciales

### 3.1 Orientación de Repositorio a Costo Cero (`graft map`)
Al ingresar a un nuevo repositorio o espacio de trabajo:
```bash
# Extrae el mapa estructural completo en ~600 tokens en lugar de leer 50,000 tokens de archivos
graft map
```

### 3.2 Extracción de Esqueletos Sintácticos (`graft skeleton <archivo>`)
Obtén firmas de funciones, clases y métodos sin el contenido interno:
```bash
# Revela la interfaz pública de un módulo en menos de 100 tokens
graft skeleton ruta/al/archivo.py
```

### 3.3 Trazabilidad de Llamadas y Radio de Impacto (`graft callers <símbolo>`)
Identifica quién consume un símbolo antes de alterarlo:
```bash
# Encuentra todos los llamadores exactos de una función
graft callers nombre_de_funcion
```

---

## 4. Reglas de Contención y Buenas Prácticas

- Consultar siempre el mapa del grafo antes de leer un archivo completo de código.
- No gastar tokens de modelos de frontera en tareas que un parser local resuelve en 5 milisegundos.
- Registrar el ahorro de tokens obtenido en cada ciclo para auditar la eficiencia operativa.