hellices/flow-atlas

O que flow-atlas faz?

O próprio AGENTS.md do repositório, os documentos de design e os testes de governança têm precedência sobre esta skill.

Três partes

O atlas gera o que o código estabelece. Você escreve o que precisa de intenção, e o atlas verifica. Entre os dois, você interpreta qual trabalho pertence a qual componente, com os critérios em references/boundaries.md. Tudo que você decide vai para um arquivo que o atlas lê (arquivos de fluxo, o arquivo de exceções, a configuração, feedback), para que a próxima execução e o próximo agente vejam.

O atlas gera: nunca escreva estes manualmente

Fato	Comando
superfícies, chamadas, arestas, operationIds, registros, versões de contrato	scan
superfícies e chamadas por caminho, método ou componente	query
os chamadores upstream de uma superfície e os serviços que ela alcança downstream	trace
um rascunho de Fluxo: nome, passos ao longo do caminho do código, entrada quando um componente o chama, candidatos onde ele ramifica	draft flow
se um Fluxo se mantém no código, e se seus campos de autor estão escritos	flows (condições)
descobertas com localizações e caminhos próximos	check, explain
o que mudou entre revisões	diff
candidatos de configuração e quanto a configuração cobre	inventory, scan
as descrições OpenAPI de cada componente, o quanto as descrições comprometidas concordam com o código, e qual é a do componente quando o código decide	scan, inventory

Não use grep em graph.json, não adivinhe chamadores a partir de busca textual, nem digite ids de superfície de memória: copie-os da saída do atlas.

Você escreve: o atlas verifica

O quê	Verificado por
o title de um Fluxo e o role de cada passo	Documented
owner, labels, sources, lifecycle (planejado quando um passo não está construído)	schema; Resolved conta passos planejados separadamente
generated: { by: <ferramenta>/<modelo>, at } depois que você escreveu a intenção de um fluxo; stale_after quando ele deve ser revisado (OKF)	schema; Fresh
o componente de entrada quando vários chamam o primeiro passo; o próximo passo onde o manipulador ramifica	EntryCalled, Connected
produces	ProducesListed
exceções: motivo, decidedBy, reviewBy	expiração traz a descoberta de volta
falsos positivos, com o porquê	stats
a configuração	cobertura do scan
o documento OpenAPI que o framework gera, para um componente que o atlas não consegue analisar (routes[].openapi, references/openapi.md)	cobertura do scan e linhas limit:
origins: a URL base na qual cada componente executa em um ambiente, a partir dos arquivos de implantação	export arazzo nota um ausente
openapi.<componente> quando o atlas relata sua descrição como ambiguous	export arazzo recusa até que esteja definido

Não entregue sua parte à ferramenta: nenhuma atualização de publicSurfaces, exceção ou linha de base sem um motivo que uma pessoa aceitaria. Nunca escreva uma entrada verified com um ator human:: isso registra a revisão de uma pessoa, e o nível de confiança do fluxo (unverified, machine-confirmed, human-reviewed) depende disso.

Você interpreta: limites

Se um salto pertence ao componente em que está, se uma superfície similar já faz o trabalho, se uma lacuna é um defeito, um plano ou um falso positivo, o quanto confiar em uma aresta, e onde um fluxo começa e termina. Siga references/boundaries.md; ele ordena as fontes (regras do repositório, depois papéis do fluxo, depois código) e fornece os critérios.

Configuração

• Execute atlas --help. Se atlas não estiver instalado, execute-o através do npx (npx github:hellices/flow-atlas --help) ou peça ao usuário para instalá-lo; não reimplemente suas leituras manualmente.
• A configuração é <raiz>/atlas.config.yaml, <saida>/atlas.config.yaml, ou --config <arquivo>. Se não houver nenhuma, siga "Configurando" abaixo.
• Se o repositório não deve ser modificado, passe --out <diretório fora dele>. Toda escrita vai para lá.

Projetando uma mudança

