Using Knowledge Graphs for Onboarding New Team Members in Understand Anything

Understand Anything converts your codebase into a typed KnowledgeGraph that automatically generates comprehensive onboarding documentation through the buildOnboardingGuide function, eliminating manual documentation overhead for new team members.

The Egonex-AI/Understand-Anything repository provides a multi-agent system that transforms raw source code into a structured knowledge graph. This graph captures every file, function, class, and architectural relationship, then compiles them into self-contained onboarding guides that help new developers navigate complex codebases efficiently.

How the Knowledge Graph Powers Onboarding

The onboarding process relies on a typed knowledge graph (KnowledgeGraph) that serves as the single source of truth for your codebase's structure and semantics.

Graph Construction Pipeline

The system employs a multi-agent pipeline to build the graph incrementally. The project-scanner, file-analyzer, and architecture-analyzer agents parse each source file using tree-sitter to extract structural data. This data is then enriched with LLM-generated summaries, semantic tags, and layer assignments. The resulting graph is stored as KnowledgeGraph according to the type definitions in packages/core/src/types.ts.

This graph encodes:

• Import/export relationships between modules
• Function and class hierarchies
• Architectural layers (e.g., data layer, service layer)
• Complexity metrics for identifying hotspots
• Conceptual nodes explaining domain-specific logic

The KnowledgeGraph Schema

As defined in packages/core/src/types.ts, the graph uses typed nodes and edges to represent code entities. Each node carries metadata including file paths, line numbers, descriptions, and complexity scores. Edges represent relationships like "calls", "imports", or "belongs-to-layer". This structure enables precise traversal when generating documentation or answering specific questions about the codebase.

Generating Onboarding Guides with buildOnboardingGuide

The core onboarding functionality resides in src/onboard-builder.ts, which exports the buildOnboardingGuide function. This function consumes a KnowledgeGraph instance and produces a markdown document containing several structured sections.

The generated guide automatically includes:

• Project Overview: Repository name, description, primary languages, and frameworks
• Architecture Section: Logical layers and their key components mapped from graph layers
• Key Concepts: Nodes of type concept that explain domain-specific terminology
• Guided Tour: An ordered tour array with file links and contextual lessons
• File Map: A navigable table of significant files
• Complexity Hotspots: A curated list of the most intricate code sections requiring careful attention

Practical Implementation

import { buildOnboardingGuide } from "./src/onboard-builder";
import type { KnowledgeGraph } from "@understand-anything/core";
import fs from "fs";

// Load the previously generated knowledge graph
const graph: KnowledgeGraph = JSON.parse(
  fs.readFileSync(
    ".understand-anything/knowledge-graph.json",
    "utf-8"
  )
);

// Produce the onboarding guide as markdown
const guideMd = buildOnboardingGuide(graph);

// Save it where new contributors will see it
fs.writeFileSync("ONBOARDING_GUIDE.md", guideMd);

Contextual Learning for Ad-Hoc Questions

Beyond static documentation, the system supports dynamic query resolution through the buildChatContext function in src/context-builder.ts. When a new team member asks specific questions like "How does authentication work?", this function uses the internal SearchEngine to locate relevant nodes in the knowledge graph.

The process works by:

1. Executing semantic search against graph nodes
2. Expanding context by traversing one hop via edges to capture related entities
3. Formatting the subgraph into a markdown prompt via formatContextForPrompt

This approach gives LLMs a concise, graph-based view of the project that is far more focused than providing raw source files, enabling precise answers to architectural questions without overwhelming context windows.

Automated Onboarding Workflows

The repository provides CLI commands that automate the entire onboarding pipeline. The /understand command generates or refreshes the knowledge graph, writing the serialized data to .understand-anything/knowledge-graph.json. The /understand-onboard command then invokes buildOnboardingGuide to produce the markdown documentation.

Complete Workflow Example

# Generate the knowledge graph from source

$ /understand

# Create the onboarding guide

$ /understand-onboard

# Commit the documentation for new team members

$ git add ONBOARDING_GUIDE.md && git commit -m "Add auto-generated onboarding guide"

For interactive learning, the /understand-chat command leverages the graph for contextual query responses:

# Query-driven context retrieval

$ /understand-chat "How does authentication work?"

# Internally runs buildChatContext → SearchEngine → formatContextForPrompt

The tour generation logic specified in agents/tour-builder.md ensures that the guided paths through the codebase follow logical dependencies and complexity gradients, making the learning curve manageable for new developers.

Summary

• Understand Anything constructs a typed KnowledgeGraph using tree-sitter parsing and LLM enrichment to model your entire codebase.
• The buildOnboardingGuide function in src/onboard-builder.ts transforms this graph into a comprehensive markdown guide including architecture overviews, key concepts, and complexity hotspots.
• buildChatContext enables dynamic, query-specific onboarding by searching the graph and formatting relevant subgraphs for LLM consumption.
• CLI commands /understand and /understand-onboard automate the generation and updating of onboarding documentation, ensuring it stays synchronized with code changes.
• The system stores graph definitions in packages/core/src/types.ts and implements tour logic in agents/tour-builder.md.

Frequently Asked Questions

How does the knowledge graph handle large codebases with thousands of files?

The multi-agent pipeline in Understand Anything processes files incrementally, storing the KnowledgeGraph as a JSON file in .understand-anything/knowledge-graph.json. The buildOnboardingGuide function filters and prioritizes nodes based on complexity scores and layer assignments, ensuring that generated documentation focuses on architecturally significant components rather than overwhelming new team members with every implementation detail.

Can I customize the sections included in the onboarding guide?

While the standard buildOnboardingGuide function produces a fixed set of sections (overview, architecture, concepts, tour, and hotspots), the KnowledgeGraph schema in packages/core/src/types.ts supports custom node types and metadata. You can extend the builder logic or post-process the markdown output to include additional sections derived from custom graph queries, such as security-sensitive files or API endpoints.

What is the difference between /understand-onboard and /understand-chat?

The /understand-onboard command generates static documentation by calling buildOnboardingGuide, producing a complete markdown file like ONBOARDING_GUIDE.md that serves as persistent reference material. The /understand-chat command uses buildChatContext to dynamically query the graph for specific topics, providing targeted explanations for immediate questions without requiring the user to search through the full guide manually.

How does the tour builder determine the order of files to show new team members?

According to the specifications in agents/tour-builder.md, the tour builder analyzes the KnowledgeGraph to identify entry points (files with high inbound dependencies but low complexity) and critical paths to core architectural components. It constructs an ordered tour array that progresses from foundational concepts to complex implementations, using edge relationships to ensure each step builds upon previously introduced material.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}