understand-onboard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/understand-onboard

Generate a comprehensive onboarding guide from the project's knowledge graph.

从项目的知识图谱生成全面的入职指南。

Graph Structure Reference

知识图谱结构参考

The knowledge graph JSON has this structure:

```
project
```
— {name, description, languages, frameworks, analyzedAt, gitCommitHash}
```
nodes[]
```
— each has {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
- Code node types: file, function, class, module, concept
- Non-code node types: config, document, service, table, endpoint, pipeline, schema, resource
- Domain/knowledge node types: domain, flow, step, article, entity, topic, claim, source
- IDs use the node type as prefix, e.g.
```
file:path
```
  ,
```
function:path:name
```
  ,
```
config:path
```
  ,
```
article:path
```
```
edges[]
```
— each has {source, target, type, direction, weight}
- Key types: imports, contains, calls, depends_on, configures, documents, deploys, triggers, contains_flow, flow_step, related, cites
```
layers[]
```
— each has {id, name, description, nodeIds[]}
```
tour[]
```
— each has {order, title, description, nodeIds[]}

知识图谱JSON的结构如下：

```
project
```
— {name, description, languages, frameworks, analyzedAt, gitCommitHash}
```
nodes[]
```
— 每个节点包含 {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
- 代码节点类型：file、function、class、module、concept
- 非代码节点类型：config、document、service、table、endpoint、pipeline、schema、resource
- 领域/知识节点类型：domain、flow、step、article、entity、topic、claim、source
- ID以节点类型为前缀，例如
```
file:path
```
  、
```
function:path:name
```
  、
```
config:path
```
  、
```
article:path
```
```
edges[]
```
— 每个边包含 {source, target, type, direction, weight}
- 关键类型：imports、contains、calls、depends_on、configures、documents、deploys、triggers、contains_flow、flow_step、related、cites
```
layers[]
```
— 每个层级包含 {id, name, description, nodeIds[]}
```
tour[]
```
— 每个导览项包含 {order, title, description, nodeIds[]}

How to Read Efficiently

高效阅读指南

Use Grep to search within the JSON for relevant entries BEFORE reading the full file
Only read sections you need — don't dump the entire graph into context
Node names and summaries are the most useful fields for understanding
Edges tell you how components connect — follow imports and calls for dependency chains

在通读整个文件之前，使用Grep在JSON中搜索相关条目
只阅读你需要的部分——不要把整个图谱都加载到上下文里
节点名称和摘要最有助于理解内容
边展示了组件之间的关联——跟随imports和calls查看依赖链

Instructions

操作步骤

Check that

.understand-anything/knowledge-graph.json

exists. If not, tell the user to run

/understand

first.

Read project metadata — use Grep or Read with a line limit to extract the
```
"project"
```
section (name, description, languages, frameworks).
Read layers — Grep for
```
"layers"
```
to get the full layers array. These define the architecture and will structure the guide.
Read the tour — Grep for
```
"tour"
```
to get the guided walkthrough steps. These provide the recommended learning path.
Read file-level structural nodes only — use Grep to find nodes with file-level types (
```
file
```
,
```
config
```
,
```
document
```
,
```
service
```
,
```
pipeline
```
,
```
table
```
,
```
schema
```
,
```
resource
```
,
```
endpoint
```
) in the knowledge graph. Skip function-level and class-level nodes to keep the guide high-level. Extract each node's
```
name
```
,
```
filePath
```
,
```
summary
```
, and
```
complexity
```
.
Identify complexity hotspots — from the file-level nodes, find those with the highest
```
complexity
```
values. These are areas new developers should approach carefully.
Generate the onboarding guide with these sections:
- Project Overview: name, languages, frameworks, description (from project metadata)
- Architecture Layers: each layer's name, description, and key files (from layers + file nodes)
- Key Concepts: important patterns and design decisions (from node summaries and tags)
- Guided Tour: step-by-step walkthrough (from the tour section)
- File Map: what each key file does (from file-level nodes, organized by layer)
- Complexity Hotspots: areas to approach carefully (from complexity values)
Format as clean markdown
Offer to save the guide to
```
docs/ONBOARDING.md
```
in the project
Suggest the user commit it to the repo for the team

检查
```
.understand-anything/knowledge-graph.json
```
是否存在。如果不存在，告知用户先运行
```
/understand
```
。
读取项目元数据——使用Grep或限制行数的读取方式提取
```
"project"
```
部分（name、description、languages、frameworks）。
读取层级信息——使用Grep搜索
```
"layers"
```
获取完整的层级数组。这些信息定义了架构，将作为指南的结构框架。
读取导览内容——使用Grep搜索
```
"tour"
```
获取分步导览内容。这些内容提供了推荐的学习路径。
仅读取文件级结构节点——使用Grep在知识图谱中查找文件级类型的节点（
```
file
```
、
```
config
```
、
```
document
```
、
```
service
```
、
```
pipeline
```
、
```
table
```
、
```
schema
```
、
```
resource
```
、
```
endpoint
```
）。跳过函数级和类级节点，保持指南的高视角。提取每个节点的
```
name
```
、
```
filePath
```
、
```
summary
```
和
```
complexity
```
。
识别复杂度热点——从文件级节点中找出
```
complexity
```
值最高的节点。这些是新开发者需要谨慎处理的区域。
生成入职指南，包含以下部分：
- 项目概述：名称、使用语言、框架、描述（来自项目元数据）
- 架构层级：每个层级的名称、描述和关键文件（来自层级信息 + 文件节点）
- 核心概念：重要模式和设计决策（来自节点摘要和标签）
- 引导导览：分步操作指南（来自导览部分）
- 文件映射：每个关键文件的作用（来自文件级节点，按层级组织）
- 复杂度热点：需要谨慎处理的区域（来自复杂度值）
整理为简洁的Markdown格式
询问用户是否要将指南保存到项目的
```
docs/ONBOARDING.md
```
中
建议用户将其提交到代码仓库供团队使用