Guias

O que é graph engineering? Um CLAUDE.md de 8 linhas

Graph engineering é desenhar um sistema de agentes de IA como um grafo: os nós fazem o trabalho, as arestas decidem o que corre a seguir e o estado viaja entre eles. A nossa visão: o grafo substitui o ficheiro de instruções, por isso um CLAUDE.md pode encolher para 8 linhas enquanto o processo e as regras vivem em fluxos de trabalho e normas.

David Marsa

David Marsa

Founder & CEO

Intermédio8 min de leituraAtualizado em 10/10/2026

Última verificação: 07/10/2026

Ferramentas e modelos abordados:Claude Code
O que é graph engineering: um CLAUDE.md de 8 linhas alimenta uma triagem que envia o trabalho pelo caminho de funcionalidade ou de bug até Build + testes, e um ponto de aprovação Code review cujo não leva a uma correção e volta aos testes antes do fim.

O que vai conseguir fazer

  • Explicar graph engineering numa frase e em que é diferente do LangGraph.
  • Reduzir o CLAUDE.md ou o AGENTS.md de um agente a um ficheiro de identidade curto.
  • Transformar um processo que a sua equipa repete num fluxo de trabalho com decisões, pontos de aprovação e normas.
  • Provar os caminhos de «não» de um fluxo de trabalho plantando uma falha numa tarefa descartável.

Pontos-chave

  • Graph engineering é desenhar um sistema de agentes como um grafo: os nós fazem o trabalho, as arestas decidem o que corre a seguir e o estado viaja entre eles.
  • A nossa visão: o grafo substitui o ficheiro de instruções, que encolhe para um ficheiro de identidade de 8 linhas.
  • O processo passa para fluxos de trabalho de passos, decisões e pontos de aprovação, e as regras passam para normas lidas no passo.
  • A tarefa guarda o estado, por isso um ficheiro curto leva o trabalho através de sessões separadas.
  • O conhecimento cresce, o prompt não.

O problema: um CLAUDE.md que não para de crescer

Todas as equipas que usam um agente de programação com IA como o Claude Code mantêm um ficheiro de instruções, e esse ficheiro só cresce. CLAUDE.md, AGENTS.md, .cursorrules. Começa com vinte linhas: quem é o agente, como está organizado o repositório, meia dúzia de regras.

Depois chegam as lições. Um bug causado pelo agente passa a regra. Algumas regras pertencem a um hook, não a um ficheiro: veja como impedir que o Claude Code apague os seus ficheiros. Um processo que a equipa combinou passa a parágrafo. Aparece uma tabela de encaminhamento: «para bugs faça isto, para funcionalidades faça aquilo». Meses depois, o CLAUDE.md está demasiado longo: centenas de linhas, e o agente segue parte delas.

Isto não é uma impressão. A documentação de boas práticas do Claude Code da Anthropic di-lo sem rodeios: ficheiros CLAUDE.md inchados fazem com que o Claude ignore as suas instruções reais (Anthropic, Best practices for Claude Code(abre num novo separador)).

Cada linha acrescentada para melhorar o agente torna todas as outras mais fracas. O graph engineering é a forma como saímos dessa armadilha.

O que é graph engineering: a definição e a nossa visão

Graph engineering (engenharia de grafos) é desenhar um sistema de agentes como um grafo: os nós fazem o trabalho, as arestas decidem o que corre a seguir e o estado viaja entre eles. É esse o significado comum, e não fomos nós que criámos o termo. O LangGraph é uma biblioteca para construir esses grafos. O graph engineering é a disciplina.

Um CLAUDE.md de 412 linhas dividido em três: a tabela de encaminhamento, a checklist de release e o «pergunte sempre antes de fazer deploy» passam a um fluxo de trabalho com um ponto de aprovação de revisão de código, as regras de código e as lições passam a ficheiros de normas, e só fica um ficheiro de identidade de 8 linhas.

A nossa visão vai um passo mais longe. O grafo substitui o ficheiro de instruções. O agente nunca lê o processo inteiro de uma vez. Lê um passo, faz exatamente esse passo e avança. Há três coisas que ocupam o lugar do ficheiro longo:

