Aprende a conectar un «GPS» y un «bisturí de precisión» a Claude Code para que trabaje más rápido, cometa menos errores y ahorre dinero.
- ¿Por qué hacemos esto y cómo funciona? (Explicado fácil)
Imagina que contratas a un asistente inteligente (Claude Code) para reparar una mansión enorme y compleja (tu proyecto de software).
Sin ayuda externa, Claude hace lo siguiente:
Entra a oscuras habitación por habitación buscando una llave perdida.
Abre cajón por cajón (lee cientos de archivos completos).
Esto toma mucho tiempo, gasta muchos recursos (tokens/dinero) y a veces se cansa o confunde cosas.
Para evitar esto, le entregamos dos superherramientas:
1. ¿Qué hace cada pieza?
CodeGraph (El Mapa / GPS):
Crea una maqueta o mapa relacional de todo tu código antes de empezar. Cuando Claude pregunta «¿dónde está la función de inicio de sesión y a quién afecta si la cambio?», CodeGraph se lo dice en un segundo, sin tener que escanear archivo por archivo.
Serena (El Cirujano / Bisturí):
Permite a Claude editar código a nivel de "símbolo" (la función específica, la variable o la clase), en lugar de reescribir archivos enteros de 500 líneas con riesgo de borrar cosas por accidente.
¿Cómo lo orquesta Claude Code?
Paso A: Recibe tu instrucción.
Paso B: Primero consulta a CodeGraph para entender dónde tocar y cuál es el impacto.
Paso C: Luego usa Serena para ir directamente a la línea exacta y realizar la modificación limpia.
2. Paso previo: Instalar lo necesario en tu computadora
Antes de conectarlos a Claude, necesitamos tener el motor que los ejecuta. Usaremos una herramienta moderna llamada uv, que instala y corre programas en lenguaje Python de forma ultrarrápida y sin errores de configuración.
2.1. Instalar uv (El gestor universal)
Abre tu Terminal (en Mac/Linux) o PowerShell (en Windows) y pega el comando correspondiente:
En Mac o Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
En Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
2.2. Instalar Serena y CodeGraph
Con uv listo, instalamos ambos paquetes
codegraph macOS / Linux -> link al repo codegraph
en el repositorio oficial veremos un step by step, de como se instala y regresaremos a este post.
serena corremos este comando:
uv tool install -p 3.13 serena-agent y hacemos serena init en el proyecto que la vamos a usar.
3. Paso 1: Agregar Serena a Claude Code
Claude Code cuenta con un sistema llamado MCP (Protocolo de Contexto de Modelo), que le permite conectar enchufes o accesorios externos.
Abre tu terminal.
Ve a la carpeta de tu proyecto (escribe cd seguido de un espacio y arrastra tu carpeta a la terminal, luego pulsa Enter):
cd /ruta/de/tu/proyecto
Ejecuta este comando para vincular Serena:
claude mcp add serena -- serena-mcp-server --context ide-assistant --project .
¿Qué significa este comando?
Le estás diciendo a Claude: «Añade un accesorio llamado "serena", ejecútalo en modo asistente y analiza el proyecto que está en esta carpeta actual (.).
4. Paso 2: Agregar CodeGraph a Claude Code
Ahora conectamos el mapa del proyecto.
4.1. Primero: Crear el mapa inicial de tu proyecto
En la misma carpeta de tu proyecto, corre: codegraph init Verás un mensaje indicando que indexó entidades y relaciones (generalmente toma entre 2 y 10 segundos).
5. Paso 3: Configurar Hooks para que Claude NO se salte las herramientas
El problema de las IAs distraídas
Si solo le dices a Claude: «Por favor, usa siempre CodeGraph y Serena», el modelo puede olvidarlo cuando tiene prisa o cuando la conversación se alarga.
La solución: Los "Hooks" (Reglas obligatorias de sistema)
Un Hook no es una sugerencia; es un candado programado dentro de Claude Code que se dispara automáticamente en momentos clave de la sesión.
Vamos a configurar dos salvaguardas:
Un Hook de inicio de consulta (UserPromptSubmit): Cada vez que le pidas algo, el sistema le inyecta la orden estricta a su memoria de trabajo antes de procesar la respuesta.
Un archivo de directrices (CLAUDE.md): La constitución de tu proyecto.
Paso a paso para activar el Hook:
Dentro de la carpeta de tu proyecto, entra a la carpeta oculta .claude (si no existe, créala).
Crea o edita el archivo llamado settings.json dentro de .claude:
Ruta: .claude/settings.json
Pega la siguiente configuración exacta:
{
"hooks": {
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "echo 'REGLA OBLIGATORIA DEL SISTEMA: Antes de explorar archivos con grep o lectura manual ciega, consulta obligatoriamente CODEGRAPH para mapear dependencias y SERENA para ubicar y modificar los símbolos relevantes.'"
}
]
}
]
}
}
¿Cómo funciona esto?
Cada vez que presionas Enter con una pregunta o tarea, el Hook se ejecuta en una fracción de milisegundo y le dice al oído a Claude: «Alto, no explores a ciegas; consulta primero CodeGraph y Serena». Claude no puede ignorarlo porque viene inyectado a nivel de sistema.
Paso complementario: El archivo CLAUDE.md
En la raíz de tu proyecto, crea un archivo de texto llamado CLAUDE.md y pega esto:
# Reglas de Operación del Proyecto
## 1. Búsqueda y Exploración
- Prohibido hacer barridos masivos de archivos con búsquedas de texto tradicionales si la información puede obtenerse con CodeGraph.
- Usa las herramientas de `codegraph` para identificar qué funciones llaman a qué otras y cuál es el mapa arquitectónico.
## 2. Modificación de Código
- Para renombrar, inspeccionar o editar funciones, clases o métodos, utiliza prioritariamente las herramientas de `serena`.
- No leas archivos enteros si solo necesitas el cuerpo de una función específica.
6. Paso 4: Cómo comprobar que todo está funcionando
Hacer una prueba real
Hazle una pregunta estructural a Claude sobre tu proyecto:
«Explícame qué hace este proyecto y cuáles son los componentes principales según CodeGraph.»
Observarás que Claude ejecutará una herramienta llamada codegraph o serena directamente en lugar de ponerse a abrir archivos de texto al azar.
Top comments (0)