Unfold

O que Unfold faz?

Produz uma única página HTML autocontida: uma visão geral que se desdobra, nível por nível, nas partes de um sistema. O motor (assets/template.html) desenha, organiza, aplica zoom, rastreia e edita. Seu trabalho é entender o código e escrever os dados do diagrama (JSON), para que um leitor que não sabe nada sobre o projeto seja capaz de explicá-lo.

Em cada nível, a página responde a três perguntas: o que entra, o que acontece com isso, o que sai.

Padrão de qualidade

• Preciso. Cada nó e aresta é respaldado por código que você realmente examinou. Seu source indica onde: caminho/arquivo.py:símbolo. Marque confiança em cada nó: lido, visto ou inferido. Qualquer item inferido é listado ao usuário.
• Adequado à base de código. Use o vocabulário próprio do projeto (nomes de módulos, nomes de tópicos e rotas literalmente) e o tipo de diagrama que se ajusta a cada parte (veja a etapa 4).
• Discreto. Rótulos têm 2 a 4 palavras, legendas uma linha, notas 1 a 3 frases, e nada mais. Os detalhes ficam a um clique ou a um hover de distância, nunca na tela.
• Navegável do zero. meta.summary diz para que serve o sistema em uma frase. Um breve meta.glossary define o jargão do projeto. As notas abrem com uma frase que funciona como dica de hover.

Fluxo de trabalho

1. Enquadre a solicitação

A intenção vem primeiro: para que serve o mapa. Ela define o escopo, a profundidade, os tipos de nível, o tour, a mídia e o glossário; references/intents.md contém os padrões para cada intenção.

• Não pergunte quando o prompt já disser. "Explique-me este projeto" significa aprender. "Como funciona a lógica de retry?" significa explicar. "O que esta PR muda?" significa revisar. "Vou apresentar isso na sexta" significa demonstrar.
• Caso contrário, faça uma pergunta antes de escanear, com estas opções: Aprender a base de código, Demonstrar meu trabalho, Explicar um detalhe específico, Revisar uma mudança ou Outro (documentar ou entregar, depurar um caminho, planejar uma refatoração, auditar fluxo de dados).
• Depois, faça no máximo duas perguntas complementares, escolhidas para aquela intenção em references/intents.md. Pule qualquer uma que a conversa já tenha respondido.
• Registre a resposta como meta.intent e meta.audience. Ao estender uma página existente, reutilize seu meta.intent em vez de perguntar novamente.

Em seguida, a partir da conversa ou no mesmo lote curto, estabeleça:

• scope: qual repositório ou parte dele;
• audience: novo desenvolvedor, revisor, gerente ou apresentação;
• focus: a parte que mais importa, que receberá mais profundidade;
• confidentiality: as páginas são compartilhadas, portanto omita hosts, segredos, nomes de clientes e planos não lançados, a menos que seja instruído de outra forma.

Se não houver código, trabalhe a partir da descrição do usuário. Nunca invente partes, fluxos ou números.

2. Leia a base de código em etapas, dentro de um orçamento

Repositórios grandes não cabem no contexto, e ler arquivos inteiros superficialmente desperdiça esse recurso. Leia em etapas e pare assim que o diagrama estiver fundamentado.

Etapa	Comando	O que você obtém	Custo
Mapa	python scripts/scan_repo.py REPO [--section NOME]	linguagens, estrutura, manifestos, pontos de entrada, sinais de E/S com arquivo:linha, importações entre partes, uma lista leia estes primeiro	pequeno, limitado por --budget
Contorno	python scripts/scan_repo.py REPO --outline [PREFIXO]	cada classe e função, com assinatura e primeira linha do docstring, sem corpos	médio, limitado por --budget
Evidência	python scripts/peek.py REPO arquivo:linha arquivo:símbolo ...	apenas as linhas ao redor de cada referência, mescladas, dentro de um orçamento fixo de linhas e tokens	pequeno por chamada
Profundidade	ler arquivos inteiros	apenas os 3 a 8 arquivos que carregam a lógica central na área de foco do usuário	grande

Como trabalhar com as etapas:

