Introduction
vibe coding → agentic engineering → LLM wiki
In my previous article about AI tools and agents, I explored the instruments that are changing how software is developed. In the follow-up, I argued that the developer's role is shifting from writing code to directing it.
This article takes the next step: what happens when AI agents become capable of building and navigating increasingly complex codebases? How do we keep the knowledge they rely on accurate, discoverable, and up to date? This is where the idea of an LLM wiki comes in.
An onboarding file (example: CLAUDE.MD) tells the agent how to behave: the conventions, the layer rules, the forbidden patterns. What it does not give the agent is the accumulated knowledge of your system — why the payment flow has that strange branch, which of the eleven integrations quietly deviates from its documented contract, which parts of the documentation are lies. A human developer builds this knowledge over months of incidents and code reviews. An agent starts from zero every single session.
In April 2026 Andrej Karpathy published a short gist called LLM Wiki that proposes one answer to this problem. I implemented it over the payment core of a large platform I work on. Before that, I had been practicing a different answer: a README-driven repository where every module documents itself and the agent is told exactly what to read. This article is a field report on both — what each approach looks like in production, where they turn out to be the same idea, and when you actually need one over the other.
[I] Karpathy's LLM Wiki: The Idea
The gist describes itself modestly: "A pattern for building personal knowledge bases using LLMs. This is an idea file, it is designed to be copy pasted to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, or etc.)". Not a product, not a framework — a pattern you hand to the agent you already have.
The Problem It Names
Karpathy starts from the failure mode of the default approach — retrieval over a pile of raw documents, RAG-style:
"Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up."
The traditional alternative — a hand-maintained wiki — fails for the opposite reason: humans are bad at the maintenance. As the gist puts it, "the tedious part of maintaining a knowledge base is not reading or thinking — it's the bookkeeping". Updating cross-references, reconciling contradictions, keeping the index consistent — exactly the work people silently stop doing after week three.
Three Layers, Two Files, Three Operations
The proposed structure is deliberately minimal:
raw/ immutable source documents; raw/assets/ for attachments wiki/ markdown pages — written and maintained only by the LLM CLAUDE.md the schema: conventions and instructions for the agent index.md a catalog of every page with a one-line description log.md append-only journal of everything the wiki did
And the agent performs three operations on it:
- Ingest. A new source arrives; the LLM reads it, discusses the takeaways with you, writes a summary page — and, this is the important part, updates ten or fifteen existing pages with new connections and corrections.
- Query. You ask a question; the LLM routes through the index, reads the relevant pages, and synthesizes an answer with citations. A good answer can itself be filed back as a new page.
- Lint. A periodic health check: contradictions, orphan pages, stale claims, missing cross-references.
"You never write the wiki yourself — the LLM writes and maintains all of it."
Your job, then? "The human's job is to curate sources, direct analysis, ask good questions. The LLM's job is everything else."
"The wiki is a persistent, compounding artifact. The cross-references are already there."
[II] How I Implemented It: A Wiki Over a Payment Core
This is not a thought experiment — the wiki is built and in daily use. It runs on top of a large payment platform: a DDD + CQRS monolith with around twenty bounded contexts and roughly 37,000 PHP files. It does not try to swallow the whole system — it covers the hardest part, the payment core, distilled into exactly 70 pages.
It lives in .claude/wiki/ and is deliberately gitignored: a personal synthesis layer, not team documentation — and not a replacement for the module READMEs, but a layer on top of them. It is invoked through an explicit slash command — /wiki, described below; nothing is auto-loaded into context.
The Shape of It
.claude/wiki/ ├── CLAUDE.md the constitution: source rules, page templates, lint │ checklist — the only file a human edits ├── index.md the router: "if you are looking for X -> page Y", │ known contradictions, known gaps ├── log.md append-only journal ├── contexts/ 7 pages — one per bounded context ├── providers/ 8 pages — the payment-provider roster ├── concepts/ 10 pages — cross-cutting domain concepts └── flows/ 5 pages — end-to-end payment scenarios
The index deserves special mention. It is not a table of contents — it is a router. Its main section is literally a table of "if you are looking for X, open page Y" entries, followed by a list of known contradictions and a list of known gaps. The query workflow starts there: pick three to seven pages, follow links at most one level deeper, synthesize. And if the wiki has no answer, the rule is to say "the wiki does not cover this" and propose ingesting a source — not to quietly improvise from code.
Anatomy of a Page
Every page follows the same contract, enforced by the schema file:
--- title: Provider A — card processing type: provider status: active verified: 2026-07-14 verified_sha: 3f9c2e1 ---
A page opens with a lead paragraph that answers "why you came here", uses a single level of headings, always ends with an "Open questions" section, and must stay under 120 lines. When a page outgrows the budget, the rule is to split it into two linked pages — never to stretch it. And every page needs at least two inbound links, so knowledge stays reachable instead of orphaned.
The /wiki Command — and the One Rule That Holds It Together
All of this is wrapped into a single custom slash command I created for the agent — /wiki, defined in .claude/commands/wiki.md. It is the only entry point: outside of it, the wiki is never touched. Karpathy's three operations grew into seven subcommands:
/wiki seed initial fill of the wiki from the codebase /wiki ingest <source> absorb a document, a plan, or a memory note /wiki query <question> answer from the wiki, with credibility markers /wiki sync [ref] reconcile pages with the code they describe /wiki verify <page> re-check a single page against its sources /wiki lint the 17-check health suite /wiki status cheap frontmatter-only health readout
Every subcommand starts with the same mandatory pre-flight: read the schema (the wiki's CLAUDE.md), read the index, check the last entries of the log — so the agent always operates under the wiki's rules rather than its own habits. Two subcommands do the heavy lifting:
- sync — run after every
git pulland after finishing a task, before the merge request. For each page it diffs the code between the SHA the page was last verified at and the current HEAD, restricted to that page's declared sources. Every touched page gets one of three verdicts: unchanged (only the verification stamp moves), corrected (the diff made the page wrong — the text gets fixed), or uncovered (new behavior no page describes — a new page is proposed). - lint — seventeen automated checks run by two parallel read-only subagents: contradictions, orphans, broken links, budget overruns. The check I value most re-runs every negative claim's command and flags any grep that has stopped returning empty.
[III] The Approach I Was Already Using: README-Driven Repos
Long before the gist, I had been practicing documentation-as-code. The documentation there went through its own migration: out of Confluence, into the repository, next to the code it describes. Confluence did not disappear — it now holds a curated mirror of selected pages for management, rendered from the repository through a GitHub plugin. Engineers read and edit markdown next to the code; managers read Confluence; there is exactly one source of truth.
Four Levels of Documentation
application/
├── README.md 73 lines the map: modern modules vs
│ legacy, migration plan
├── ARCHITECTURE.MD 921 lines frozen narrative: how the
│ system actually works
├── modules/
│ ├── README.md 952 lines the conventions bible: layers,
│ │ naming, DI, testing, checklists
│ └── {Module}/README.md ~300 lines business value, annotated
│ file tree, data flow, monitoring
└── docs/ guides, rules, api-doc...
Each level answers a different question. The top README answers "what is where, and what is legacy". The architecture narrative answers "how does this actually work end to end". The conventions guide answers "how do I build a module here". And each module's README answers "what does this module do, and why does it exist" — the best of them opens with business value, walks through an annotated tree of all 62 of its files, and closes with monitoring and configuration.
CLAUDE.md as a Router, Not a Container
The crucial decision in this setup: the onboarding file does not contain the knowledge. It routes to it. The project's CLAUDE.md opens with a fixed reading order — "before executing any task, read the following documentation" — pointing at the four levels above, and then delegates downward: "Read the relevant module README before working on module-specific code." The agent ends up reading the two or three documents relevant to the task, not the whole tree. Progressive disclosure — before I knew there was a term for it.
And the routing works in both directions. The same CLAUDE.md makes updating the documentation part of the task itself: "Keep README up to date. After making changes to an application, update the corresponding README.md." So after finishing a change, the agent itself updates the README of the module it touched — the documentation diff lands in the same merge request as the code diff, and both are reviewed together. No separate "documentation day", no ticket to write the docs later: the docs move with the code, or they do not move at all.
[IV] Same Idea, Two Scales
Put side by side, the two approaches are almost embarrassingly similar. Knowledge lives next to the code, in plain files, under version control. An entry file routes the agent instead of stuffing everything into its context. Reading is progressive: index first, then the two or three documents that matter. If your coding agent indexes the repository well, both setups give it the same superpower — it stops rediscovering your system and starts consulting it.
The real difference is not the format. It is the answer to two questions: where does the knowledge come from, and who does the bookkeeping?
A README is written by a developer, about one module, from the code in front of them. A wiki in Karpathy's sense is synthesized by the LLM from every source it can reach:
Code ↓ Git history ↓ README files ↓ Architecture Decision Records ↓ Issues / Pull Requests ↓ LLM — reads, synthesizes, cross-links ↓ Knowledge Graph / Wiki
Which produces this comparison:
--------------------+---------------------------+---------------------------
| README-per-module | LLM Wiki
--------------------+---------------------------+---------------------------
Who writes it | developers | the LLM writes,
| | a human curates
Sources | the module's code | code, git history, README,
| | ADRs, issues and PRs
Unit of knowledge | one module | cross-module synthesis
Staleness | manual updates — drifts | mechanically detectable
| | (SHA diffs, lint)
Structure | fixed up front | grows with the knowledge
Sweet spot | the current project | huge, heterogeneous
| | knowledge volumes
--------------------+---------------------------+---------------------------
[V] When You Don't Need a Wiki
On the other hand, I am ready to admit that not every project needs a separate LLM wiki. If you work with a coding agent that indexes a repository well — Claude Code, Cursor, Codex — and your repository is well-structured — clean modular code, a README per module, clear DDD boundaries, and architecture documents — then much of the knowledge the wiki provides is already available through repository retrieval.
The wiki becomes valuable when the repository itself is no longer enough to answer cross-cutting questions. It adds a synthesis layer for knowledge that does not naturally belong to any single module: relationships between bounded contexts, end-to-end flows, provider comparisons, architectural contradictions, and verified claims that span multiple sources.
So the choice is not really "README or Wiki". A well-structured repository is the foundation. The wiki is an additional layer that becomes useful when the complexity of the system creates knowledge that cannot be cleanly owned by a single part of the codebase.
The Default Setup I Recommend
For a modular project of ordinary size, I would not start with a wiki. I would start with this:
docs/ ├── architecture/ │ ├── overview.md system map: contexts and boundaries │ └── payment-flow.md end-to-end flows ├── decisions/ ADRs — the "why", not just the "what" ├── modules/ one page per module ├── integrations/ external services and their contracts └── development/ conventions, how to add a module AGENTS.md / CLAUDE.md the rules — and the routing
With an agent rules file whose contents look like this:
- You are working in DDD + Clean Architecture.
- Domain does not depend on Infrastructure.
- Use cases live in the Application layer.
- Do not use Doctrine inside Domain.
- Every change ships with tests.
- Before changing the payment flow, read
docs/architecture/payment-flow.md.
That last line is the pattern that matters most: rules that route. "Before touching X, read Y" gives the agent exactly the progressive disclosure a wiki index gives — at zero maintenance cost beyond keeping Y honest.
Conclusion
Strip away the formats, and both approaches are one philosophy. Knowledge lives next to the code, in plain files, versioned like code. An entry file — CLAUDE.md, index.md — is a router, not a container.
The ladder, as I see it now:
- Every project: a README worth reading, and a CLAUDE.md that routes.
- Modular projects: a
docs/tree — architecture, decisions, module pages — with "read X before touching Y" rules wired into the agent file. - Past the complexity threshold: an LLM-maintained wiki with verification metadata, synthesizing what no single document holds.
Where to Start
- Turn your CLAUDE.md into a router. A reading order, "read X before touching Y" rules, pointers instead of content. If it is longer than a page, it is holding knowledge that belongs elsewhere
- Create the docs/ skeleton. architecture/, decisions/, modules/, integrations/, development/ — even with three files in it, the structure tells both humans and agents where knowledge lives
- Write ADRs for the decisions you already regret not writing down. The "why" is the only part of your system an agent cannot re-derive from code
- Stop enumerating what a command can list. Point at
ls, route dumps, configs. Lists drift; the filesystem does not - Past the threshold — seed a wiki over your hardest subsystem. Copy Karpathy's gist to your agent, point it at the one domain where every answer lives in five places, and let it write the seventy pages you never will
- Make freshness mechanical. Pin every synthesized page to the commit it was verified against, and make "the diff was read" a precondition for moving that pin. A knowledge base you cannot audit for staleness is a rumor mill with good formatting
In the previous article I argued that the code is no longer yours. The knowledge about the code still has to be. The only question left is who maintains that knowledge — you, or your agent. My answer, after running both approaches: you curate, it maintains. That division of labor is the whole pattern.