/understand-domain

Extrai conhecimento do domínio de negócios — domínios, fluxos de negócios e etapas de processo — de uma base de código e produz um gráfico de fluxo horizontal interativo no painel.

Como Funciona

• Se um grafo de conhecimento já existir (.ua/knowledge-graph.json, ou o legado .understand-anything/knowledge-graph.json quando esse diretório estiver presente), deriva o conhecimento do domínio dele (barato, sem varredura de arquivos)
• Se nenhum grafo de conhecimento existir, realiza uma varredura leve: árvore de arquivos + detecção de ponto de entrada + arquivos amostrados
• Use o sinalizador --full para forçar uma nova varredura, mesmo que um grafo de conhecimento exista

Instruções

Fase 0: Resolver PROJECT_ROOT

Defina PROJECT_ROOT para o diretório de trabalho atual.

Redirecionamento de Worktree. Se PROJECT_ROOT estiver dentro de um worktree git (não o checkout principal), redirecione a saída para a raiz do repositório principal. Worktrees gerenciados pelo Claude Code são efêmeros — o diretório de dados (.ua/, ou o legado .understand-anything/) gravado lá é destruído quando a sessão termina, levando o grafo de domínio com ele (issue #133). Detecte um worktree comparando git rev-parse --git-dir com git rev-parse --git-common-dir; em um checkout normal ou submódulo, eles se resolvem para o mesmo caminho, em um worktree eles diferem e o pai de --git-common-dir é a raiz do repositório principal.

COMMON_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)
GIT_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-dir 2>/dev/null)
if [ -n "$COMMON_DIR" ] && [ -n "$GIT_DIR" ]; then
  COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" 2>/dev/null && pwd -P)
  GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR" 2>/dev/null && pwd -P)
  if [ -n "$COMMON_ABS" ] && [ "$COMMON_ABS" != "$GIT_ABS" ]; then
    MAIN_ROOT=$(dirname "$COMMON_ABS")
    if [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]; then
      echo "[understand-domain] Detected git worktree at $PROJECT_ROOT"
      echo "[understand-domain] Redirecting output to main repo root: $MAIN_ROOT"
      echo "[understand-domain] (Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to keep PROJECT_ROOT as the worktree.)"
      PROJECT_ROOT="$MAIN_ROOT"
    fi
  fi
fi

Use $PROJECT_ROOT (não o CWD nu) para cada referência a "o projeto atual" / <project-root> nas fases subsequentes.

Resolver o diretório de dados $UA_DIR. Todos os artefatos do Understand-Anything vivem no diretório de dados do projeto. Resolva-o uma vez, agora que $PROJECT_ROOT é conhecido, e reutilize $UA_DIR para cada leitura e escrita nas fases posteriores:

UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)"

Isso mantém o diretório legado .understand-anything/ quando ele já existe (projetos existentes continuam funcionando sem migração) e usa o novo .ua/ caso contrário. Como cada fase pode ser executada em um shell novo, leve $UA_DIR adiante como $PROJECT_ROOT, resolvendo-o novamente com a linha acima se um bloco de comando posterior precisar dele.

Importante: não assuma que a raiz do plugin é simplesmente dois diretórios acima da string do caminho da skill. Em muitas instalações, ~/.agents/skills/understand-domain é um link simbólico para o checkout real do plugin. Prefira raízes de plugin fornecidas em tempo de execução primeiro (para Claude), depois recorra a links simbólicos universais, resolução de links simbólicos de skill e caminhos de instalação comuns baseados em clone.

Resolva a raiz do plugin assim:

SKILL_REAL=$(realpath ~/.agents/skills/understand-domain 2>/dev/null || readlink -f ~/.agents/skills/understand-domain 2>/dev/null || echo "")
SELF_RELATIVE=$([ -n "$SKILL_REAL" ] && cd "$SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
COPILOT_SKILL_REAL=$(realpath ~/.copilot/skills/understand-domain 2>/dev/null || readlink -f ~/.copilot/skills/understand-domain 2>/dev/null || echo "")
COPILOT_SELF_RELATIVE=$([ -n "$COPILOT_SKILL_REAL" ] && cd "$COPILOT_SKILL_REAL/../.." 2>/dev/null && pwd || echo "")

PLUGIN_ROOT=""
for candidate in \
  "${CLAUDE_PLUGIN_ROOT}" \
  "$HOME/.understand-anything-plugin" \
  "$SELF_RELATIVE" \
  "$COPILOT_SELF_RELATIVE" \
  "$HOME/.codex/understand-anything/understand-anything-plugin" \
  "$HOME/.opencode/understand-anything/understand-anything-plugin" \
  "$HOME/.pi/understand-anything/understand-anything-plugin" \
  "$HOME/understand-anything/understand-anything-plugin"; do
  if [ -n "$candidate" ] && [ -f "$candidate/package.json" ] && [ -f "$candidate/pnpm-workspace.yaml" ]; then
    PLUGIN_ROOT="$candidate"
    break
  fi
done

if [ -z "$PLUGIN_ROOT" ]; then

…