O que é substituídoO que o substituiNuma linha
O ficheiro de instruçõesUm ficheiro de identidade de 8 linhasQuem é o agente, e «siga o passo, depois avance»
Os parágrafos de processoFluxos de trabalho: um grafo de passos, decisões e pontos de aprovaçãoUm pedido entra num nó, e uma decisão envia-o pelo caminho que lhe pertence
Os parágrafos de regrasNormas: ficheiros markdown simples, um por temaO agente que cada passo inicia lê-os nesse passo

A frase de que depende a ideia toda: o conhecimento cresce, o prompt não.

Corremos estes grafos como fluxos de trabalho do ConvOps(abre num novo separador), e cada exemplo abaixo é um deles, mostrado com dados de demonstração.

As cinco partes do grafo

Os nossos grafos têm cinco tipos de peça, e cada uma elimina uma secção do prompt antigo.

As cinco partes na funcionalidade de lista de espera da Brightloom: um passo (Build), uma decisão (Triage), um ponto de aprovação (Code review, cujo não vai para Fix review findings e volta a Run tests), uma norma (testing.md, lida pelo agente do passo) e o cartão da tarefa, que guarda o passo atual e a nota de cada passo.

ParteO que éO que substitui no prompt
Passo (nó)Uma unidade de trabalho com as suas próprias instruções: planear, construir, correr os testes, rever«Planeie sempre antes de programar, depois...»
DecisãoUm nó com várias arestas. Encaminha um pedido pelo caminho que lhe pertence, por exemplo funcionalidade ou bugA tabela de encaminhamento
Ponto de aprovaçãoUm passo que não avança sem um sim ou um não explícito. Os nossos pontos de aprovação dizem ao agente para parar e perguntar a uma pessoa. Um não envia o trabalho para um passo de correção«Pergunte sempre antes de...»
NormaUm ficheiro markdown em standards/, lido pelo agente que o passo iniciaRegras coladas no prompt
EstadoA tarefa, o seu passo atual e a nota que cada passo lhe deixaVoltar a explicar tudo em cada sessão

Porquê chamar-lhe engenharia? Porque o trabalho é escolher nós e arestas. Onde entra um pedido. Que decisão o envia para onde. Que agente lê que normas. Onde é que uma pessoa tem de dizer sim. Os passos deixam notas na tarefa, por isso o estado sobrevive a qualquer sessão.

Uma execução, passo a passo: uma tarefa, três sessões

O exemplo mais pequeno mostra a ideia toda: uma tarefa atravessa três sessões que nunca vê juntas, e o ficheiro de instruções nunca diz como. Pense na Brightloom, uma equipa fictícia de quatro pessoas que está a construir uma aplicação de reserva de aulas para estúdios de yoga. O ficheiro de instruções inteiro do agente, com os nomes das ferramentas em palavras simples:

# Who you are

You are the team's co-worker in this repo. The task system is your task list and your memory.

# How you work

1. Every request becomes a task: search first, then create one if none exists.
2. The task carries a workflow. Read the current step, do exactly what it says, then advance. Repeat until the workflow completes.

Nada sobre planear, testar, aprovações ou retomar. Entra um pedido: «Acrescente a política de cancelamento ao email de confirmação da reserva.» O agente cria a tarefa e o fluxo de trabalho de seis passos associa-se sozinho: Intake (receção), Analyze (análise, com aprovação), Implement (implementação), Verify (verificação, com aprovação), Capture Learnings (registo de aprendizagens), Complete (conclusão).

Três sessões na mesma tarefa com uma aprovação humana entre cada uma: a barra de progresso de seis passos para no ponto de aprovação Analyze, depois no ponto de aprovação Verify, e termina em Complete, 6 de 6.

SessãoO que lhe dizemO que o agente fazOnde para
1O pedidoIntake, depois um plano: editar emails/booking_confirmed.html, acrescentar um parágrafo, verificar a pré-visualizaçãoPonto de aprovação Analyze
PessoaAprova fora da sessão do agente
2«Continue onde ficámos.»Encontra a tarefa aberta, faz a alteração, escreve um relatório de verificação: a pré-visualização é apresentada, o parágrafo está láPonto de aprovação Verify
PessoaAprova
3«Continue onde ficámos.»Escreve a nota de aprendizagem «os modelos de email estão em emails/», fecha a tarefaComplete, 6 de 6

