Understanding Graphs: "Less, But Better" Codebase Navigation

The question arose during a discussion of agent reasoning in large codebases: would Markov Chains improve context management? This led to a deeper inquiry: what do agents (and humans) actually need to understand code?

Traditional dependency graphs answer the wrong question. They show all relationships—every import, every type reference, every function call. But comprehension doesn't require exhaustive mapping; it requires sufficient mapping. The hermeneutic question became: What is sufficient for understanding?

This research asks: Can dependency documentation embody "Less, but better"?

We propose "Understanding Graphs"—minimal documents that capture only what's needed to comprehend a package in context. These documents:

• Are human-readable (plain markdown, no visualization required)
• Are machine-parseable (Claude Code can use them for context)
• Capture bidirectional relationships (depends on + enables understanding of)
• Include semantic meaning (why, not just what)
• Require no tooling (no LSP, no graph database, no build step)

Contributions: (1) A hermeneutic methodology for "sufficient" documentation, (2) The UNDERSTANDING.md canonical format, (3) Implementation across CREATE SOMETHING monorepo, (4) A Claude Code Skill for maintaining understanding graphs.

We applied Heidegger's hermeneutic circle—the interpretive method where understanding emerges through movement between whole and parts. The "whole" was the CREATE SOMETHING methodology; the "part" was dependency documentation.

2.1 First Movement: Whole → Part

We began by examining what traditional dependency graphs provide:

This violates Rams' principles: it's not useful (overwhelming), not unobtrusive (requires tooling), and certainly not "as little as possible."

2.2 Second Movement: Part → Whole

We then asked: what would sufficient documentation look like? The hermeneutic insight emerged: understanding is not about knowing all connections but about knowing where to start and what relates to what semantically.

A developer doesn't need to know every import. They need to know:

• Purpose: What does this package do? (one sentence)
• Position: How does it fit in the larger system?
• Entry points: What 3-5 files should I read first?
• Key concepts: What terms might confuse me?
• Relationships: What does this depend on? What depends on this?

2.3 The Hermeneutic Insight

The critical realization: dependency graphs are unidirectional (A depends on B), but understanding flows bidirectionally. Understanding A helps me understand B, and vice versa. The documentation format must capture this circular flow—exactly what the hermeneutic circle describes.

3.1 The UNDERSTANDING.md Format

We developed a canonical format that balances human readability with machine parseability:

# Understanding: [Package Name]

> **[One-sentence purpose]**

## Ontological Position
**Mode of Being**: [Role in system]
[2-3 sentences on relationship to whole]

## Depends On (Understanding-Critical)
| Dependency | Why It Matters |
|------------|----------------|
| `pkg`    | [What this enables] |

## Enables Understanding Of
| Consumer | What This Clarifies |
|----------|---------------------|
| `pkg`  | [How this helps] |

## To Understand This Package, Read
1. **[file]** — [Why this is entry point]
2. **[file]** — [What concept this explains]

## Key Concepts
| Concept | Definition | Where |
|---------|------------|-------|
| [Term]  | [Brief]    | [File]|

3.2 What Makes It "Less, But Better"

3.3 Monorepo Implementation

We created UNDERSTANDING.md files for all six packages in the CREATE SOMETHING monorepo:

packages/
├── components/UNDERSTANDING.md  → Foundation (Vorverständnis)
├── tufte/UNDERSTANDING.md       → Visualization foundation
├── ltd/UNDERSTANDING.md         → Being-as-Canon
├── io/UNDERSTANDING.md          → Being-as-Document
├── space/UNDERSTANDING.md       → Being-as-Experience
└── agency/UNDERSTANDING.md      → Being-as-Service

Each file follows the canonical format, capturing only what's needed to understand that package in the context of the hermeneutic workflow.

3.4 Claude Code Skill

To maintain understanding graphs over time, we created the understanding-graphs Skill. This Skill provides:

• Guidelines for creating new UNDERSTANDING.md files
• Validation checklist (one-sentence purpose, 3-5 entry points, etc.)
• Update criteria (when to update vs. leave alone)
• Integration with other CREATE SOMETHING Skills

4.1 Comparison: Traditional vs. Understanding Graphs

4.2 Hermeneutic Circle Validation

The implementation completed the hermeneutic circle:

5.1 Why Markov Chains Were the Wrong Question

The original question—whether Markov Chains could improve agent reasoning—assumed the problem was state compression. But the hermeneutic analysis revealed the actual problem is semantic navigation. Markov Chains are memoryless; understanding requires accumulated context. The hermeneutic circle works precisely because we carry prior understanding into each new encounter.

Understanding Graphs enable this accumulation: each UNDERSTANDING.md provides the pre-understanding (Vorverständnis) needed to engage with a package. Claude Code can read these documents to build context without loading entire codebases.

5.2 Implications for AI-Native Development

This research suggests a pattern for AI-human collaboration in codebase navigation:

• Human-authored understanding: Developers write UNDERSTANDING.md with semantic insight
• AI-consumed context: Claude Code uses these for efficient navigation
• AI-assisted maintenance: The understanding-graphs Skill guides updates
• Bidirectional benefit: Both humans and AI navigate the same documentation

5.3 Limitations

Understanding Graphs require human judgment to identify "understanding-critical" relationships. This is both a strength (captures semantic meaning machines miss) and limitation (requires maintenance). We mitigate this through:

• Clear validation checklist (one-sentence purpose, 3-5 entry points)
• Staleness tracking ("Last validated" date)
• Update criteria (only on structural changes, not bug fixes)

5.4 Future Work

Potential extensions include:

• Automated staleness detection (compare UNDERSTANDING.md to recent commits)
• Graph visualization from markdown (optional, generated on demand)
• Cross-repository understanding graphs (for microservices)
• Integration with IDE navigation (jump to entry points)

This research demonstrates that dependency documentation can embody "Less, but better." Traditional dependency graphs violate Rams' principles—they're exhaustive when sufficiency is needed, require tooling when plain text suffices, and capture structure when meaning matters.

Understanding Graphs invert these assumptions. By applying Heidegger's hermeneutic circle, we identified that codebase comprehension requires semantic navigation, not exhaustive mapping. The UNDERSTANDING.md format captures only what's needed: purpose, position, entry points, concepts, and bidirectional relationships.

Implementation across the CREATE SOMETHING monorepo validated the approach. Six packages now have human-readable, machine-parseable understanding graphs that require no tooling and embody the minimalist philosophy that guides the entire methodology.

The hermeneutic insight: To understand a codebase, you don't need all relationships—just the right ones.