O manual completo de Engenharia de Grafos para Claude Code

A maioria das pessoas ainda usa o Claude Code como um estagiário muito caro.

Elas dão uma tarefa, esperam por uma resposta e decidem manualmente o que vem a seguir.

Mas os times que estão extraindo o máximo de valor da IA estão construindo algo mais próximo de um pequeno sistema distribuído.

Um agente define o escopo do problema.

Cinco agentes mais baratos pesquisam em paralelo.

Um script determinístico remove duplicatas.

Três agentes céticos tentam refutar as descobertas.

Um modelo de alto nível faz o julgamento final.

Isso é engenharia de grafos.

Antes de continuar lendo:

Salve este guia nos favoritos para que você possa retornar aos padrões de grafos quando começar a construir seus próprios fluxos de trabalho no Claude.

Siga

@Gyome1_ -

Eu analiso Claude Code, agentes de IA e os sistemas que transformam um modelo em um fluxo de trabalho de engenharia confiável.

Passei semanas dissecando arquiteturas reais de agentes, diagramas de fluxo de trabalho e padrões de produção para reconstruir a Engenharia de Grafos em um guia prático.

Em vez de escrever um prompt mais longo, você projeta o caminho que a informação percorre através do sistema:

linear → expandir → reduzir → verificar → sintetizar

Cada agente se torna um nó com uma função limitada. Cada aresta carrega dados estruturados. Roteadores decidem qual ramo é executado. Verificadores rejeitam saídas fracas. Loops continuam até o grafo parar de encontrar algo novo.

A mudança importante é que o Claude Code não precisa mais se comportar como uma única inteligência trabalhando em uma lista de verificação gigante.

Ele pode gerar o código de orquestração, gerar uma frota de subagentes especializados, rotear suas saídas através de diferentes modelos e montar o resultado final somente após a evidência sobreviver à verificação.

Os padrões básicos não são novos. Engenheiros de software usam DAGs, pipelines, barreiras, MapReduce e workers distribuídos há décadas.

O que mudou é o que agora reside dentro de cada nó.

Um nó pode pesquisar um repositório, auditar uma migração, desafiar uma decisão arquitetural, inspecionar falhas de teste ou sintetizar cinquenta descobertas independentes em um único relatório citado.

Este guia detalha todo o sistema, desde o agente linear mais simples até grafos diamante, nós roteadores, painéis de verificação adversária, loops de convergência, hierarquia de modelos e fluxos de trabalho dinâmicos gerados diretamente dentro do Claude Code.

Ao final, você será capaz de olhar para uma tarefa grande e parar de perguntar:

"Qual prompt devo escrever?"

1. A ENGENHARIA DE GRAFOS COMEÇA COM A CONTA

A engenharia de grafos é frequentemente apresentada como uma forma de executar mais agentes.

Esse enquadramento perde a parte cara.

Você pode lançar vinte agentes Claude contra o mesmo repositório e receber vinte relatórios sobrepostos, contexto repetido, conclusões conflitantes e uma conta de API muito maior.

Um grafo útil controla onde a computação acontece, qual modelo lida com cada decisão e como descobertas incertas se movem pelo fluxo de trabalho.

Imagine pedir ao Claude Code para preparar uma migração de produção:

Inspecione o repositório, encontre todas as dependências, proponha a migração, identifique riscos, verifique o plano e escreva o briefing final.

Dentro de um único prompt, isso se torna um processo longo e opaco. O Claude pesquisa a base de código, armazena descobertas no contexto, projeta a migração, revisa seu próprio plano e produz o relatório final.

Quando o relatório falha, a origem da falha é difícil de localizar. O Claude pode ter perdido um arquivo, entendido mal uma dependência, perdido um detalhe anterior ou aceitado uma suposição fraca durante a verificação.

Cada estágio também pode ser executado no mesmo modelo caro, mesmo quando partes da tarefa envolvem extração ou classificação simples.

A engenharia de grafos abre esse fluxo de trabalho e dá a cada decisão um lugar visível.

Os ramos de inspeção são executados ao mesmo tempo porque usam a mesma tarefa com escopo definido e não dependem da saída um do outro.

Suas descobertas se encontram em um estágio de redução, onde as duplicatas desaparecem e a evidência é comprimida em um conjunto de dados menor.

