# Regla: Usar code-review-graph antes de Read/Grep/Glob para explorar

Esta regla es OBLIGATORIA y aplica a todo proyecto del usuario donde el MCP
server `code-review-graph` esté disponible (sus herramientas
`mcp__code-review-graph__*` aparecen registradas o deferred en la sesión, o el
proyecto declara el grafo en su `CLAUDE.md`).

El grafo de conocimiento es un índice estructural del codebase construido con
Tree-sitter: nodos (archivos, clases, funciones, tipos, tests) y aristas
(llamadas, imports, dependencias, cobertura). Consultarlo es **más barato en
tokens**, **más rápido** y aporta **contexto estructural** (callers, dependents,
blast radius, tests) que un `Grep`/`Read` plano no puede dar.

---

## Principio

> Cuando necesites **explorar, entender, revisar o medir impacto** de código y
> el grafo `code-review-graph` esté disponible, **consúltalo PRIMERO** con las
> herramientas `mcp__code-review-graph__*`. Cae a `Read`/`Grep`/`Glob` solo
> cuando el grafo no cubre lo que necesitas (ver excepciones), no por inercia.

El costo de una consulta al grafo es de segundos y pocos tokens. El costo de
leer 5-10 archivos completos para reconstruir relaciones que el grafo ya conoce
es contexto desperdiciado y dinero.

---

## Cuándo usar el grafo PRIMERO (obligatorio)

| Necesidad | Herramienta del grafo | En vez de |
|---|---|---|
| Encontrar una función/clase/tipo por nombre o keyword | `semantic_search_nodes_tool` | `Grep` amplio |
| Entender la arquitectura de alto nivel | `get_architecture_overview_tool`, `list_communities_tool` | leer N archivos para inferir estructura |
| Trazar callers / callees / imports / tests | `query_graph_tool` (patrones callers_of, callees_of, imports_of, tests_for, dependencies) | `Grep` recursivo + lectura manual |
| Medir blast radius de un cambio | `get_impact_radius_tool` | rastrear imports a mano |
| Saber qué flujos de ejecución afecta un cambio | `get_affected_flows_tool` | inferir leyendo |
| Revisar cambios (code review) con riesgo puntuado | `detect_changes_tool` | `git diff` + leer archivos completos |
| Obtener snippets justos para revisar | `get_review_context_tool`, `get_minimal_context_tool` | `Read` de archivos enteros |
| Planear renames / detectar código muerto | `refactor_tool` | `Grep` + verificación manual |
| Funciones grandes / hubs / puentes arquitectónicos | `find_large_functions_tool`, `get_hub_nodes_tool`, `get_bridge_nodes_tool` | heurística manual |
| Verificar cobertura de tests de un símbolo | `query_graph_tool` pattern `tests_for` | `Grep` de nombres de test |

Antes de una sesión de exploración/revisión, vale `list_graph_stats_tool` para
confirmar que el grafo está construido y fresco (`Last updated`).

---

## Workflow estándar

1. **Localizar**: `semantic_search_nodes_tool` con el nombre/keyword del símbolo
   o `get_architecture_overview_tool` para el mapa general.
2. **Relacionar**: `query_graph_tool` (callers/callees/imports/tests) o
   `get_impact_radius_tool` para el blast radius.
3. **Leer dirigido**: `get_review_context_tool`/`get_minimal_context_tool` para
   traer solo los snippets relevantes — no el archivo completo.
4. **Caer al filesystem solo entonces**: si el grafo no cubre el detalle
   concreto (líneas exactas no indexadas, archivos no parseados, formatos no
   soportados), ahí sí `Read`/`Grep` con foco específico.

El grafo se auto-actualiza vía hooks al cambiar archivos. Si `list_graph_stats`
muestra un `Last updated` viejo respecto a cambios recientes, reconstruir con
`build_or_update_graph_tool` antes de confiar en sus resultados.

---

## Cuándo SÍ usar Read/Grep/Glob directo (excepciones)

NO forzar el grafo cuando:

1. **El grafo no está disponible** — el proyecto no tiene `code-review-graph`
   instalado, o `list_graph_stats_tool` falla. Usar Read/Grep sin más.