• Comece com o README, a documentação e o Mapa.
• Use o Contorno nas pastas que importam. Para um repositório grande, execute-o por parte de alto nível, e não em tudo.
• Use peek para cada sinal de E/S e ponto de entrada que você planeja desenhar, e para a função por trás de cada nível de processo.
• Leia arquivos inteiros apenas onde a lógica for genuinamente intrincada.
• Mantenha uma lista de evidências em execução (nó → arquivo:símbolo). Ela se tornará os campos source.
• O escaneamento é baseado em regex: ele perde ligações dinâmicas e relata alguns falsos positivos, como padrões dentro de strings. Confirme com peek antes de desenhar.

Orçamento de tokens. Cada comando termina com seu custo (≈N tokens). Gaste apenas o que o mapa precisa:

• Nunca leia um arquivo inteiro antes de seu contorno. Use peek em arquivo:símbolo, não em intervalos amplos de linhas, e agrupe referências em uma única chamada peek.
• Uma lista cortada termina com … N mais; execute novamente com --section X. Busque-a apenas se o diagrama precisar. Em um repositório grande, contorne uma parte de cada vez com --outline PREFIXO.
• Pare de ler assim que cada nó que você planeja desenhar tiver um source.
• Verifique com unfold.py check e outline; não releia o JSON ou a página. Corrija diagram.json com pequenas edições; nunca o reimprima inteiro.

Custos, o cache de escaneamento e o que é ignorado: references/reading-code.md (Orçamento de tokens).

3. Fixe o limite do sistema

Liste as entradas (requisições, tópicos inscritos, argumentos de CLI, arquivos lidos, sensores, configuração) e as saídas (respostas, tópicos publicados, arquivos escritos, comandos, escritas em banco). Marque-as com "role": "input" ou "role": "output" em todos os níveis de arquitetura e processo.

4. Escolha o diagrama para cada nível

A visão geral é sempre architecture: 4 a 10 partes, armazenamentos e externos, com entradas à esquerda e saídas à direita. Cada parte que vale a pena abrir recebe o tipo filho que seu código pede:

O código interno é…	type	Desenhe
Várias partes que se chamam ou se enviam mensagens	architecture	partes rounded, armazenamentos cylinder, externos cloud
Uma sequência de etapas sobre uma entrada: um handler, pipeline, job ou algoritmo	process	início/fim pill, etapas rect, decisões diamond com ramos rotulados, laços de volta tracejados
Uma interação entre partes ao longo do tempo: um ciclo de vida de requisição, handshake, objetivo de ação	sequence	participantes como nós, da esquerda para a direita; mensagens como arestas em ordem; tracejado para retornos
Comportamento orientado por estados e eventos: uma máquina de estados, gerenciador de modos, conexão, status de árvore de comportamento	state	marcadores initial e final, estados pill, arestas rotuladas com o evento ou guarda
Estruturas de dados, esquemas, modelos ORM, definições de mensagens	data	nós table com fields ("id: int PK"), arestas rotuladas com cardinalidade
Classes e suas relações: um modelo de objeto, hierarquia de plugins	class	nós class com fields e methods; arestas com rel (inherits, implements, composition, …)
O sistema em seu mundo: usuários, sistemas vizinhos, a tecnologia de cada contêiner	c4	person para pessoas, partes com tech, externos cloud, grupos como limites
O que executa onde: hosts, dispositivos, clusters, contêineres	deployment	máquinas node3d, grupos para ambientes, tech em cada um
Importações de módulos ou pacotes	dependency	módulos rect, arestas do importador para o importado
Uma árvore de comportamento (py_trees, BehaviorTree.CPP, Nav2)	behaviour	nós com bt (sequence, selector, parallel, decorator, action, condition); arestas pai → filho em ordem de execução
Uma hierarquia: árvore de configuração, menu, docs, tópicos	tree	arestas pai → filho, em ordem
Versões, migrações, ordem de inicialização ou startup	timeline	nós em ordem com uma date cada um

Vá mais fundo onde o código vai, e pare onde uma nota seria suficiente. Abra uma parte apenas se seu interior tiver 3 ou mais elementos significativos. Mantenha cada nível com cerca de 12 nós; acima disso, aninhe. references/reading-code.md contém padrões para serviços web, ROS 2, pipelines, CLIs, firmware, frontends e monorepos.

5. Adicione recursos visuais onde o código os tiver