Um roteador então lê a gravidade. Mudanças de rotina passam por uma revisão leve. Descobertas de alto risco recebem uma análise mais profunda de vários revisores independentes antes de chegar ao modelo final.

O resultado é um fluxo de trabalho onde latência, custo do modelo, tamanho do contexto e profundidade da verificação são controlados através da estrutura do grafo.

Um nó deve tomar uma decisão

Um nó útil tem uma responsabilidade limitada.

Encontre todas as chamadas para a API obsoleta. Classifique cada risco de migração como baixo, médio ou alto. Teste o plano de reversão para casos de falha.

Cada nó precisa de uma entrada clara, uma saída definida e uma superfície de decisão limitada.

Um nó que pesquisa o repositório, estima o impacto nos negócios, projeta a correção e escreve a recomendação ainda contém vários estágios ocultos. A depuração continua difícil porque o raciocínio intermediário está enterrado dentro de uma única chamada de modelo.

Limites menores revelam onde a evidência entrou no sistema e onde seu significado mudou.

Uma aresta deve carregar evidência

Uma aresta representa dados necessários para o próximo nó.

O scanner pode retornar um objeto previsível:

1{
2  "file": "src/auth/session.ts",
3  "lines": [84, 119],
4  "dependency": "legacySessionClient",
5  "confidence": 0.94,
6  "evidence": "Ambos os locais de chamada dependem do método refresh obsoleto."
7}

O classificador de risco agora recebe os mesmos campos para cada descoberta. Ele pode rejeitar resultados incompletos, agrupar arquivos relacionados e rotear evidências incertas para outra revisão.

Esquemas reduzem o desvio de interpretação entre nós. Parágrafos de forma livre forçam cada agente downstream a reconstruir o significado do agente anterior. Ao longo de vários estágios, pequenas ambiguidades podem alterar a conclusão final.

A saída estruturada mantém a evidência estável enquanto ela se move através do grafo.

Alguns nós são código comum

Suponha que oito agentes de busca retornem oitenta descobertas.

O fluxo de trabalho precisa combinar arrays, descartar respostas vazias, remover duplicatas e classificar os itens restantes.

Essas operações têm respostas determinísticas:

1const uniqueFindings = [
2  ...new Map(
3    results
4      .flatMap(batch => batch ?? [])
5      .map(item => [`${item.file}:${item.lines.join("-")}`, item])
6  ).values()
7];

Uma transformação JavaScript lida com isso instantaneamente e produz a mesma saída em todas as execuções. Enviar a mesma tarefa para outro modelo adiciona custo de token e cria outro lugar onde a evidência pode desaparecer.

Nós de modelo pertencem em torno de busca, classificação, comparação, revisão e síntese. O código pode lidar com validação, deduplicação, classificação, regras de roteamento explícitas e outras transformações previsíveis.

Essa divisão se torna a base do grafo.

Toda chamada de modelo deve corresponder a uma decisão que realmente exige julgamento.

2. O DIAMANTE: COMO OS GRAFOS DE AGENTES REAIS MOVEM O TRABALHO

A maioria dos grafos de agentes sérios acaba assumindo a mesma forma.

Uma tarefa começa com um escopo compartilhado, se divide em vários workers independentes, espera por suas saídas, comprime a evidência e passa o resultado para uma decisão final.

Essa forma é o diamante.

O lado esquerdo é a expansão.

O ponto médio onde todos os ramos se encontram é a barreira.

O lado direito é a contração.

Esse padrão aparece em todos os lugares quando uma tarefa se torna grande demais para uma janela de contexto.

Uma auditoria de repositório pode ser dividida por subsistema. Um relatório de mercado pode ser dividido por fonte. Uma tarefa de pesquisa pode ser dividida por hipótese. Uma revisão de migração pode ser dividida em uso de API, alterações no banco de dados, risco de implantação e cobertura de teste.

Cada worker recebe o mesmo escopo com uma atribuição mais restrita.

O grafo então espera até que evidências úteis suficientes tenham retornado.

A expansão deve criar trabalho independente

Um ramo pertence à expansão quando pode começar a partir da entrada compartilhada e produzir um resultado útil sem ler a saída de outro ramo.

Para uma auditoria de segurança, a divisão pode ser assim:

O Claude Code pode lançar essas chamadas simultaneamente com uma primitiva de barreira, como parallel()

