The larger a codebase gets, the faster documentation falls behind. Add agents to the mix and the gap widens - not because agents make more mistakes, but because decisions move faster. A human cuts a feature on Tuesday. An agent restructures the auth flow Thursday. By Friday, your CLAUDE.md still points to a SPEC that hasn’t been true since last sprint. A fresh agent session reads it. Builds from it. With full confidence.
The deeper problem isn’t any individual missed update - it’s that there’s no system. Manual versioning produces file clutter with no discovery mechanism and no standard for separating a codebase-wide spec from a feature spec. If your CLAUDE.md says “always refer to SPEC” and four files answer to that name, the instruction is meaningless. Documentation falls behind not because nobody cares, but because there’s no structured place for knowledge to live and grow alongside the code.
The Idea
Like most practitioners following Andrej Karpathy’s work, I’d been using his LLM knowledge base pattern for research and a second brain - tracking projects, articles, and interconnected ideas. For those unfamiliar: instead of dumping raw documents into retrieval at query time, an LLM incrementally builds and maintains a persistent wiki. When you add a new source, it doesn’t just index the content. It reads it, extracts key information, and integrates it into the existing wiki - updating concept pages, noting connections, resolving contradictions with what’s already there. The knowledge is compiled once and kept current. You source; the LLM does the filing, cross-referencing, and bookkeeping. It’s powerful because you’re not re-deriving relationships on every query. The wiki already knows how things connect.
Codebases have the same problem. Architecture decisions, spec evolution, the reasoning behind tradeoffs - all information that needs to be compiled once and kept current, not scattered across 7 differently named spec files (looking at you SPEC_v1.3 and SPEC.old and FEATURE_SPEC) and six months of commit messages.
So I put the knowledge base inside the codebase.
The /raw directory holds source files as originally written - specs, decision notes, research. When a spec evolves, the new version sits alongside the old one. History stays.
The /wiki is the maintained layer. The agent builds and updates it: architecture concepts, entity definitions, spec summaries with version history, outstanding questions, domain conventions. Pages link to each other. When a decision affects three domains, the wiki reflects it in all three.
The CLAUDE.md or AGENTS.md is the instruction that ties it together: any agent entering this codebase reads the knowledge base, maintains it, and queries it before asking questions the documentation has already answered. You write the raw files. The agents write the wiki.
What Changed
Every agent working in the codebase became a librarian automatically - not because I assigned it documentation tasks, but because the AGENTS.md made the wiki its default reference and its default output target. Maintenance became ambient.
The project root got clean. One place for documentation to live, one format, one discovery path.
Knowledge discovery simplified. Instead of loading multiple context files and hoping the agent read all of them, the agent queries the wiki for whatever’s relevant to its current task. It gets back only what’s topically connected - lean context, fewer tokens, less hallucination from material that was never relevant to the task in the first place.
When a decision changes, the agent in that session documents it in the same pass. The knowledge base grows with the codebase. Not because you remembered to write it back. Because the setup expects it.
The Real Unlock for Agentic Development
This is where the pattern changes what’s actually possible.
Without structured knowledge in the codebase, starting a new agent session requires orientation. You tell it what to work on, what to read, what constraints apply. Either you load a lot into context upfront - expensive and often stale - or you accept that the agent will miss things.
With a knowledge base in the codebase, a fresh agent orients itself. It queries what’s available to work on. It queries what it needs to know about the relevant domain. It gets back only information topically connected to its task - not the entire project history, not three spec files of varying accuracy. Just what it needs.
It implements. It writes learnings back to the wiki. The next session inherits better context than the one before it.
That compounds. Every session makes the next one more accurate - because the map keeps getting updated.
Part 2
What this post doesn’t cover is how the wiki stays current through active development - specifically, the workflow mechanism that writes decisions back after every task without depending on you remembering. That’s CRAFTS, a development methodology built around exactly this kind of compounding. Part 2 covers the full picture: how CRAFTS phases map to specialized subagents, how adversarial review works across different model families, and how the Sharpen phase closes the loop back into the knowledge base.
For now: if your agents are working from documentation that hasn’t kept pace with your codebase, the problem isn’t the prompt. The map is wrong. A knowledge base that agents maintain as part of doing the work is the fix.