@saulwade/swl-ses 2.0.0 → 2.1.0

package/reglas/usar-code-review-graph.md

@@ -0,0 +1,155 @@
+# 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`).