Uma lista de tarefas não é um plano de execução

Projetos de software raramente carecem de uma lista de tarefas. Jira, planilha, arquivo Markdown, foto de um quadro que ninguém consegue ler uma semana depois. O que muitas vezes falta é um plano de execução. Isso funciona por bastante tempo, porque o plano está na cabeça das pessoas. Alguém simplesmente sabe que a integração de pagamentos não pode começar antes de estabilizar o modelo de pedidos e que “pronto” significa que os números foram de fato conferidos.

Os agentes tornam essa lacuna visível. Um agente não absorve o plano não escrito nas conversas de corredor. Ele recebe o que você fornece, e uma lista de tarefas é surpreendentemente pouco.

O que uma lista não diz

Uma lista de tarefas responde a uma pergunta: o que precisa acontecer? Um plano de execução precisa responder a várias outras:

• Ordem. O que depende do quê e o que pode rodar em paralelo?
• Entradas. O que este trabalho precisa saber antes de começar: qual decisão, qual contrato, quais arquivos?
• Saídas. O que ele produz que outro trabalho vai consumir?
• Pronto. Que evidência mostra que terminou e quem ou o que confere essa evidência?

Com pessoas, boa parte disso é negociada em conversas. Com agentes, quem encaminha o trabalho faz essa negociação — geralmente eu, copiando contexto entre sessões e tentando lembrar qual branch estava esperando por qual. É essa parte que estou tentando tornar explícita.

A direção que estou experimentando

O fluxo que estou explorando nos meus projetos é assim:

produto, jornadas e telas → PRD → especificação técnica → grafo de execução → trabalho dos agentes → verificação → integração

Os primeiros passos são trabalho normal de produto e arquitetura, e continuam sendo decisões humanas. O passo interessante está no meio: transformar uma especificação aprovada em um grafo em que cada nó é uma unidade de trabalho com suas dependências, o contexto que pode acessar, o que deve produzir e os critérios que precisa cumprir.

Este é um exemplo conceitual. Ilustra o formato, não é um arquivo de um sistema em funcionamento:

- id: order-status-api
  depends_on: [order-model]
  context: [tech-spec#orders, decisions/0007-status-names]
  produces: [GET /orders/{id}/status]
  done_when:
    - contract tests pass
    - status names match the decision record

- id: status-notifications
  depends_on: [order-status-api]
  context: [tech-spec#notifications]
  produces: [notification on status change]
  done_when:
    - integration test covers the status → notification path

Não há nada sofisticado aqui. O importante é que as relações, os limites e a definição de pronto estejam em algo que uma ferramenta possa ler, em vez de na minha memória. É isso que chamo de engenharia de grafos neste contexto: explicitar as relações e o estado da execução. O termo também é usado de outras formas. A LangChain o usa para construir agentes como grafos de nós e arestas; não se trata de uma disciplina nova, GraphRAG ou banco de dados em grafo.

Três grafos, três perguntas

Algo que vivia confundindo minhas anotações: não existe um grafo. Existem pelo menos três, e eles respondem a perguntas diferentes.

• Um grafo de funcionalidades pergunta: do que o produto precisa e quais capacidades se apoiam em outras?
• Um grafo de dependências de projetos pergunta: quais partes do código dependem de quais? O Nx, por exemplo, constrói um grafo de projetos a partir do repositório e um grafo de tarefas ao executá-las, e os usa para descobrir o que uma mudança afeta.
• Um grafo de execução pergunta: qual trabalho acontece a seguir, com qual contexto, e como sabemos que terminou?

Misturá-los produz planos que parecem rigorosos e não respondem bem a nenhuma das perguntas. Uma funcionalidade pode tocar cinco projetos; uma tarefa pode existir apenas para verificar outra.

Quando não usar um grafo

Sinceramente, na maior parte do tempo.

Se o trabalho são três passos, uma pessoa e uma tarde, uma lista de verificação é a ferramenta certa. Um grafo tem custo: alguém precisa escrevê-lo, mantê-lo alinhado à realidade e decidir o que acontece quando estiver errado. Se o plano muda toda hora, o grafo vira apenas uma forma muito estruturada de estar desatualizado.

As situações em que acho que compensa são mais específicas:

• quando o trabalho se divide entre vários agentes ou sessões e ninguém tem a visão completa;
• quando as dependências são reais e errar custa caro;
• quando “pronto” exige evidência, não uma caixa marcada.

Estou testando isso nos meus projetos e ainda não sei onde fica a linha entre estrutura útil e um segundo produto para manter. É sobre essa pergunta que continuarei escrevendo: quando um grafo resolve a coordenação de verdade e quando uma lista simples basta?