Se o repositório contiver capturas de tela, imagens de arquitetura, GIFs de demonstração ou vídeos (procure em docs/, assets/ e no README), anexe-os com "media": {"src": "caminho/relativo.png", "caption": "…"}, ou uma lista deles para dar a uma parte vários. Qualquer nó com mídia mostra um emblema de miniatura e abre um visualizador; um nó com "shape": "image" mostra a imagem na tela. Para demonstrate, peça ao usuário capturas de tela das partes que você mostra.

unfold.py build incorpora arquivos locais. Páginas publicadas no claude.ai bloqueiam imagens remotas, portanto prefira arquivos locais.

6. Escreva as palavras

• meta.summary: uma frase sobre o que o sistema faz para quem.
• meta.glossary: até 8 termos do projeto, cada um com uma definição de 10 palavras ou menos.
• caption por nível: uma linha sobre o propósito, ex.: "Cada objetivo é verificado quanto à alcançabilidade antes de o braço se mover".
• note em um nó: sua primeira frase é mostrada ao passar o mouse, portanto ela deve fazer sentido sozinha; até duas frases adicionais vão no cartão de detalhes.
• Rótulos de arestas: o que flui, em 1 a 3 palavras.

7. Escreva um tour

Para learn e demonstrate (e sempre que o mapa tiver mais de dois níveis), adicione uma entrada meta.tours: 5 a 9 etapas na ordem em que um desenvolvedor explicaria, das entradas para as saídas. Cada etapa nomeia um path (os ids dos nós a serem abertos, da visão geral para baixo) e opcionalmente um node a ser destacado, com um title e uma ou duas frases de text. Para demonstrate, adicione notes para o apresentador. Para learn, termine com uma etapa quiz ({"q", "answer": id do nó, "explain"}). A página também gera um tour quando nenhum é escrito, portanto pule isso para um mapa pequeno de nível único.

8. Verifique, revise, construa

python scripts/unfold.py check   diagram.json     # erros falham; leia cada aviso
python scripts/unfold.py outline diagram.json     # a árvore inteira em uma tela
python scripts/unfold.py drift   diagram.json --repo REPO   # cada fonte ainda resolve
python scripts/unfold.py build   diagram.json page.html --repo REPO   # fixa meta.repo no commit

Mantenha uma cópia do que você gerou como diagram.generated.json ao lado de diagram.json; o remapeamento precisa dela.

Leia o contorno como se fosse o recém-chegado:

• Você consegue explicar o sistema a partir dele?
• Cada nível responde a entrada → processo → saída?
• Cada filho é do tipo correto?

Se a automação de navegador, como Playwright, estiver disponível, capture a tela da visão geral e de um nível interno de cada tipo e corrija sobreposições ou cruzamentos.

9. Entregue

No claude.ai com a ferramenta Artifact, publique page.html de /mnt/user-data/outputs/ com capabilities: {"artifact": {}, "downloads": true}, que habilita Salvar e Exportar. Em outros lugares, entregue o arquivo; ele funciona offline.

Em seguida, informe ao usuário, em poucas linhas:

• o que a visão geral mostra;
• quais partes são inferidas;
• como ler a página: clique para abrir, passe o mouse para rastrear, Esc ou diminuir o zoom para voltar, / para pesquisar, Tour ou T para o tour guiado, P para apresentar e Editar para alterar coisas;
• que Exportar fornece PNG, SVG, PDF, Mermaid, draw.io e Excalidraw, para slides, READMEs e outras ferramentas.

Se o usuário posteriormente editou a página, continue a partir de python scripts/unfold.py extract page.html diagram.json, e não da sua cópia antiga.

Para remapear após alterações no código, escaneie com --changed-since <meta.repo.commit>, atualize uma cópia de diagram.generated.json com os mesmos ids, então unfold.py merge no mapa editado para que edições manuais sobrevivam. Etapas: references/reading-code.md (Remapeamento).

Referência

• references/intents.md: o que cada intenção altera e suas perguntas complementares.
• references/schema.md: cada campo, tipo de nível, forma e cor.
• references/reading-code.md: transformar código em níveis, com padrões por ecossistema.
• Não altere assets/template.html para um diagrama. Mudanças no motor pertencem ao repositório, com testes.