1const findings = await parallel(
2  checks.map(check => async () => {
3    return agent({
4      task: check.task,
5      context: auditScope,
6      schema: FINDING_SCHEMA
7    });
8  })
9);

A orquestração permanece em JavaScript comum. Cada ramo recebe uma tarefa limitada e retorna um objeto validado.

O resultado chega como uma coleção de saídas que podem ser filtradas, inspecionadas e passadas para o próximo estágio.

Uma grande expansão ainda precisa de uma razão por trás de cada ramo.

Dividir uma tarefa vaga em doze agentes quase idênticos geralmente produz descobertas repetidas com redações ligeiramente diferentes. O paralelismo útil vem de fontes, perspectivas, regiões de código ou hipóteses distintas.

A barreira cria um ponto de decisão

Uma barreira pausa o próximo estágio até que os ramos necessários tenham sido concluídos.

Essa pausa é importante porque algumas decisões dependem do conjunto completo.

Um nó de classificação não pode identificar a vulnerabilidade mais importante enquanto metade do repositório ainda está sendo inspecionada. Um modelo de síntese não pode escrever um plano de migração completo enquanto a revisão de implantação ainda está em execução.

Na barreira, o grafo tem a chance de inspecionar o estado da execução:

1const completed = findings.filter(Boolean);
2
3if (completed.length < MIN_REQUIRED_RESULTS) {
4  throw new Error("Cobertura de auditoria insuficiente");
5}

É aqui que as falhas parciais se tornam visíveis.

Um worker pode expirar, retornar dados malformados ou não produzir descobertas. Filtrar valores nulos mantém a execução em andamento, mas fluxos de trabalho de produção geralmente precisam de uma política mais clara:

• quantos ramos bem-sucedidos são necessários;
• quais ramos são obrigatórios;
• se um nó com falha deve tentar novamente;
• se o resultado final deve ser marcado como incompleto.

A barreira é, portanto, parte do modelo de confiabilidade, não apenas um mecanismo de sincronização.

Reduza antes de sintetizar

Após a expansão, o grafo pode conter dezenas de descobertas sobrepostas.

Enviar todas elas diretamente para um modelo de alto nível cria um contexto grande, repete a mesma evidência e torna detalhes importantes mais difíceis de distinguir.

O estágio de redução prepara a evidência.

Alguma redução pode acontecer em código:

1const unique = deduplicateByKey(
2  completed.flatMap(result => result.findings),
3  finding => `${finding.file}:${finding.line}:${finding.type}`
4);

A próxima camada pode exigir julgamento:

1const curated = await agent({
2  task: `
3    Agrupe descobertas relacionadas.
4    Preserve todas as referências de arquivo e linha.
5    Classifique cada grupo por impacto operacional.
6    Retorne a evidência mais forte para cada conclusão.
7  `,
8  input: unique,
9  schema: CURATED_FINDINGS_SCHEMA
10});

A redução controla o que chega ao modelo final.

Um bom redutor remove a repetição enquanto preserva a evidência. Um redutor agressivo pode comprimir vários riscos distintos em um resumo vago e apagar os detalhes necessários para a verificação.

O padrão mais seguro mantém um link entre cada afirmação reduzida e seus itens de origem.

1{
2  "risk": "A renovação da sessão pode falhar após a migração",
3  "severity": "alta",
4  "sourceFindingIds": ["AUTH-04", "API-11", "TEST-07"],
5  "evidence": [
6    "Três serviços chamam o método refresh obsoleto",
7    "Nenhum caminho de fallback existe",
8    "A cobertura de integração está faltando"
9  ]
10}

Agora o nó de síntese recebe um conjunto de dados menor sem perder a rastreabilidade.

3. CONFIABILIDADE FAZ PARTE DO GRAFO

Um grafo pode terminar rapidamente e ainda produzir uma resposta ruim.

Assim que vários agentes começam a pesquisar, classificar e revisar a mesma tarefa, o problema principal se torna o controle.

O sistema precisa de regras para decidir quais descobertas merecem trabalho mais aprofundado, quais saídas devem ser rejeitadas e quando o fluxo de trabalho pesquisou o suficiente.

Roteie pelo risco

Um nó roteador lê a saída estruturada e escolhe o próximo ramo.

A classificação pode vir de um modelo, enquanto o ramo em si permanece explícito no código.

1const route =
2  finding.severity === "alta"
3    ? runFullAudit(finding)
4    : runQuickReview(finding);