1. atlas query --path <caminho ou fragmento> e atlas query --component <nome> para ver o que já existe.
2. atlas trace <superfície mais próxima> para ver a cadeia: chamada do cliente, rota do BFF, os métodos de porta que seu manipulador alcança, a rota de serviço que cada um corresponde.
3. Decida: reutilizar, estender ou adicionar. Anote as chaves de superfície que você adicionará ou alterará e qual componente possui cada salto. Se dois componentes acabariam fazendo o mesmo passo, resolva isso antes de escrever código.
4. Se o repositório mantém fluxos (flows/*.flow.yaml), atualize o Fluxo, ou inicie um novo com atlas draft flow <surface> (veja "Escrevendo um fluxo"). Marque passos que ainda não existem com lifecycle: planned.

Enquanto implementa

Depois de adicionar uma rota ou uma chamada de cliente, execute atlas trace <surface>. O upstream deve mostrar o chamador que você pretendia e o downstream as chamadas que você pretendia. Um lado vazio significa que ou não está conectado ainda, ou está conectado de uma forma que a ferramenta não consegue ler (um caminho construído longe da chamada, um manipulador em outra linguagem); abra o código e diga qual.

Quando você adiciona, remove ou altera uma rota de um componente cujas rotas vêm de um documento OpenAPI gerado, regenere o documento na mesma alteração. Uma chamada de cliente sozinha não o altera.

Escrevendo um fluxo

1. atlas draft flow <primeira superfície> imprime um Fluxo com tudo que o código estabelece; adicione --to <surface> para seguir o código até um determinado fim. Salve-o em flows/<nome>.flow.yaml (ou <out>/flows/ para um repositório que você não pode alterar).
2. Preencha todo comentário agent:: title, role de cada passo (o que o componente faz e deixa para outros), owner, lifecycle, produces; escolha a entrada e os próximos passos onde o rascunho lista candidatos. Mantenha os valores sem marcador; eles vêm do código.
3. atlas flows até que o fluxo esteja Ready=True. Um Resolved, Connected ou EntryCalled falso significa que o código ou o fluxo está errado: decida qual com references/boundaries.md. Um Documented falso significa que um campo de autor está vazio.

Um arquivo pode conter vários fluxos separados por ---. Ids de superfície escrevem parâmetros de caminho como modelos OpenAPI ({id}). Não copie localizações, arestas ou condições para dentro do arquivo; o atlas os calcula a cada execução. O formato é schema/flow.schema.json no pacote flow-atlas, cujos docs/schema.md e docs/responsibilities.md o explicam.

Antes de finalizar

1. atlas check --since <revisão a partir da qual você começou>. Apenas descobertas introduzidas pela sua alteração aparecem.
2. Para cada uma: atlas explain <chave> mostra as localizações e caminhos semelhantes. Então corrija-a, ou registre uma exceção, ou registre um falso positivo. Veja "Lidando com uma descoberta".
3. Coloque atlas diff <base>..WORKTREE --format markdown (ou <base>..HEAD) e o trace de cada nova superfície na descrição do PR ou na nota de passagem de trabalho.

Quando a configuração está desatualizada

Sinais: linhas limit: no stderr (arquivos configurados não correspondem a nada, uma fonte produz menos da metade de sua linha de base), ou FA001 em rotas que você sabe que são chamadas. Execute atlas inventory, compare com a configuração, corrija-a (references/config.md), e verifique a cobertura do atlas scan novamente. Pergunte a uma pessoa antes de atlas baseline update.

Configurando

atlas inventory lista candidatos sem decidir nada. Escreva a configuração a partir dele (references/config.md); para um framework de servidor que o atlas não analisa (Spring, Django, Flask e outros), gere seu documento OpenAPI e aponte as rotas para ele (references/openapi.md), execute atlas scan até que cada fonte produza o que você espera, execute atlas check, e revise uma amostra das descobertas com uma pessoa. Só então registre a linha de base.

Lidando com uma descoberta

Decida primeiro se é um defeito, um plano ou um falso positivo (references/boundaries.md), então:

• Corrija quando a descoberta é o bug: conecte o chamador ausente, remova a rota morta, adicione o produtor, aponte a chamada para o caminho servido. references/rules.md lista as causas usuais por regra.

• Quando o código está correto intencionalmente, adicione uma exceção que nomeie a decisão:

  # flows/atlas-exceptions.yaml (ou <out>/exceptions.yaml)
  - rule: FA001
    key: FA001|orders|GET /orders/{id}/history
    reason: O serviço é lançado primeiro; a tela do aplicativo segue no próximo release.
    decidedBy: docs/orders.md#history
    reviewBy: 2026-12-31
  

  Superfícies servidas a clientes fora do repositório vão para publicSurfaces na configuração.

• Quando a descoberta está errada: atlas feedback <chave> false-positive --note "<porquê>". Se o extrator leu um arquivo incorretamente, diga qual arquivo e como.

Nunca execute atlas baseline update a menos que uma pessoa peça. Nunca edite código gerado para satisfazer uma descoberta.

Saída legível por máquina

--format json ou --format yaml imprime documentos que seguem o schema/*.schema.json do pacote flow-atlas, cada um com apiVersion, kind e provenance (o commit e arquivos lidos, com digests). Leia estes em vez de analisar a saída de texto; decida baseado no reason de uma condição, não em sua message. atlas check --format sarif fornece as descobertas como SARIF 2.1.0 para varredura de código e visualizadores de IDE; atlas export arazzo fornece os fluxos como Arazzo 1.0 para fluxo de trabalho de API e ferramentas e2e, que ainda precisam de parâmetros, corpos de requisição e critérios de sucesso preenchidos.

Lendo a saída

• Status da descoberta: new é sua; baseline é dívida aceita; excepted está coberta; expired-exception precisa de uma pessoa.
• Em um trace, = junta uma chamada a uma superfície por método e caminho; ~ junta uma rota a uma chamada de saída que seu manipulador executa: escrita no próprio código do manipulador ou nas funções que ele chama (evidência static), ou mantida em um método de um nome que o manipulador chama (evidência name), ou, para uma página Spring, feita pelo template que seu nome de view renderiza (via view <nome>). Um ~ por nome através de um nome genérico (get, send) precisa de uma olhada no código.
• O in <nome> de uma chamada é a função que contém a string. Uma string em um rótulo de erro ou uma mensagem de log não é uma requisição mesmo que pareça um caminho; o escopo geralmente mostra isso.
• Apenas arquivos configurados são lidos, e neles apenas o que é escrito com certeza: caminhos literais, com o significado que um padrão ou o framework lhes dá. Uma URL de uma variável, outro mecanismo de template, ou atributos htmx e Vue não é lida nem adivinhada. Portanto, "sem chamador" significa nenhum que o atlas possa ler; verifique o código antes de remover qualquer coisa, e declare superfícies servidas fora do repositório em publicSurfaces. Nenhuma descoberta não prova que um fluxo está completo.

Referências

• Interpretando limites, decidindo defeito, plano ou falso positivo: references/boundaries.md
• Regras, causas, resoluções, quando uma exceção se encaixa: references/rules.md
• Escrevendo ou corrigindo a configuração: references/config.md
• Lendo rotas a partir do documento OpenAPI gerado por um framework, e como gerá-lo: references/openapi.md