/understand-chat

Responda perguntas sobre esta base de código usando o grafo de conhecimento no diretório de dados do projeto (.ua/knowledge-graph.json, ou o legado .understand-anything/knowledge-graph.json quando esse diretório estiver presente).

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: config, 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, idsNós[]}
• tour[] — cada um tem {ordem, título, descrição, idsNós[]}

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 compreensão
4. Arestas mostram como os componentes se conectam — siga importações e chamadas 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 legado .understand-anything/ quando ele já existe, caso contrário, o novo .ua/. Verifique se $UA_DIR/knowledge-graph.json existe na raiz do projeto atual. 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 na árvore de trabalho do escopo do 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 apenas tocam um projeto monorepo irmão não devem tornar este grafo obsoleto. Uma incompatibilidade de hash sozinha não é obsoleta quando o diff do projeto está vazio.
   • Ignore o diretório de dados selecionado (.ua/ ou o legado .understand-anything/) em cada saída de comando, pois 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 responder 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. Leia apenas os metadados do projeto — use Grep ou Read com um limite de linhas para extrair apenas a seção "project" do topo do arquivo para contexto (nome, descrição, linguagens, frameworks).

4. Procure por nós relevantes — use Grep para pesquisar o arquivo do grafo de conhecimento pelas palavras-chave da consulta do usuário: "$ARGUMENTS"

   • Pesquise os campos "name": grep -i "query_keyword" no arquivo do grafo
   • Pesquise os campos "summary" por correspondências semânticas
   • Pesquise os arrays "tags" por correspondências de tópicos
   • Anote os valores id de todos os nós correspondentes

5. Encontre arestas conectadas — para cada ID de nó correspondente, use Grep para procurar esse ID na seção edges para encontrar:

   • O que ele importa ou depende (downstream)
   • O que o chama ou o importa (upstream)
   • Isso lhe dá o subgrafo de 1 salto em torno da consulta

6. Leia o contexto da camada — use Grep para "layers" para entender a quais camadas arquitetônicas os nós correspondentes pertencem.

7. Responda à consulta usando apenas o subgrafo relevante:

   • Referencie arquivos, funções e relacionamentos específicos do grafo
   • Explique quais camadas são relevantes e por quê
   • Seja conciso, mas completo — vincule conceitos a locais de código reais

…