Wikis and similar systems — Confluence, Notion, and the rest — are orthogonal to the system itself. Pages fall behind quickly, because updating them is secondary labor. In a traditional SDLC, this isn’t the end of the world. Humans can just ignore out-of-date documentation, and rely on the bits they know to be reliable, filling in the gaps by asking their manager or emailing the product team. An agent won’t do that! A copy and paste from outdated docs will be treated as 100% true by an agent.
Ultimately, this is less a model problem than a documentation and memory problem.
The repository as the system of record
One solution to this problem is to make the repository the system of record. Requirements and rationales live alongside the modules they describe, and git history and PR comments explain what changed along the way. Jira and Confluence shift from being the source of truth to useful reports generated from what lives in the repo.
Several forces stack in favor of this locality, especially with agents in the loop. The simplest is colocation: docs that live next to src/billing/ change when billing changes. Local docs aren’t orthogonal to the work the way wiki articles are. And because they ride the same branches, the honesty machinery you already run (pull requests, human and agent review, CI checks, linters) can govern documentation too.
Locality also changes what a diagram is worth. A box-and-arrow PNG in Confluence is opaque to an agent, but a Mermaid flowchart beside the service entrypoint shows up in the diff and can be read by the tools. Underneath all of this is a question of what the artifact is optimized for. When agents and engineers reason about a change, the question is usually what a module does and what must not break, not where the payments wiki lives. A repository is organized around that question; a topical wiki fights it.
Karpathy’s markdown library: compile, don’t chunk
We’re not the only ones thinking this way. Andrej Karpathy recently described an approach to building an LLM knowledge base that bypasses classic RAG for many real workloads. You dump raw material into a folder, let an agent compile it into interlinked Markdown, and run periodic lint passes so the library stays consistent. At team scale he argued structured text plus indices beats opaque embedding search that returns plausible fragments with weak provenance.
That pattern rhymes with system documentation too. You already have the raw material of a knowledge base scattered everywhere: git history, tickets, Slack threads, and code. You’re just not compiling it into agent-readable truth that lives beside the work. Karpathy’s point is that the model can be your librarian. Once the pattern is established, summaries, cross-links, and cleanup become ongoing maintenance, done entirely agentically, rather than a one-time migration project. This doesn’t mean vector databases are dead; it means the interesting bet for many product engineering teams is versioned Markdown in git, maintained with the same habits as code.
What you should do Monday
We are intentionally not prescribing a full-on “move your tickets into git” or “replace Jira with YAML tasks” project. Ticket workflow is a separate fight, and many teams are not ready for it. This thesis calls for different experiments around documentation and shared memory.
Try this: pick one bounded subsystem and require that its functional and architectural documentation live in Markdown/Mermaid stored alongside the code. Treat wiki pages as deprecated for that slice. Then add a lightweight gate that makes drift visible: a CI check that fails when certain paths change but their docs don’t, or an agent lint step that compares README claims to test names and public API surfaces.
Run a Karpathy-style compile pass to flesh out this new library: export related decisions from Slack into a raw/ folder, then run a bounded agent job to produce interlinked docs/ with backlinks. Review the agent’s work and tweak based on what it missed or under/overemphasized. Measure whether onboarding and agent sessions get faster, more accurate, or just plain easier.
Whatever experiment you run, teams will have to adjust. This change lands differently on each side of the house. Product leaders will need to build fluency with repo-resident artifacts (reading a spec in git, commenting on a PR). For engineering leaders, the change means owning freshness: if agents read the repo, stale local docs are now a production risk, not a technical-writing nuisance.
None of this requires replacing the wiki overnight. Plenty of orgs will keep it as the official face for auditors and executives, and that’s not wrong. Different consumers need different views. The bet worth running in 2026 is smaller: for the teams shipping with agents, stop asking them to treat a parallel documentation universe as true. Put truth beside the implementation, let git govern change, and let agents help maintain the library the same way we finally learned to let CI maintain tests.
Further Reading
- LLM Wiki (Karpathy’s own gist) – Andrej Karpathy, ~Apr 2026. His three-layer pattern:
raw/(immutable sources) →wiki/(LLM-generated interlinked Markdown) → a schema file (he names CLAUDE.md / AGENTS.md), withingest/query/lintops and the LLM as “compiler.” This is the thesis in his own words and uses theraw/folder the draft references. - Stop Writing Passive Documentation (DDS) – Alper Kinali, Apr 2026. “Passive documentation… is a critical point of failure”; agents “lack context, they hallucinate.” Near-verbatim support.
- Docs as Code — Write the Docs – canonical reference. Authoritative definition: version control, PR review, CI gating, block a merge that lacks docs.
- Mermaid — Introduction – Mermaid project, maintained. Explicitly positions itself against “Doc-Rot”; text-defined, version-controllable diagrams vs. opaque binaries.
- Is RAG Dead? Context Engineering & Semantic Layers – Steve Hedden, TDS, Oct 21 2025. Backs “structured context beats embedding search.”
- Docs for Developers (book) – Bhatti, Corleissen, Lambourne, Nunez, Waterhouse; Apress, 2021.
- Why we use “docs as code” — GOV.UK – Jen Lambourne, GDS, Aug 25 2017.
- Squarespace’s docs-as-code journey – Squarespace Eng, 2025.