2. **Lenguaje/formato no indexado** — el grafo parsea código fuente (Python, JS,
   TS, Go, Rust, Java, C#, bash). Para `.md`, `.json`, `.sql`, `.yaml`, `.env`,
   migraciones, seeds, configs → Read/Grep directo (el grafo no los modela).
3. **Necesitas líneas exactas o contenido literal** — verificar una cita
   `archivo:línea`, leer el cuerpo completo de un archivo que vas a editar,
   confirmar texto exacto. El grafo da estructura, no sustituye `Read` del
   archivo que vas a modificar.
4. **El usuario pidió explícitamente** leer un archivo concreto o hacer un grep
   puntual.
5. **Operación de un solo archivo ya conocido** — sabes exactamente qué archivo
   y qué línea; un `Read` dirigido es más simple que el grafo.
6. **El grafo está desactualizado** para el cambio recién hecho y no quieres
   reconstruirlo en ese instante — usa Grep para lo recién escrito.

Antes de editar un archivo, SIEMPRE `Read` del archivo (la regla de Edit lo
exige y la verificación de citas `archivo:línea` también). El grafo localiza
**qué** leer; no reemplaza la lectura del archivo que vas a tocar.

---

## Anti-patrones

- **`Grep` amplio del codebase** para encontrar una función cuando
  `semantic_search_nodes_tool` la ubica en una llamada.
- **Leer 5+ archivos completos** para entender la arquitectura sin haber
  consultado `get_architecture_overview_tool` primero.
- **Rastrear imports a mano con `Grep`** para estimar el impacto de un cambio en
  vez de `get_impact_radius_tool` / `get_affected_flows_tool`.
- **`git diff` + leer archivos enteros** para revisar cuando `detect_changes_tool`
  da el diff con riesgo puntuado y `get_review_context_tool` los snippets justos.
- **Defaultear a Read/Grep "porque es lo de siempre"** cuando las herramientas
  `mcp__code-review-graph__*` aparecen deferred (schemas not loaded) — deferred
  ≠ ausente: cargar el schema con `ToolSearch(query="select:<tool>")` y usarlo.
  Confundir "no cargado" con "no disponible" es el mismo error documentado para
  el MCP `obsidian` en `consultar-vault-primero.md`.
- **Confiar en el grafo sin verificar frescura** tras cambios recientes — si
  `Last updated` es anterior al cambio, reconstruir o caer a Grep para esa parte.

---

## Relación con otras reglas

- `~/.claude/rules/consultar-vault-primero.md` — patrón hermano: consultar la
  fuente curada (vault Obsidian para decisiones; grafo para estructura de
  código) antes de leer múltiples archivos. Mismo principio de economía de
  tokens y mismo anti-patrón de "deferred ≠ ausente".
- `~/.claude/rules/verificar-citas-normativas.md § Familia 2` — el grafo
  **localiza** la cita `archivo:línea`; verificarla aún exige `Read` del archivo
  real. El grafo no exime de la verificación de citas.
- `~/.claude/rules/harness-claude-code.md § Disciplina de input format` — repos
  grandes (>500 archivos) son donde el grafo da el mayor ahorro de tokens
  (6.8-49× por review según la nota de ese harness).
- `~/.claude/rules/analizar-directorios-antes-de-escribir.md` — para decidir
  DÓNDE escribir docs sigue siendo `ls`/`Glob`; el grafo es para explorar
  **código**, no estructura de directorios de documentación.

---

## Aplicabilidad

Aplica a:
- Claude Code (CLI, Desktop, IDE) en proyectos con `code-review-graph` activo.
- Sesiones de exploración, debugging, code review, refactor, análisis de impacto.

NO aplica a:
- Proyectos sin el grafo instalado.
- Exploración de documentación/configuración no indexada por el grafo.
- Sub-agentes que operan sobre un único archivo pasado como argumento.

---

## Origen

Formalizada el 2026-06-09 a petición explícita del usuario tras observar que en
una sesión larga (feature B-1 de SIGM) se usó `Grep`/`Read`/`Bash` directo de
forma intensiva para explorar el codebase mientras el MCP `code-review-graph`
estaba disponible y auto-actualizado (9336 nodos, 78247 aristas). El proyecto
SIGM ya documentaba la preferencia en su `CLAUDE.md` ("ALWAYS use the
code-review-graph MCP tools BEFORE using Grep/Glob/Read"), pero el usuario pidió
promoverla a regla global para que aplique a todo proyecto con el grafo, no solo
a SIGM. La regla global es ahora la fuente de verdad del comportamiento; el
`CLAUDE.md` de cada proyecto solo debe declarar que el grafo está disponible
(no re-derivar el comportamiento — ver `sin-duplicacion-reglas-globales.md`).
