Recorte de contexto: Grafos de dependencias en lugar de repositorios completos

Para las tareas de código, la forma más rápida de inflar un prompt es pegar un repositorio completo cuando el modelo solo necesita un puñado de archivos.

Un grafo de dependencias te permite enviar estructura en lugar de volumen: un mapa de qué importa qué, además de los fragmentos específicos que realmente importan.

Resumen

Un grafo de dependencias es una pequeña estructura de datos que registra qué archivos o módulos importan, llaman o dependen de otros.

En lugar de pegar un código base completo en un prompt, recorres este grafo desde el archivo que se está modificando e incluyes solo los archivos a los que está estructuralmente conectado.

Esto mantiene el prompt pequeño y enfocado, lo que reduce el costo y evita diluir la atención del modelo con código no relacionado.

También escala mejor que adivinar manualmente qué archivos son relevantes, ya que el grafo se construye una vez y se reutiliza en muchos prompts.

Esta página explica cómo construir un grafo de dependencias mínimo en Python, usarlo para seleccionar archivos relevantes para un cambio y enviar ese contexto recortado a Claude.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

import ast
import os
 
def get_imports(filepath: str) -> set[str]:
    with open(filepath) as f:
        tree = ast.parse(f.read(), filename=filepath)
    imports = set()
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            imports.update(alias.name for alias in node.names)
        elif isinstance(node, ast.ImportFrom) and node.module:
            imports.add(node.module)
    return imports

Cuándo usarlo:

• La tarea trata sobre un archivo o función, pero ese archivo reside dentro de un repositorio mucho más grande.
• Quieres que Claude entienda cómo un cambio se propaga a los llamadores, sin enviar el código fuente completo de cada llamador.
• El repositorio es demasiado grande para caber en un solo prompt, incluso con una ventana de contexto generosa.
• Estás ejecutando el mismo tipo de prompt de revisión de código o refactorización repetidamente y quieres un paso de selección reutilizable.

Ejemplo de trabajo

import ast
import os
import anthropic
 
client = anthropic.Anthropic()
 
 
def get_imports(filepath: str) -> set[str]:
    """Devuelve el conjunto de nombres de módulos que importa un archivo Python."""
    with open(filepath) as f:
        tree = ast.parse(f.read(), filename=filepath)
    imports = set()
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            imports.update(alias.name for alias in node.names)
        elif isinstance(node, ast.ImportFrom) and node.module:
            imports.add(node.module)
    return imports
 
 
def build_dependency_graph(repo_root: str) -> dict[str, set[str]]:
    """Mapea cada ruta de archivo a los nombres de módulos que importa."""
    graph = {}
    for dirpath, _, filenames in os.walk(repo_root):
        for name in filenames:
            if name.endswith(".py"):
                path = os.path.join(dirpath, name)
                graph[path] = get_imports(path)
    return graph
 
 
def module_name_to_path(repo_root: str, module: str) -> str | None:
    """Mapeo de mejor esfuerzo de un nombre de módulo a una ruta de archivo."""
    candidate = os.path.join(repo_root, *module.split(".")) + ".py"
    return candidate if os.path.exists(candidate) else None
 
 
def relevant_files(repo_root: str, target_file: str, graph: dict[str, set[str]]) -> set[str]:
    """Archivos que el objetivo importa, más archivos que importan el objetivo."""
    related = {target_file}
    for module in graph.get(target_file, set()):
        path = module_name_to_path(repo_root, module)
        if path:
            related.add(path)
    for path, imports in graph.items():
        target_module = os.path.splitext(os.path.relpath(target_file, repo_root))[0].replace(os.sep, ".")
        if target_module in imports:
            related.add(path)
    return related
 
 
def prompt_with_trimmed_context(repo_root: str, target_file: str, question: str) -> str:
    graph = build_dependency_graph(repo_root)
    files = relevant_files(repo_root, target_file, graph)
 
    context_blocks = []
    for path in sorted(files):
        with open(path) as f:
            context_blocks.append(f"# {os.path.relpath(path, repo_root)}\n{f.read()}")
 
    prompt = f"{question}\n\n" + "\n\n".join(context_blocks)
 
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=500,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.content[0].text
 
 
answer = prompt_with_trimmed_context(
    repo_root="./billing_service",
    target_file="./billing_service/retry_queue.py",
    question="If I add a max_attempts parameter to retry_queue.py, what callers break?",
)
print(answer)

Lo que esto demuestra:

• build_dependency_graph recorre un repositorio una vez y registra las importaciones de cada archivo, lo cual es económico de calcular y reutilizable en muchos prompts.
• relevant_files recorre un salto en ambas direcciones: lo que importa el archivo objetivo y lo que importa el archivo objetivo.
• Solo los archivos en ese vecindario de un salto se leen e incluyen en el prompt, no todo el repositorio.
• El paso de construcción del grafo está separado del paso de construcción del prompt, por lo que el mismo grafo puede responder a muchas preguntas diferentes sobre diferentes archivos.

Análisis profundo

Cómo funciona

• ast.parse convierte el código fuente de Python en un árbol de sintaxis sin ejecutarlo, que es la forma segura y estándar de inspeccionar las importaciones.
• Recorrer el árbol con ast.walk encuentra cada nodo Import e ImportFrom independientemente de cuán profundamente esté anidado en el archivo.
• El grafo en sí es solo un diccionario que mapea las rutas de los archivos a los nombres de los módulos que importan, lo cual es suficiente para responder "de qué depende X" y, al invertir la búsqueda, "qué depende de X".
• Seleccionar un vecindario de un salto (dependencias directas y dependientes directos) suele ser suficiente contexto para la mayoría de los cambios de un solo archivo; una transversal más profunda incluye más archivos a costa de un prompt más grande.

Elección de la profundidad del grafo

Ir más allá de uno o dos saltos generalmente reintroduce el problema que esta técnica pretende resolver: el prompt vuelve a crecer hacia "todo el repositorio", solo que con pasos adicionales.

Notas de Python

# Protege contra archivos que no se pueden analizar (errores de sintaxis, no UTF8, etc.)
def get_imports_safe(filepath: str) -> set[str]:
    try:
        return get_imports(filepath)
    except (SyntaxError, UnicodeDecodeError):
        return set()

Los repositorios reales tienen archivos generados, código de terceros o errores de sintaxis ocasionales de ediciones en curso.

Envolver el paso de análisis para que un archivo defectuoso no bloquee toda la construcción del grafo lo hace práctico para ejecutarlo en un código base real.

Errores comunes

• Las importaciones relativas se resuelven incorrectamente. ast informa la cadena literal del módulo, por lo que una importación relativa como from . import utils necesita una resolución consciente del paquete, no una simple unión de rutas. Solución: resuelve las importaciones relativas con respecto a la ruta del paquete del archivo importador, o restringe el grafo a importaciones absolutas para una primera versión más simple.
• Las importaciones dinámicas son invisibles para ast. El código que importa a través de importlib.import_module(computed_name) no aparecerá como un nodo Import estático. Solución: trata los módulos cargados dinámicamente como una brecha conocida y agrega manualmente las dependencias dinámicas conocidas al grafo.
• El grafo se vuelve obsoleto si se construye una vez y se almacena en caché para siempre. Un código base que agrega nuevas importaciones no se reflejará en un grafo antiguo. Solución: reconstruye el grafo en cada ejecución para repositorios pequeños, o invalida la caché en los cambios de archivo para repositorios más grandes.
• Las dependencias circulares pueden causar una transversal ilimitada en recuentos de saltos más altos. Dos archivos que se importan entre sí, encadenados a través de varios archivos más, pueden hacer que una transversal de "2 saltos" incluya mucho más de lo esperado. Solución: rastrea los archivos visitados durante la transversal y deja de volver a visitar el mismo archivo.
• Un vecindario de un salto aún puede omitir el archivo realmente relevante. Algunos cambios arquitectónicos afectan un archivo sin una relación de importación directa, como un valor de configuración leído por convención en lugar de por importación. Solución: trata el grafo como un punto de partida, no como una garantía, y permite que un humano o un pase de puntuación de relevancia económico agregue los archivos que el grafo omite.

Alternativas

Preguntas frecuentes

Relacionado

• Cómo la ingeniería de contexto reduce el gasto de tokens - el modelo mental más amplio en el que encaja esta técnica.
• Conceptos básicos de ingeniería de prompts y contexto - ejemplos prácticos de recorte de prompts, incluido un enfoque de puntuación de relevancia más simple.
• Sumarización antes de la llamada - qué hacer cuando un archivo seleccionado sigue siendo demasiado largo.
• Evitar llamadas a herramientas redundantes en bucles de agente de múltiples turnos - una alternativa de uso de herramientas para precalcular un grafo.
• Corrupción del contexto: por qué más tokens no significan mejores respuestas - por qué incluir archivos no relacionados puede perjudicar la calidad de la respuesta, no solo el costo.

Versiones de pila: Escrito para la línea de modelos Claude actual a partir de junio de 2026: Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5, y el SDK oficial de Python de anthropic (última versión 0.x). Los nombres de los modelos, los precios y las versiones del SDK cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.