/understand-explain

Forneça uma explicação completa e aprofundada de um componente de código específico.

Referência da Estrutura do Grafo

O JSON do grafo de conhecimento tem esta estrutura:

• project — {nome, descrição, linguagens, frameworks, analisadoEm, hashCommitGit}
• nodes[] — cada um tem {id, tipo, nome, caminhoArquivo?, resumo, tags[], complexidade, notasLinguagem?}
  • Tipos de nó de código: arquivo, função, classe, módulo, conceito
  • Tipos de nó que não são de código: configuração, documento, serviço, tabela, endpoint, pipeline, esquema, recurso
  • Tipos de nó de domínio/conhecimento: domínio, fluxo, etapa, artigo, entidade, tópico, alegação, fonte
  • IDs usam o tipo de nó como prefixo, por exemplo, file:path, function:path:name, config:path, article:path
• edges[] — cada um tem {origem, destino, tipo, direção, peso}
  • Tipos de chave: importa, contém, chama, depende_de, configura, documenta, implanta, aciona, contém_fluxo, etapa_fluxo, relacionado, cita
• layers[] — cada um tem {id, nome, descrição, idsNodos[]}
• tour[] — cada um tem {ordem, título, descrição, idsNodos[]}

Como Ler Eficientemente

1. Use Grep para pesquisar dentro do JSON por entradas relevantes ANTES de ler o arquivo completo
2. Leia apenas as seções de que você precisa — não despeje o grafo inteiro no contexto
3. Nomes de nós e resumos são os campos mais úteis para a compreensão
4. As arestas mostram como os componentes se conectam — siga imports e calls para cadeias de dependência

Instruções

1. Resolva o diretório de dados $UA_DIR. Execute UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua) — este é o .understand-anything/ legado se ele já existir, caso contrário, o novo .ua/. Verifique se $UA_DIR/knowledge-graph.json existe. Se não, diga ao usuário para executar /understand primeiro.

2. Verifique a atualidade do grafo antes de usar o contexto derivado do grafo:

   • Leia project.gitCommitHash dos metadados do grafo como GRAPH_COMMIT_RAW. Resolva-o como um commit antes de usá-lo em qualquer diff do Git, em seguida, compare-o com git rev-parse HEAD e inspecione as alterações confirmadas e da árvore de trabalho com escopo de projeto a partir da raiz do projeto:

     GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
     git rev-parse HEAD
     git diff --name-only "$GRAPH_COMMIT" HEAD -- .
     git diff --cached --name-only -- .
     git diff --name-only -- .
     git ls-files --others --exclude-standard -- .
     

   • O pathspec -- . é necessário: commits que tocam apenas um projeto monorepo irmão não devem tornar este grafo obsoleto. Uma incompatibilidade de hash por si só não é obsoleta quando o diff do projeto está vazio.
   • Ignore o diretório de dados selecionado (.ua/ ou o .understand-anything/ legado) em cada saída de comando porque ele contém artefatos de grafo gerados, não desvios de origem do projeto.
   • Se o diff confirmado ou qualquer comando da árvore de trabalho relatar arquivos do projeto, avise antes de explicar que o contexto derivado do grafo pode omitir essas alterações. Sugira: Execute /understand para atualizar o grafo.
   • Execute o diff do commit apenas quando GRAPH_COMMIT_RAW for resolvido com sucesso. Se o commit do grafo ou os metadados do Git estiverem ausentes, inválidos ou indisponíveis, forneça um breve aviso de melhor esforço e continue em vez de bloquear.

3. Encontre o nó de destino — use Grep para pesquisar no grafo de conhecimento o componente: "$ARGUMENTS"

   • Para caminhos de arquivo (por exemplo, src/auth/login.ts): pesquise por correspondências de "filePath"
   • Para notação de função (por exemplo, src/auth/login.ts:verifyToken): pesquise o nome da função em campos "name" filtrados pelo caminho do arquivo
   • Observe o id, type, summary, tags e complexity exatos do nó

4. Encontre todas as arestas conectadas — Pesquise com Grep o ID do nó de destino na seção de arestas:

   • Correspondências de "source" → coisas que este nó chama/importa/depende (saindo)
   • Correspondências de "target" → coisas que chamam/importam/dependem deste nó (entrando)
   • Observe os IDs dos nós conectados e os tipos de arestas

5. Leia os nós conectados — para cada ID de nó conectado da etapa 4, pesquise com Grep esses IDs na seção de nós para obter seu name, summary e type. Isso constrói o vizinhança do componente.

6. Identifique a camada — Pesquise com Grep o ID do nó de destino na seção "layers" para encontrar a qual camada arquitetônica ele pertence e a descrição dessa camada.

7. Leia o arquivo de origem real — Leia o arquivo de origem no filePath do nó para a análise aprofundada.

8. Explique o componente em contexto:

   • Seu papel na arquitetura (qual camada, por que existe)

…