Nenhuma sessão guarda o estado. Cada sessão nova transforma «continue» em: encontrar a tarefa ativa, ler o seu passo, fazer esse passo. O ficheiro de identidade nunca diz como, porque a tarefa já sabe onde está.

Um grafo construído a conversar

Construímos grafos a descrevê-los, não a programá-los. A líder da Brightloom descreve o processo da equipa numa só conversa: uma decisão separa funcionalidades de bugs, um planner escreve um plano que espera por aprovação, os bugs começam com um teste que falha, e tudo termina num bloco partilhado de build, execução dos testes e uma revisão de código que devolve o trabalho quando a resposta é não. O agente transforma essa descrição nos fluxos de trabalho.

Numa conversa posterior, a líder pede uma revisão de normas depois dos testes. O agente acrescenta-a como um pequeno subfluxo com o seu próprio ciclo de correção, com entrada a partir de uma decisão, e a tarefa que o acrescenta passa pelo novo passo antes de fechar. O grafo cresce. O ficheiro de identidade não muda uma única linha. As lições chegam da mesma forma: cada uma vai para o passo ou a norma que precisava dela, o ciclo por trás de como construímos um sistema de IA que se melhora a si próprio.

O grafo de programação com a funcionalidade de lista de espera seguida em doze passos numerados: a primeira revisão de código diz não porque o teste nunca enche a aula, por isso o trabalho vai para uma correção, para os testes e para a revisão de normas antes de uma segunda revisão dizer sim.

Depois passa uma funcionalidade: «Acrescente uma lista de espera às aulas cheias.»

PassoQuemResultadoPonto de aprovação
Triage: funcionalidade ou bugdecisãoCaminho de funcionalidadeautomático
Plan the feature (planear a funcionalidade)plannerjoin_waitlist(class_id, member), ordem de chegada, promover quando há cancelamento, 5 testessim de uma pessoa
Build, depois Run testsdeveloper, depois a sessão principalwaitlist.py e 5 testes, 5 passaramnota
Standards gate, Standards reviewstandards-reviewerVerificado face a standards/testing.md: 0 problemassim de uma pessoa
Code review, ronda 1code-reviewer«test_full_class_goes_to_waitlist nunca enche a aula primeiro, por isso passa com uma aula vazia»não de uma pessoa
Fix review findings (corrigir os problemas da revisão)developerEnche a aula até à sua capacidade de 12 antes de entrar na listanota
Run tests, normas, Code review ronda 2sessão principal, standards-reviewer, code-reviewer5 passaram, normas aprovadas, sem problemassim de uma pessoa
Done (concluído)Tarefa concluída

O não é o que interessa. O revisor apanha um teste que não prova nada, uma pessoa concorda, e o grafo envia o trabalho para a correção, depois para os testes e depois para uma segunda revisão. Ninguém escreveu «se a revisão falhar, volte atrás» num prompt. É uma aresta.

O que corre mal: passagens de testemunho e caminhos de não por testar

Um grafo tira o processo do prompt. Não torna seguras, por si só, as passagens de testemunho nem os caminhos por testar. Deparámo-nos com as duas coisas.

O agente seguinte não lê as notas. Depois de Plan the feature, o agente developer começa só com o seu briefing. O plano aprovado está na tarefa como uma nota de passo que ele nunca abre, e uma sessão nova só vê pré-visualizações curtas das notas mais recentes. A regra que seguimos agora: a sessão principal põe o plano aprovado e os problemas em aberto no briefing do agente seguinte. A nota fica na tarefa como registo, e o briefing leva aquilo de que o passo seguinte precisa.

Um caminho de não que ninguém percorreu não está provado. O nosso primeiro ciclo de revisão passou a validação sem erros, e mesmo assim o primeiro não real não conseguiu seguir a aresta de volta. Uma validação limpa prova a forma, não o caminho.

A regra: plante uma falha numa tarefa descartável e veja o caminho de não correr do princípio ao fim. Para a Brightloom, isso significa uma função sem teste: a revisão de normas apanha-a, a correção acrescenta o teste, a nova verificação passa e a tarefa descartável é cancelada.

Quando compensa o graph engineering

Um grafo é um custo a mais para trabalho pontual e paga-se a si próprio em tudo o que a equipa repete.

Prompt ou grafo: o trabalho pontual fica num prompt simples, todo o trabalho que a equipa repete ganha um grafo, e os pontos de aprovação só vão onde o trabalho tem de parar por um sim ou um não.

