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.

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ído | O que o substitui | Numa linha |
|---|---|---|
| O ficheiro de instruções | Um ficheiro de identidade de 8 linhas | Quem é o agente, e «siga o passo, depois avance» |
| Os parágrafos de processo | Fluxos de trabalho: um grafo de passos, decisões e pontos de aprovação | Um pedido entra num nó, e uma decisão envia-o pelo caminho que lhe pertence |
| Os parágrafos de regras | Normas: ficheiros markdown simples, um por tema | O 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.

| Parte | O 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ão | Um nó com várias arestas. Encaminha um pedido pelo caminho que lhe pertence, por exemplo funcionalidade ou bug | A tabela de encaminhamento |
| Ponto de aprovação | Um 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...» |
| Norma | Um ficheiro markdown em standards/, lido pelo agente que o passo inicia | Regras coladas no prompt |
| Estado | A tarefa, o seu passo atual e a nota que cada passo lhe deixa | Voltar 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).

| Sessão | O que lhe dizem | O que o agente faz | Onde para |
|---|---|---|---|
| 1 | O pedido | Intake, depois um plano: editar emails/booking_confirmed.html, acrescentar um parágrafo, verificar a pré-visualização | Ponto de aprovação Analyze |
| Pessoa | Aprova 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 |
| Pessoa | Aprova | ||
| 3 | «Continue onde ficámos.» | Escreve a nota de aprendizagem «os modelos de email estão em emails/», fecha a tarefa | Complete, 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.

Depois passa uma funcionalidade: «Acrescente uma lista de espera às aulas cheias.»
| Passo | Quem | Resultado | Ponto de aprovação |
|---|---|---|---|
| Triage: funcionalidade ou bug | decisão | Caminho de funcionalidade | automático |
| Plan the feature (planear a funcionalidade) | planner | join_waitlist(class_id, member), ordem de chegada, promover quando há cancelamento, 5 testes | sim de uma pessoa |
| Build, depois Run tests | developer, depois a sessão principal | waitlist.py e 5 testes, 5 passaram | nota |
| Standards gate, Standards review | standards-reviewer | Verificado face a standards/testing.md: 0 problemas | sim de uma pessoa |
| Code review, ronda 1 | code-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) | developer | Enche a aula até à sua capacidade de 12 antes de entrar na lista | nota |
| Run tests, normas, Code review ronda 2 | sessão principal, standards-reviewer, code-reviewer | 5 passaram, normas aprovadas, sem problemas | sim 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.

| Situação | Melhor escolha |
|---|---|
| Scripts pontuais, exploração, uma pergunta rápida | Um prompt simples |
| Um processo que a equipa repete: funcionalidades, bugs, releases, revisões | Um grafo. Cada repetição corre os mesmos passos |
| Várias pessoas ou agentes a fazer o mesmo tipo de trabalho | Um 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çar | Um 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 linhas | Um 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.
