O processo que está no código, não o que está na cabeça

Todo time tem dois processos: o que as pessoas acham que o sistema faz e o que o código realmente faz. PRD, reunião de refinamento e onboarding costumam descrever o primeiro. Os incidentes acontecem no segundo.

Na última semana construí uma ferramenta para fechar essa distância: uma skill do Claude Code que lê o código de uma aplicação e reconstrói os processos de negócio por trás dele como diagramas BPMN - validados, versionáveis e que abrem no bpmn.io ou no Camunda Modeler. Este post conta o que ela faz, para que serve e o caminho até aqui, que incluiu abrir um PR no Mermaid e depois fechá-lo.

Por que BPMN, e por que em texto

BPMN é a notação padrão para processos de negócio. Uma pessoa de produto, de operações ou de compliance consegue ler: quem participa, onde estão as decisões, o que acontece quando algo dá errado. Não é diagrama de sequência nem fluxograma de funções. É o processo.

O problema é a ferramenta. BPMN costuma viver em editores visuais e em arquivos XML que ninguém revisa num pull request. Diagrama que não passa por revisão desatualiza, e diagrama desatualizado é pior do que nenhum, porque as pessoas confiam nele.

Então a escolha foi escrever BPMN como texto, no estilo do Mermaid:

bpmn LR
  pool "Shop"
    start message s1 "Receive order"
    task:user t1 "Review order"
    xor g1 "Items available?"
    end e1 "Order shipped"
    end e2 "Order backordered"
  s1 --> t1 --> g1
  g1 -- "Yes" --> e1
  g1 -->|default| e2

Texto entra no git, aparece num diff, pode ser revisado em PR e - o ponto que mais importa hoje - pode ser escrito por um modelo de linguagem.

O que a skill faz

Você abre o repositório no Claude Code e pede para mapear um fluxo de negócio. A skill:

• descobre os fluxos a partir de rotas, consumidores de fila, jobs agendados, enums de status, webhooks e integrações externas;
• modela o processo de negócio, não o grafo de chamadas: atores viram pools e lanes, decisões viram gateways, esperas viram eventos de tempo;
• valida o diagrama e, quando há erro, a mensagem já diz como corrigir, para o próprio agente iterar até ficar válido;
• aplica um lint de estilo: gateways como perguntas, desfechos nomeados, caminhos paralelos que se fecham, rótulos em linguagem de negócio e não nomes de função;
• gera um catálogo de regras em que cada decisão, limite e timeout aponta para o arquivo e a linha de onde saiu;
• exporta BPMN 2.0 XML para abrir no bpmn.io ou no Camunda.

Esse catálogo é o que mais me interessa. Um diagrama sem lastro é opinião. Um diagrama em que cada gateway cita a linha de código é um recibo.

Onde isso já foi usado

Usei a skill numa empresa em que trabalho para mapear um fluxo que atravessa vários serviços: uma visão geral e sete etapas, com cerca de 80 regras de negócio, cada uma ligada à sua origem no código. O mapa agora está indo para a documentação do time, e estou começando a usar a mesma abordagem para discutir PRDs.

O efeito mais útil não foi o desenho. Foi a lista de lacunas. Quando você obriga cada regra a ter um arquivo e uma linha, aparecem as que não têm: comportamento que ninguém documentou, valores que vivem fora do repositório, decisões que o time precisa confirmar. É exatamente o tipo de ambiguidade que eu gosto de encontrar antes, e não durante, um incidente.

O PR no Mermaid, e por que eu fechei

O objetivo original era ter BPMN nativo no Mermaid, para os diagramas renderizarem direto no GitHub. Implementei um tipo de diagrama bpmn com a camada que chamo de AI-first - gramática tolerante, erros que sugerem a correção, uma especificação pronta para colar num prompt - e um export para BPMN 2.0 XML. Abri como draft no repositório oficial (mermaid-js/mermaid#8313).

Aí o Filip Sajdak comentou. Ele vinha construindo o bpmn-beta havia semanas, numa série de PRs mais completa do que a minha em quase tudo: swimlanes com pools e lanes de verdade, boundary events, subprocessos. Os dois PRs colidiam, e só um entraria sem retrabalho. A parte que ele não tinha era justamente a minha: o export XML e a camada AI-first.

Competir não fazia sentido. Levei a camada AI-first para cima do trabalho dele, num PR no fork dele, e fechei o meu. Ele preferiu segurar o PR até os mantenedores definirem a direção do BPMN no Mermaid, com algumas decisões de desenho que mudam o que eu fiz - e está certo: é o trabalho dele e a gramática dele. O export XML ficou oferecido para a etapa em que o projeto decidir onde ele deve morar (discussão na #2623).

É a mesma lição de sempre, agora em open source: otimizar o sistema, não a minha parte dele.

Construído em público

Publiquei a skill e comentei no X. Duas respostas viraram funcionalidade no mesmo dia. Uma crítica apontou que várias regras de estilo estavam só no texto da skill, e não no código - virou o lint automático. Uma pergunta foi se a skill gera o mapa inteiro de novo a cada execução ou só o que mudou - virou o modo incremental: cada mapa registra o commit de origem, e na execução seguinte só os diagramas afetados pela mudança são refeitos, com os mesmos ids, para o diff mostrar só o que mudou de verdade.

Como usar

A skill é open source (MIT) e instala como plugin do Claude Code:

claude plugin marketplace add rwspatin/bpmn-skill
claude plugin install bpmn-mapper@rwspatin

Depois, dentro de um repositório, algo como: "Use a skill bpmn-mapper para mapear o fluxo de pedido deste serviço em BPMN."

Onde tenho visto mais valor:

• PRDs: mapear o que existe primeiro e planejar a mudança sobre o mesmo diagrama, para a discussão ser sobre o fluxo e não sobre um parágrafo;
• onboarding: entender um sistema pelo processo antes de entender pelas pastas;
• auditoria e revisão: ver onde as regras estão, e onde deveriam estar e não estão.

Duas ressalvas honestas. A sintaxe ainda não está no Mermaid oficial (hoje ela vive no meu fork), então o GitHub não renderiza o bloco bpmn. Por enquanto, commite o SVG e o .bpmn. E o diagrama é uma reconstrução feita por IA: o validador garante a estrutura, não que o processo esteja certo. A revisão humana continua sendo parte do método.

Repositório, documentação e exemplos: github.com/rwspatin/bpmn-skill.

• Renan