Make Your CLAUDE.md Docs Compound

While I was writing the last post about shrinking CLAUDE.md, I went down a rabbit hole on Andrej Karpathy’s LLM wiki. I left it out of that post because the post was already long and the wiki is solving a different problem. The idea kept following me around though.

The previous post stopped at the right place for what it was about. Split CLAUDE.md, link out to .claude/docs/, keep the entry file lean. That fixes loading.

The docs I just split out are still a binder. Files written once, opened occasionally by Claude, edited rarely by me. Useful, but inert. Every research session, every architecture call, every weird bug I solve, none of it makes the binder smarter on its own.

Karpathy’s wiki is the missing piece, and I’ve started adapting it.

What Karpathy Actually Proposed

The wiki is a folder of interlinked markdown entity pages. One concept per file. Backlinks between related pages. Contradictions flagged when new sources disagree with old claims. Summaries revised when new information lands. The LLM does the maintenance, not you.

“The tedious part of maintaining a knowledge base is not the reading or the thinking — it’s the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value.”

That’s the part that stuck. The follow-on is where it gets interesting:

“LLMs don’t get bored, don’t forget to update a cross-reference, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero.”

The contrast is with RAG. Traditional retrieval rediscovers everything from raw sources on every query. Nothing accumulates. The wiki accumulates because the LLM keeps integrating new material into existing pages instead of re-deriving from scratch.

He calls it a compounding artifact. That phrase is doing a lot of work.

The Idea I’m Borrowing

Not the whole wiki app. Just the discipline.

.claude/docs/ already has the right shape from the previous post. Small markdown files, linked from a top-level index. The wiki goes further:

One concept per file, not one chapter per file
Pages link to each other, not just back to the index
Claude writes to the docs after meaningful work, not just reads from them
The folder gets richer over time without me editing it manually

The previous post moved the docs out of CLAUDE.md. This one moves the docs from static reference to a knowledge base that grows.

What Changes in Practice

Where I started, after the previous post:

.claude/docs/
├── auth.md
├── database.md
└── deployment.md

Three big files. Each one written once, each one a chapter. Useful, but flat.

Where I’m headed:

.claude/docs/
├── index.md
├── auth/
│   ├── refresh-flow.md
│   ├── token-storage.md
│   └── session-expiry.md
├── database/
│   ├── rls.md
│   └── migrations.md
└── decisions/
    └── 2026-04-pkce.md

When Claude reads refresh-flow.md to answer a question, it already knows what’s adjacent. I don’t have to prompt my way there.

The Compounding Loop

One instruction in CLAUDE.md starts the loop:

## Maintenance

After a non-trivial change (new feature, schema change, decision, post-mortem),
update the relevant pages in `.claude/docs/` and ensure backlinks are bidirectional.
See [.claude/docs/index.md](.claude/docs/index.md).

It fires after:

A non-trivial PR. Claude updates the entity page that changed, or writes a new one.
A research session. Claude takes the durable parts of the conversation and files them.
A bug post-mortem. The post-mortem becomes a decisions/ page with backlinks to the concepts it touched.

That’s the only new instruction the agent needs.

What I’m Watching For

I haven’t been doing this long. Calling it a battle-tested workflow would be a lie. What I’m paying attention to as it runs:

Whether Claude over-edits, rewriting pages it shouldn’t touch and churning instead of accumulating
Whether backlinks stay bidirectional or rot
Whether the wiki actually changes how Claude works on the project, or whether I just have nicer-looking docs

Karpathy says LLMs don’t get bored. We’ll see.

Try It Yourself

If your .claude/docs/ is a few flat files, here’s a starting prompt:

I want to convert my .claude/docs/ folder into a wiki-style knowledge base, inspired by Karpathy's LLM wiki pattern. Right now it's a few large markdown files written once and rarely updated. I want it to be smaller entity pages with backlinks that you can update over time. Read every file in .claude/docs/. For each file, identify the entities it contains (concepts, flows, decisions, components). Then propose a new structure as a directory tree only. Do not make any changes yet. The structure should: 1. Have one concept per file, not one chapter per file 2. Group related pages into subdirectories (auth/, database/, decisions/, etc.) 3. Include an index.md as the navigation map 4. Preserve every fact and rule from the existing files After I review and approve the proposed tree, do the restructure: 1. Create the new files with the right content split across them 2. Add backlinks at the bottom of each page in a "Related" section, bidirectionally (if A links to B, B links to A) 3. Generate index.md with grouped links to every entity page 4. Delete the old files only after the new ones are confirmed complete Finally, propose a one-paragraph addition to CLAUDE.md that tells you to update or add pages in .claude/docs/ after meaningful work (new feature, schema change, decision, post-mortem) and to keep backlinks bidirectional. Do not invent new rules or facts. If something in the existing docs is unclear, flag it instead of guessing.

The previous post stopped a bloated CLAUDE.md from drowning Claude. This one is the experiment I’m running on the docs that came out the other side. Early days, but the shape feels right.