AST Comprehension — Query, no leas
Explorar código ajeno pidiendo solo lo que necesitas. El patrón RLM (Recursive Language Models — Zhang, Kraska, Khattab, MIT CSAIL 2025) trata el codebase como dato externo que el modelo examina recursivamente con queries tipadas, en vez de cargar ficheros enteros al contexto.
Regla: antes de Read de un fichero completo, pregúntate si la respuesta cabe en una de las 6 queries tipadas abajo. Si cabe, úsala. Solo cae a Read para ficheros pequeños donde genuinamente necesitas la lectura completa.
Cuándo usar
- Pre-edición: antes de editar un fichero existente → pide solo el símbolo afectado + callers
- Legacy assessment (
/legacy-assess): explora desde entrypoints, sigue la cadena - Evaluate repo (
/evaluate-repo): estructura + símbolos clave - Comprehension report (
/comprehension-report): documentar arquitectura sin dump completo - Debugging cross-file: "¿quién llama a X con estos parámetros?"
Diferencia con ast-quality-gate
| Skill | Input | Pregunta | Output |
|---|---|---|---|
ast-quality-gate |
Código generado por IA | ¿Tiene errores? | Score + issues |
ast-comprehension |
Código ajeno/legacy | ¿Qué hace y cómo? | Respuesta a query tipada |
Las 6 queries tipadas (RLM pattern)
Cada query responde una pregunta concreta con un recipe bash que Claude ejecuta directamente. No hay server, no hay daemon — solo instrucción disciplinada sobre grep/sed/tree-sitter. Tokens estimados por operación típica en un proyecto de 10k LoC.
1. symbol-search <name> — encontrar dónde está definido
Pregunta: ¿Dónde se define useAuthStore?
grep -rn "^\(export \)\?\(function\|const\|class\|def\) <name>" src/ --include="*.{ts,tsx,js,vue,py,go,rs}"
Tokens: ~20. Evita listar cada mención del nombre.
2. impl <name> <file> — leer la implementación exacta
Pregunta: ¿Qué hace scanDirectory en walker.ts?
# Con tree-sitter (preferido, si instalado):
tree-sitter parse <file> | jq '.. | select(.type=="function_declaration" and .name=="<name>")'
# Sin tree-sitter (fallback): encontrar línea de definición y extraer hasta el cierre de llaves
awk '/^(export )?(function|const|class) <name>/,/^}/' <file>
Tokens: ~50-200 según tamaño de la función. Siempre menor que leer el fichero (500-3000 LoC típico).
3. callers <name> — quién usa este símbolo
Pregunta: ¿Qué componentes llaman a useAuthStore?
grep -rn "<name>(" src/ --include="*.{ts,tsx,vue,js}" | grep -v "function <name>\|const <name>"
Tokens: ~3 por caller. En savia-web, useAuthStore tiene 56 sites → ~200 tokens vs ~15k si lees los 19 ficheros completos. 75x menos.
4. tests <name> — tests que referencian X
Pregunta: ¿Hay cobertura de useAuthStore?
grep -rn "<name>" "**/__tests__/" "**/*.test.*" "**/*.spec.*" "tests/" 2>/dev/null
Tokens: ~5 por test reference. Evita listar tests que solo rozan el término.
5. peek <file> <start> <end> — rango exacto de líneas
Pregunta: ¿Qué hay en config.ts líneas 40-65?
sed -n '<start>,<end>p' <file>
Tokens: proporcional al rango. Úsalo cuando ya sabes dónde mirar.
6. grep-code <pattern> — scope-aware (código, no comentarios)
Pregunta: ¿Dónde se usa el flag STRICT_MODE en código real, no en comentarios?
# Filtro heurístico: excluir líneas que empiezan con // # /* * (comentarios comunes)
grep -rn "<pattern>" src/ | grep -vE '^\s*(//|#|/\*|\*)'
Tokens: típicamente 5-10x menos que grep plano en código con mucho comentario.
Pipeline de exploración (RLM)
- Entrypoint — Empieza en algo concreto: error message, función, endpoint API, log line. Usa
symbol-searchogrep-codepara localizarlo. - Impl — Lee la implementación exacta con
impl. No el fichero — la función. - Trace up —
callerspara saber quién invoca. Lee esos impls. Repite. - Trace tests —
testspara ver cobertura. Los tests suelen contener el uso canónico. - Parar cuando tengas la narrativa. No cuando hayas leído cada cosa relacionada.
Backend opt-in: CodeGraph MCP
Las 6 queries tienen ahora dos backends. Si el MCP codegraph está activo
en el proyecto (ver .opencode/skills/codegraph/SKILL.md), se usa como
backend preferido — devuelve resultados resueltos semánticamente, no matches
de grep que pueden ser comentarios o strings.
| Query | Backend MCP (preferido) | Backend grep (fallback) |
|---|---|---|
symbol-search |
codegraph_search |
grep -rn |
impl |
codegraph_node --source |
awk |
callers |
codegraph_callers |
grep + filtro |
callees |
codegraph_callees |
n/a |
tests |
codegraph_search --kind test |
grep en __tests__/ |
grep-code |
codegraph_search filtrado |
grep con filtro de comentarios |
Además CodeGraph añade dos queries que grep no puede emular:
codegraph_impact <symbol>— qué se afecta al cambiar X.codegraph affected --stdin— tests afectados por un diff (CI).
El agente decide el backend en runtime con codegraph_status. Sin CodeGraph
activo, todo sigue funcionando con grep.
Anti-patterns
- ❌
Readde un fichero entero para responder "¿qué hace función X?" → usaimpl. - ❌
grepseguido deReadde cada match → usacallers(devuelve solo call sites). - ❌ Dump JSON monolítico para un fichero cuando la pregunta era sobre 1 símbolo → usa
impl. - ❌ Leer test file completo para entender qué prueba un símbolo → usa
tests.
Extracción monolítica (fallback para legacy assessment)
Si la tarea es inventariar un codebase entero (no responder una pregunta), entonces sí corresponde el dump completo. Ver references/extraction-commands.md para el pipeline de 3 capas (tree-sitter + semgrep + native tooling) y references/comprehension-schema.md para el JSON schema.
Prerrequisitos
tree-sitter-cli(opcional):npm install -g tree-sitter-cli— mejoraimplygrep-code.jqpara normalización JSON de tree-sitter output.awk/sed/grep(siempre disponibles) — fallback suficiente para las 6 queries.
Referencias
- Paper RLM: Recursive Language Models — Zhang, Kraska, Khattab (arXiv:2512.24601).
- Research interno:
output/research-coderlm-20260418.md— evaluación de coderlm y decisión de robar patrón sin adoptar el binario. references/extraction-commands.md— comandos por lenguaje.references/comprehension-schema.md— JSON schema del modo monolítico.