/understand-onboard

Gere um guia de integração abrangente a partir do grafo de conhecimento do projeto.

Referência da Estrutura do Grafo

O JSON do grafo de conhecimento tem esta estrutura:

• project — {nome, descrição, linguagens, frameworks, analisadoEm, hashDoCommitGit}
• nodes[] — cada um tem {id, tipo, nome, filePath?, resumo, tags[], complexidade, languageNotes?}
  • Tipos de nó de código: arquivo, função, classe, módulo, conceito
  • Tipos de nó não-código: config, documento, serviço, tabela, endpoint, pipeline, schema, 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 {fonte, alvo, tipo, direção, peso}
  • Tipos de chave: imports, contains, calls, depends_on, configures, documents, deploys, triggers, contains_flow, flow_step, related, cites
• layers[] — cada um tem {id, nome, descrição, nodeIds[]}
• tour[] — cada um tem {ordem, título, descrição, nodeIds[]}

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 afetam 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 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 gerar o guia que o conteúdo de integração pode omitir essas alterações. Sugestão: 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 os metadados do projeto — use Grep ou Read com um limite de linha para extrair a seção "project" (nome, descrição, linguagens, frameworks).

4. Leia as camadas — Grep por "layers" para obter o array completo de camadas. Estas definem a arquitetura e estruturarão o guia.

5. Leia o tour — Grep por "tour" para obter as etapas do roteiro guiado. Estas fornecem o caminho de aprendizado recomendado.

6. Leia apenas nós estruturais em nível de arquivo — use Grep para encontrar nós com tipos em nível de arquivo (file, config, document, service, pipeline, table, schema, resource, endpoint) no grafo de conhecimento. Pule nós em nível de função e classe para manter o guia de alto nível. Extraia o name, filePath, summary e complexity de cada nó.

7. Identifique pontos de complexidade — a partir dos nós em nível de arquivo, encontre aqueles com os maiores valores de complexity. Estas são áreas que os novos desenvolvedores devem abordar com cuidado.

8. Gere o guia de integração com estas seções:

   • Visão Geral do Projeto: nome, linguagens, frameworks, descrição (dos metadados do projeto)
   • Camadas de Arquitetura: nome, descrição e arquivos-chave de cada camada (das camadas + nós de arquivo)
   • Conceitos-Chave: padrões importantes e decisões de design (dos resumos e tags dos nós)

…