Otimizando o Contexto: Grafos de Dependência em Vez de Repositórios Completos

Para tarefas de código, a maneira mais rápida de inflar um prompt é colar um repositório inteiro quando o modelo só precisa de um punhado de arquivos.

Um grafo de dependência permite enviar estrutura em vez de volume: um mapa de o que importa o quê, mais os trechos específicos que realmente importam.

Resumo

Um grafo de dependência é uma pequena estrutura de dados que registra quais arquivos ou módulos importam, chamam ou dependem de outros.

Em vez de colar um codebase inteiro em um prompt, você percorre este grafo a partir do arquivo que está sendo alterado e puxa apenas os arquivos aos quais ele está estruturalmente conectado.

Isso mantém o prompt pequeno e focado, o que reduz o custo e evita diluir a atenção do modelo com código não relacionado.

Ele também escala melhor do que adivinhar manualmente quais arquivos são relevantes, já que o grafo é construído uma vez e reutilizado em vários prompts.

Esta página detalha a construção de um grafo de dependência mínimo em Python, seu uso para selecionar arquivos relevantes para uma alteração e o envio desse contexto otimizado para o Claude.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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

Quando usar isso:

• A tarefa é sobre um arquivo ou função, mas esse arquivo está dentro de um repositório muito maior.
• Você quer que o Claude entenda como uma alteração se propaga para os chamadores, sem enviar o código completo de todos os chamadores.
• O repositório é muito grande para caber em um único prompt, mesmo com uma janela de contexto generosa.
• Você está executando o mesmo tipo de prompt de revisão de código ou refatoração repetidamente e deseja uma etapa de seleção reutilizável.

Exemplo de Trabalho

import ast
import os
import anthropic
 
 
client = anthropic.Anthropic()
 
 
def get_imports(filepath: str) -> set[str]:
    """Retorna o conjunto de nomes de módulos que um arquivo Python importa."""
    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]]:
    """Mapeia cada caminho de arquivo para os nomes de módulos que ele 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:
    """Mapeamento de melhor esforço de um nome de módulo de volta para um caminho de arquivo."""
    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]:
    """Arquivos que o alvo importa, mais arquivos que importam o alvo."""
    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="Se eu adicionar um parâmetro max_attempts a retry_queue.py, quais chamadores quebrarão?",
)
print(answer)

O que isso demonstra:

• build_dependency_graph percorre um repositório uma vez e registra as importações de cada arquivo, o que é barato de computar e reutilizável em vários prompts.
• relevant_files percorre um salto em ambas as direções: o que o arquivo de destino importa e o que importa o arquivo de destino.
• Apenas os arquivos nesse vizinhança de um salto são lidos e incluídos no prompt, não o repositório inteiro.
• A etapa de construção do grafo é separada da etapa de construção do prompt, para que o mesmo grafo possa responder a muitas perguntas diferentes sobre arquivos diferentes.

Mergulho Profundo

Como Funciona

• ast.parse transforma o código-fonte Python em uma árvore de sintaxe sem executá-lo, que é a maneira segura e padrão de inspecionar importações.
• Percorrer a árvore com ast.walk encontra todos os nós Import e ImportFrom, independentemente de quão aninhados estejam no arquivo.
• O grafo em si é apenas um dicionário que mapeia caminhos de arquivo para os nomes de módulos que eles importam, o que é suficiente para responder "do que X depende" e, invertendo a consulta, "o que depende de X".
• Selecionar uma vizinhança de um salto (dependências diretas e dependentes diretos) geralmente é contexto suficiente para a maioria das alterações de arquivo único; a travessia mais profunda puxa mais arquivos ao custo de um prompt maior.

Escolhendo a Profundidade do Grafo

Ir além de um ou dois saltos geralmente reintroduz o problema que esta técnica visa resolver: o prompt cresce de volta para "o repositório inteiro", apenas com etapas extras.

Notas de Python

# Protege contra arquivos que falham na análise (erros de sintaxe, não-UTF8, etc.)
def get_imports_safe(filepath: str) -> set[str]:
    try:
        return get_imports(filepath)
    except (SyntaxError, UnicodeDecodeError):
        return set()

Repositórios reais têm arquivos gerados, código incluído ou erros de sintaxe ocasionais de edições em andamento.

Envolver a etapa de análise para que um arquivo ruim não trave toda a construção do grafo mantém isso prático para executar em um codebase real.

Armadilhas

• Importações relativas são resolvidas incorretamente. ast relata a string de módulo literal, então uma importação relativa como from . import utils precisa de resolução ciente do pacote, não de junção simples de caminhos. Correção: resolva importações relativas contra o caminho do pacote do arquivo importador, ou restrinja o grafo a importações absolutas para uma primeira versão mais simples.
• Importações dinâmicas são invisíveis para ast. Código que importa via importlib.import_module(computed_name) não aparecerá como um nó Import estático. Correção: trate módulos carregados dinamicamente como uma lacuna conhecida e adicione manualmente dependências dinâmicas conhecidas ao grafo.
• O grafo fica obsoleto se for construído uma vez e armazenado em cache para sempre. Um codebase que adiciona novas importações não será refletido em um grafo antigo. Correção: reconstrua o grafo a cada execução para repositórios pequenos, ou invalide o cache em alterações de arquivo para os maiores.
• Dependências circulares podem causar travessia ilimitada em contagens de saltos mais altas. Dois arquivos que se importam, encadeados através de vários outros arquivos, podem fazer com que uma travessia de "2 saltos" puxe muito mais do que o esperado. Correção: rastreie os arquivos visitados durante a travessia e pare de revisitar o mesmo arquivo.
• Uma vizinhança de um salto ainda pode perder o arquivo realmente relevante. Algumas alterações arquitetônicas afetam um arquivo sem uma relação de importação direta, como um valor de configuração lido por convenção em vez de importação. Correção: trate o grafo como um ponto de partida, não como uma garantia, e deixe um humano ou uma passagem de pontuação de relevância barata adicionar arquivos que o grafo perde.

Alternativas

FAQs

Relacionados

• Como a Engenharia de Contexto Reduz o Gasto de Tokens - o modelo mental mais amplo em que esta técnica se encaixa.
• Noções Básicas de Engenharia de Prompt e Contexto - exemplos práticos de otimização de prompts, incluindo uma abordagem mais simples de pontuação de relevância.
• Sumarização Antes da Chamada - o que fazer quando um arquivo selecionado ainda é muito longo.
• Evitando Chamadas de Ferramentas Redundantes em Loops de Agente de Múltiplas Voltas - uma alternativa de uso de ferramentas para pré-computar um grafo.
• Deterioração do Contexto: Por Que Mais Tokens Não Significam Melhores Respostas - por que incluir arquivos não relacionados pode prejudicar a qualidade da resposta, não apenas o custo.

Versões da Stack: Escrito contra a linha de modelos Claude atual por volta de Junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.