← Back
Context Trees Beat RAG

Context Trees Beat RAG

The PageIndex framework hit 98.7% accuracy on financial documents where vector search scored around 50%. The secret? Stop searching. Start navigating.

This post applies that insight to a problem every Claude Code user faces: getting consistent CSS.

The Context Problem

You could paste your entire design system into CLAUDE.md. Every color, every spacing token, every component pattern. But Claude skims long documents. After about 100 lines, important details get missed.

Here’s what I’ve learned after months of heavy Claude use: CLAUDE.md should stay tight. Prune and review regularly. Just finished a long session with some important shifts in focus? Ask Claude to review CLAUDE.md before you quit.

So how do you give Claude access to large documents without burying the important stuff in noise?

The answer isn’t better search. It’s a structure that Claude can navigate and reason on.

This is the weakness RAG has. Chunking docs and matching by semantic similarity works for simple lookups. It fails for structured knowledge where context matters — and where “similar” doesn’t mean “relevant.”

Navigating with context is better than search alone.

Think about how you use a reference manual. You don’t Ctrl+F random keywords. You scan the table of contents, pick the right chapter, drill down to the section, and read the relevant passage. You follow a path.

A context tree gives Claude the same ability. Instead of similarity-matching against your whole codebase. Claude reads an index, reasons about where to look, and navigates to the section it needs, based on your existing conversation.

Here is what worked for me in my style guide:

style-guide/
├── index.md            # Index: links to each sub-doc
├── colors.md           # Your palette with CSS variables
├── layout.md           # Grid, spacing, container patterns
├── typography.md       # Font stacks, scales, line heights
├── dark-mode.md        # Theme switching approach
├── tokens.md           # Semantic variables
└── components/         # Button, card, alert patterns

When you say “build a product card,” Claude doesn’t grep for “card.” It reasons: Cards probably involve layout (→ layout.md), colors (→ colors.md), and… there might be a component pattern defined already. Claude uses your patterns instead of spitting out generic CSS.

Why This Works

PageIndex treats document structure as a tree and lets the LLM reason through it rather than just matching against it. The same principle can be applied to your design system:

ApproachWhat happens
Full context dumpEverything loaded, important rules buried in noise
Keyword/similarity searchMatches surface terms, misses semantic relationships
Context treeClaude navigates to relevant sections, preserves structure

The tree preserves relationships that chunking destroys. Your color palette connects to your dark mode strategy. Your spacing scale relates to your grid system. Claude can follow those connections because the structure is intact.

The Hidden Benefit: Explainability

When Claude uses a context tree, you can trace exactly why it made a choice. “I used var(--space-4) because tokens.md defines it as your standard component padding.”

With vector search or a massive context dump, Claude’s reasoning becomes opaque — leading to WTF moments. With a tree, every decision has a paper trail.

Build Your Own

The Style Guide Wizard plugin walks you through creating a context tree for your design system:

claude plugin marketplace add getskillsdev/claude-style-guide-wizard
claude plugin install gsd@claude-style-guide-wizard

Start claude

/gsd:style-wizard

Or build one yourself. The structure matters more than the tool choice:

  1. Create an index file that describes what each sub-document contains
  2. Organize info into sections - broad categories, each sub-doc contains specific patterns and examples.
  3. Include code examples in each section (Claude prefers examples, to abstract ideas)
  4. Reference between documents (“For dark mode colors, see dark-mode.md”)

If you’re thinking “I don’t have time for that” - start simple. Create a directory with an index.md. Then every time you need to correct Claude: ask Claude to save the pattern.

References: PageIndex introduced tree-based reasoning for document retrieval. The 98.7% accuracy benchmark comes from FinanceBench testing.

Subscribe to Skills Weekly, a digest of the hottest plugins & industry news. Only one email a week.

Want to unsubscribe?

We respect your privacy. Unsubscribe anytime. Privacy Policy

← Back