understand-domain

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/understand-domain

Extracts business domain knowledge — domains, business flows, and process steps — from a codebase and produces an interactive horizontal flow graph in the dashboard.

从代码库中提取业务领域知识——包括领域、业务流程和步骤——并在仪表盘中生成交互式水平流程图。

How It Works

工作原理

If a knowledge graph already exists (
```
.understand-anything/knowledge-graph.json
```
), derives domain knowledge from it (cheap, no file scanning)
If no knowledge graph exists, performs a lightweight scan: file tree + entry point detection + sampled files
Use
```
--full
```
flag to force a fresh scan even if a knowledge graph exists

若已存在知识图谱（
```
.understand-anything/knowledge-graph.json
```
），则从中推导领域知识（成本低，无需扫描文件）
若不存在知识图谱，则执行轻量扫描：文件树 + 入口点检测 + 采样文件
使用
```
--full
```
标志可强制重新扫描，即使已有知识图谱存在

Instructions

操作步骤

Phase 0: Resolve

PROJECT_ROOT

阶段0：解析

PROJECT_ROOT

Set

PROJECT_ROOT

to the current working directory.

Worktree redirect. If

PROJECT_ROOT

is inside a git worktree (not the main checkout), redirect output to the main repository root. Worktrees managed by Claude Code are ephemeral —

.understand-anything/