SituaçãoMelhor escolha
Scripts pontuais, exploração, uma pergunta rápidaUm prompt simples
Um processo que a equipa repete: funcionalidades, bugs, releases, revisõesUm grafo. Cada repetição corre os mesmos passos
Várias pessoas ou agentes a fazer o mesmo tipo de trabalhoUm grafo. O processo vive num só sítio, não no ficheiro de cada pessoa
Trabalho que precisa do sim de uma pessoa antes de avançarUm grafo com pontos de aprovação. Um ponto de aprovação é um nó, por isso espera por uma aprovação em cada execução
Um ficheiro de instruções com mais de algumas centenas de linhasUm grafo. Tire primeiro o processo, depois as regras

Se o seu ficheiro já passou desse ponto, CLAUDE.md demasiado longo? O que cortar e para onde vai percorre a auditoria linha a linha.

Para experimentar o graph engineering num processo que a sua equipa repete, ligue o seu agente ao ConvOps(abre num novo separador), descreva o processo e faça passar a sua próxima tarefa pelo fluxo de trabalho que ele constrói. Para um grafo que corre de forma agendada sem ninguém o iniciar, veja como fazemos experiências de SEO com o Claude Code, ou um ciclo de site que se repara sozinho em que cada bug tem a sua própria execução num ambiente isolado. Para ver uma empresa inteira a funcionar com estes grafos, leia como gerimos a nossa empresa com fluxos de trabalho que se lembram. Para outras ferramentas que correm fluxos de trabalho de agentes, veja o diretório de orquestração de agentes de IA.

Perguntas frequentes

O que é graph engineering?

Graph engineering é desenhar um sistema de agentes de IA como um grafo: os nós fazem o trabalho, as arestas decidem o que corre a seguir e o estado viaja entre eles. No ConvOps, o grafo é um conjunto de fluxos de trabalho que o agente percorre um passo de cada vez, por isso o ficheiro de instruções pode encolher para um ficheiro de identidade de 8 linhas enquanto o processo vive no grafo.

Graph engineering é o mesmo que LangGraph?

Não. O LangGraph é uma biblioteca para construir grafos de agentes em código, e o graph engineering é a disciplina de os desenhar. Com o ConvOps, o grafo é um conjunto de fluxos de trabalho que o agente percorre através das suas ferramentas de tarefas, sem código de grafo no repositório. As decisões de desenho são as mesmas nos dois casos: onde entra um pedido, que decisão o encaminha e onde é que o trabalho para à espera de um sim.

O que devo fazer quando o meu CLAUDE.md está demasiado longo?

Tire o processo do ficheiro, não só as regras. Divida o ficheiro em três montes: quem é o agente fica, tudo o que tenha uma ordem de trabalho passa a um passo, uma decisão ou um ponto de aprovação de um fluxo de trabalho, e cada regra passa a um ficheiro de normas. No ConvOps, os fluxos de trabalho guardam os passos, por isso cada lição nova vai para um passo ou uma norma em vez de ir para o ficheiro.

O ficheiro CLAUDE.md ou AGENTS.md desaparece?

Não. Encolhe para um ficheiro de identidade: quem é o agente, que cada pedido passa a ser uma tarefa e que o agente segue o passo atual e depois avança. Na configuração que este guia mostra, são 8 linhas, e não mudam quando o grafo cresce, porque o processo novo vai para fluxos de trabalho e as regras novas vão para normas.

O que impede o agente de saltar um ponto de aprovação?

O fluxo de trabalho. Um passo de aprovação não avança sem um sim ou um não explícito, e no ConvOps as próprias instruções desse passo dizem ao agente para parar e perguntar a uma pessoa. O ficheiro de identidade nunca tem de dizer «pergunte sempre antes de fazer deploy», porque a paragem está no passo onde se aplica.

Os agentes precisam das suas próprias instruções?

Sim, curtas. Cada função (planner, developer, code-reviewer, standards-reviewer) tem um ficheiro de agente de poucas linhas que diz o que faz e o encaminha para standards/. É o passo do fluxo de trabalho que decide que função corre, por isso os ficheiros das funções continuam pequenos e o processo continua no grafo.

Aprenda isto ao vivo

Claude Code for Teams

Ver o workshop