Isso mantém a revisão cara concentrada em torno de descobertas com impacto significativo.

Um roteador útil depende de campos que o grafo pode inspecionar: gravidade, confiança, sistemas afetados, exposição financeira ou a presença de evidências ausentes.

Adicione verificação independente

Um agente revisando sua própria conclusão carrega as mesmas suposições em ambos os estágios.

Um grafo mais forte envia descobertas importantes para vários revisores com atribuições diferentes.

Os revisores não devem receber instruções para melhorar a resposta original. A tarefa deles é procurar razões pelas quais ela pode estar incompleta ou errada.

O grafo pode exigir concordância antes que uma descoberta avance:

1const accepted = votes.filter(vote => vote.approve).length >= 2;

Isole agentes que alteram código

Agentes de codificação paralela podem interferir uns nos outros quando editam o mesmo diretório de trabalho.

Um agente pode sobrescrever um arquivo enquanto outro ainda o está lendo. Testes podem ser executados contra uma mistura de alterações não relacionadas.

Git worktrees dão a cada ramo sua própria cópia do repositório.

1repositório principal
2      │
3      ├→ worktree/correcao-auth
4      ├→ worktree/migracao-bd
5      └→ worktree/reparo-teste

Cada agente pode modificar arquivos e executar testes dentro de seu próprio ambiente. Um nó posterior compara os patches, verifica conflitos e seleciona o que deve ser mesclado.

Isso transforma o isolamento em parte do grafo, em vez de uma etapa de limpeza manual.

Deixe a descoberta convergir

Algumas tarefas não podem ser concluídas em uma única passagem.

Uma auditoria de repositório pode descobrir uma dependência que aponta para outro pacote. Esse pacote pode revelar outro local de chamada. O grafo precisa de uma maneira controlada de continuar pesquisando sem repetir tudo o que já viu.

1const seen = new Set();
2let dryRounds = 0;
3
4while (dryRounds < 2) {
5  const findings = await discoverNext([...seen]);
6  const fresh = findings.filter(item => !seen.has(item.id));
7
8  fresh.forEach(item => seen.add(item.id));
9  dryRounds = fresh.length === 0 ? dryRounds + 1 : 0;
10}

O detalhe importante é a deduplicação contra cada item visto anteriormente.

Deduplicar apenas contra descobertas confirmadas permite que itens rejeitados ou incertos retornem na próxima passagem e consumam o mesmo trabalho novamente.

O loop para após várias rodadas secas, um orçamento fixo ou um número máximo de iterações. Grafos de produção geralmente precisam de todos os três.

Combine o modelo ao nó

Todo nó não precisa do modelo mais forte disponível.

Extração, classificação básica e buscas estreitas podem frequentemente ser executadas em um nível mais rápido. Revisão de arquitetura, verificação adversária e síntese final podem justificar um modelo mais forte.

A hierarquia de modelos se torna outra propriedade do grafo.

O orçamento é determinado por quantos nós são executados, com que frequência os loops se repetem, quanto contexto cruza cada aresta e qual modelo lida com cada estágio.

Um grafo com vinte chamadas de busca baratas ainda pode custar mais do que uma chamada forte. A arquitetura precisa de um orçamento de token antes de precisar de outro ramo.

Saiba quando parar de desenhar

Tarefas pequenas raramente precisam de roteadores, painéis de votação, worktrees e loops de convergência.

A sobrecarga do grafo inclui código de orquestração, esquemas, novas tentativas, registro em log, armazenamento intermediário e mais estados de falha para depurar.

Um fluxo de trabalho linear geralmente é suficiente quando um modelo pode conter o contexto relevante, a tarefa tem poucos ramos independentes e o custo de uma resposta errada é baixo.

A engenharia de grafos se torna útil à medida que a tarefa ganha trabalho paralelo, decisões caras, grandes conjuntos de evidências ou requisitos de verificação significativos.

O fluxo de trabalho completo pode eventualmente se parecer com isto:

O valor vem de tornar o movimento do trabalho visível.

Cada nó tem uma responsabilidade limitada. Cada aresta carrega evidência estruturada. Cada ramo tem uma razão para existir. Cada loop tem uma condição de parada.

Nesse ponto, o Claude Code não está mais trabalhando em uma longa instrução.

Ele está executando um sistema projetado.