written there is destroyed when the session ends, taking the domain graph with it (issue #133). Detect a worktree by comparing

git rev-parse --git-dir

against

git rev-parse --git-common-dir

; in a normal checkout or submodule they resolve to the same path, in a worktree they differ and the parent of

--git-common-dir

is the main repo root.

bash

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

(not the bare CWD) for every reference to "the current project" /

<project-root>

in subsequent phases.

Important: do not assume the plugin root is simply two directories above the skill path string. In many installations

~/.agents/skills/understand-domain

is a symlink into the real plugin checkout. Prefer runtime-provided plugin roots first (for Claude), then fall back to universal symlinks, skill symlink resolution, and common clone-based install paths.

Resolve the plugin root like this:

bash

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
  echo "Error: Cannot find the understand-anything plugin root."
  echo "Checked:"
  echo "  - ${CLAUDE_PLUGIN_ROOT:-<unset CLAUDE_PLUGIN_ROOT>}"
  echo "  - $HOME/.understand-anything-plugin"
  echo "  - ${SELF_RELATIVE:-<unresolved path derived from ~/.agents/skills/understand-domain>}"
  echo "  - ${COPILOT_SELF_RELATIVE:-<unresolved path derived from ~/.copilot/skills/understand-domain>}"
  echo "  - $HOME/.codex/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.opencode/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.pi/understand-anything/understand-anything-plugin"
  echo "  - $HOME/understand-anything/understand-anything-plugin"
  echo "Make sure the plugin is installed correctly."
  exit 1
fi

Use

$PLUGIN_ROOT

for every reference to agent definitions in subsequent phases.

将

PROJECT_ROOT

设置为当前工作目录。

工作树重定向。如果

PROJECT_ROOT

位于git工作树内（而非主检出目录），则将输出重定向到主仓库根目录。Claude Code管理的工作树是临时的——写入其中的

.understand-anything/

会在会话结束时被销毁，领域图谱也会随之丢失（问题#133）。通过比较

git rev-parse --git-dir

与

git rev-parse --git-common-dir

来检测工作树；在普通检出或子模块中，两者路径相同，在工作树中则不同，且

--git-common-dir

bash

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

在后续阶段中，所有对「当前项目」/

<project-root>

的引用均使用

$PROJECT_ROOT

（而非当前裸CWD）。

重要提示：请勿假设插件根目录只是技能路径字符串上方的两个目录。在许多安装环境中，

~/.agents/skills/understand-domain

是指向真实插件检出目录的符号链接。优先使用运行时提供的插件根目录（针对Claude），然后依次回退到通用符号链接、技能符号链接解析和常见基于克隆的安装路径。

按如下方式解析插件根目录：

bash

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
  echo "Error: Cannot find the understand-anything plugin root."
  echo "Checked:"
  echo "  - ${CLAUDE_PLUGIN_ROOT:-<unset CLAUDE_PLUGIN_ROOT>}"
  echo "  - $HOME/.understand-anything-plugin"
  echo "  - ${SELF_RELATIVE:-<unresolved path derived from ~/.agents/skills/understand-domain>}"
  echo "  - ${COPILOT_SELF_RELATIVE:-<unresolved path derived from ~/.copilot/skills/understand-domain>}"
  echo "  - $HOME/.codex/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.opencode/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.pi/understand-anything/understand-anything-plugin"
  echo "  - $HOME/understand-anything/understand-anything-plugin"
  echo "Make sure the plugin is installed correctly."
  exit 1
fi

在后续阶段中，所有对代理定义的引用均使用

$PLUGIN_ROOT

。

Phase 1: Detect Existing Graph

阶段1：检测现有图谱

Check if

$PROJECT_ROOT/.understand-anything/knowledge-graph.json

exists

If it exists AND
```
--full
```
was NOT passed → proceed to Phase 3 (derive from graph)
Otherwise → proceed to Phase 2 (lightweight scan)

检查

$PROJECT_ROOT/.understand-anything/knowledge-graph.json

是否存在

若存在且未传入
```
--full
```
参数 → 进入阶段3（从图谱推导）
否则 → 进入阶段2（轻量扫描）

Phase 2: Lightweight Scan (Path 1)

阶段2：轻量扫描（路径1）

The preprocessing script does NOT produce a domain graph — it produces raw material (file tree, entry points, exports/imports) so the domain-analyzer agent can focus on the actual domain analysis instead of spending dozens of tool calls exploring the codebase. Think of it as a cheat sheet: cheap Python preprocessing → expensive LLM gets a clean, small input → better results for less cost.

Run the preprocessing script bundled with this skill, passing
```
$PROJECT_ROOT
```
from Phase 0:
```
python ./extract-domain-context.py "$PROJECT_ROOT"
```
This outputs
```
$PROJECT_ROOT/.understand-anything/intermediate/domain-context.json
```
containing:
- File tree (respecting
```
.gitignore
```
  )
- Detected entry points (HTTP routes, CLI commands, event handlers, cron jobs, exported handlers)
- File signatures (exports, imports per file)
- Code snippets for each entry point (signature + first few lines)
- Project metadata (package.json, README, etc.)
Read the generated
```
domain-context.json
```
as context for Phase 4
Proceed to Phase 4

预处理脚本不会生成领域图谱——它会生成原始素材（文件树、入口点、导出/导入信息），以便领域分析代理专注于实际的领域分析，而非花费数十次工具调用来探索代码库。可以将其视为一份 cheat sheet：低成本的Python预处理 → 昂贵的LLM获得简洁、小巧的输入 → 以更低成本获得更好结果。

运行本技能附带的预处理脚本，传入阶段0中获取的
```
$PROJECT_ROOT
```
：
```
python ./extract-domain-context.py "$PROJECT_ROOT"
```
该脚本会在
```
$PROJECT_ROOT/.understand-anything/intermediate/domain-context.json
```
中输出以下内容：
- 文件树（遵循
```
.gitignore
```
  规则）
- 检测到的入口点（HTTP路由、CLI命令、事件处理器、定时任务、导出处理器）
- 文件签名（每个文件的导出、导入信息）
- 每个入口点的代码片段（签名 + 前几行）
- 项目元数据（package.json、README等）
读取生成的
```
domain-context.json
```
作为阶段4的上下文
进入阶段4

Phase 3: Derive from Existing Graph (Path 2)

阶段3：从现有图谱推导（路径2）

Read

$PROJECT_ROOT/.understand-anything/knowledge-graph.json

Format the graph data as structured context:
- All nodes with their types, names, summaries, and tags
- All edges with their types (especially
```
calls
```
  ,
```
imports
```
  ,
```
contains
```
  )
- All layers with their descriptions
- Tour steps if available
This is the context for the domain analyzer — no file reading needed
Proceed to Phase 4

读取

$PROJECT_ROOT/.understand-anything/knowledge-graph.json

将图谱数据格式化为结构化上下文：
- 所有节点及其类型、名称、摘要和标签
- 所有边及其类型（尤其
```
calls
```
  、
```
imports
```
  、
```
contains
```
  ）
- 所有层及其描述
- 若有可用的引导步骤
这将作为领域分析器的上下文——无需读取文件
进入阶段4

Phase 4: Domain Analysis

阶段4：领域分析

Read the domain-analyzer agent prompt from
```
$PLUGIN_ROOT/agents/domain-analyzer.md
```
Dispatch a subagent with the domain-analyzer prompt + the context from Phase 2 or 3

The agent writes its output to

$PROJECT_ROOT/.understand-anything/intermediate/domain-analysis.json

从
```
$PLUGIN_ROOT/agents/domain-analyzer.md
```
读取领域分析代理提示词
调度子代理，传入领域分析代理提示词 + 阶段2或3的上下文

代理将输出写入

$PROJECT_ROOT/.understand-anything/intermediate/domain-analysis.json

Phase 5: Validate and Save

阶段5：验证与保存

Read the domain analysis output
Validate using the standard graph validation pipeline (the schema now supports domain/flow/step types)
If validation fails, log warnings but save what's valid (error tolerance)

Save to

$PROJECT_ROOT/.understand-anything/domain-graph.json

Clean up

$PROJECT_ROOT/.understand-anything/intermediate/domain-analysis.json

and

$PROJECT_ROOT/.understand-anything/intermediate/domain-context.json

读取领域分析输出
使用标准图谱验证管道进行验证（当前 schema 支持领域/流程/步骤类型）
若验证失败，记录警告但保存有效部分（容错处理）

保存到

$PROJECT_ROOT/.understand-anything/domain-graph.json

清理

$PROJECT_ROOT/.understand-anything/intermediate/domain-analysis.json

和

$PROJECT_ROOT/.understand-anything/intermediate/domain-context.json

Phase 6: Launch Dashboard

阶段6：启动仪表板

Auto-trigger
```
/understand-dashboard
```
to visualize the domain graph
The dashboard will detect
```
domain-graph.json
```
and show the domain view by default

自动触发
```
/understand-dashboard
```
以可视化领域图谱
仪表板将检测到
```
domain-graph.json
```
并默认显示领域视图

understand-domain

Original

Translation

/understand-domain

/understand-domain

How It Works

工作原理

Instructions

操作步骤

Phase 0: Resolve
`PROJECT_ROOT`

阶段0：解析
`PROJECT_ROOT`

Phase 1: Detect Existing Graph

阶段1：检测现有图谱

Phase 2: Lightweight Scan (Path 1)

阶段2：轻量扫描（路径1）

Phase 3: Derive from Existing Graph (Path 2)

阶段3：从现有图谱推导（路径2）

Phase 4: Domain Analysis

阶段4：领域分析

Phase 5: Validate and Save

阶段5：验证与保存

Phase 6: Launch Dashboard

阶段6：启动仪表板

understand-domain

Original

Translation

/understand-domain

/understand-domain

How It Works

工作原理

Instructions

操作步骤

Phase 0: Resolve PROJECT_ROOT

阶段0：解析PROJECT_ROOT

Phase 1: Detect Existing Graph

阶段1：检测现有图谱

Phase 2: Lightweight Scan (Path 1)

阶段2：轻量扫描（路径1）

Phase 3: Derive from Existing Graph (Path 2)

阶段3：从现有图谱推导（路径2）

Phase 4: Domain Analysis

阶段4：领域分析

Phase 5: Validate and Save

阶段5：验证与保存

Phase 6: Launch Dashboard

阶段6：启动仪表板

Phase 0: Resolve
`PROJECT_ROOT`

阶段0：解析
`PROJECT_ROOT`