AI coding agents are the new baseline. But an agent dropped into your repo with no context behaves exactly like a contractor with no onboarding: it re-derives your conventions from scratch, guesses at the patterns, and ships plausible code that quietly violates three invariants nobody ever wrote down. The fix is not a smarter model. It is a wiki written for the machine.
What an LLM wiki is — and isn't
It is not your Confluence, and it is not the human README. It is the context an agent loads before it touches your code: the conventions, the invariants, the "never do X," the architecture decisions and load-bearing weirdness that an LLM cannot infer from the code itself. Concretely, it's the files the tools already look for — CLAUDE.md, AGENTS.md, .cursorrules at the root, an llms.txt for docs — plus deeper documents the agent pulls in on demand.
The test of whether something belongs in it is simple: would a strong engineer who's never seen this codebase get it wrong? If yes, it goes in the wiki. If the code already says it, it doesn't.
Why it matters: the agent is only as good as its context
- An ungrounded coding agent is the same failure mode as ungrounded RAG — confident, plausible, wrong. It reaches for the wrong pattern because it never saw the right one. Answerability comes before retrieval for your code, too.
- The context window is finite and billed. Dumping the whole repo into every turn is slow and expensive, and most of it is noise. A curated wiki is the efficient grounding — a small always-loaded core plus on-demand depth. (The cache-aware instinct, applied to your own tooling.)
- It compounds. Humans and agents read the same source of truth. Less tribal knowledge, faster onboarding — for the new hire and the new agent alike.
How to build one
- Write the unobvious, not the obvious. The code already states what it does. The wiki states what an LLM would get wrong: invariants ("never call the store directly — always through the repository"), naming conventions, the one weird constraint that everything depends on, and why a thing is the way it is. Repeating what the code already says just burns context.
- Keep it in the repo, versioned with the code. Docs in a separate wiki rot the day they're written; docs next to the code change in the same pull request. The agent loads what's in the repo — so that's where the truth has to live.
- Layer it for the context budget. A small root file that's always loaded — the rules that apply everywhere — pointing to deeper, per-area docs the agent retrieves only when relevant. Same discipline as any retrieval system: don't put the whole library in the prompt.
- Generate the map, curate the rules. Auto-generate the structural half — the source-tree, the module map, the entry points. Then a human adds the judgment a machine can't infer. The generated half stays current; the curated half makes it correct.
- Treat staleness as a bug. A stale wiki is worse than none: an agent will follow an outdated rule with total confidence. Update the wiki in the same PR that changes the behavior, and check for drift in CI — the same way you'd catch any other regression.
- Make it answerable. Structure it so the right slice is findable: clear headings, one fact per place, links between related rules. The agent (and any retrieval over it) needs to locate the relevant rule, not read the whole thing.
- Measure it. The wiki is a system, so evaluate it like one: does the agent produce more in-pattern, fewer-rewrite changes with it than without? If you can't tell, you're guessing — and guessing is the thing the eval exists to kill.
How we use it
We keep an LLM wiki in our own repos — a small root instruction file, a generated structure map, and the hand-written rules an agent would otherwise miss — because we build with AI agents every day. An agent with our context produces code that fits the system; the same agent without it produces code we have to rewrite. It's the cheapest leverage in AI-assisted engineering, and almost nobody does it deliberately.
A prompt to build one
You don't have to start from a blank file. Paste this into a coding agent, run from your repo root, and answer its questions — it generates the structural half and stops for the judgment a machine can't infer.
Set up an LLM wiki for this repo — the context an AI coding agent loads before
it touches the code. Goal: capture only what an agent would get WRONG, not what
the code already states. Work in phases, stop for my input where marked.
RULES: write the unobvious, never the obvious. Keep it in-repo. When unsure
whether something is a real invariant vs a guess, ASK — don't invent. A
confident wrong rule is worse than a missing one.
1. MAP (generate): detect stack, entry points, build/test/run commands, and a
skimmable structure map of the top modules. Output as a draft.
2. EXTRACT (ask me): hunt for invariants, "never do X", the one weird constraint
everything depends on, non-obvious conventions, and gotchas in the git
history. Present a numbered candidate list WITH evidence, then STOP and let
me confirm or correct before writing any rule.
3. AUTHOR (layered): a small always-loaded root file (CLAUDE.md or AGENTS.md —
match what's here) with the rules that apply everywhere + the commands +
pointers to deeper per-area docs pulled in on demand. Each rule: the rule,
then one line of WHY.
4. VERIFY: re-read as an agent with zero context — is each rule findable,
unambiguous, non-redundant with the code? Then give me 5 concrete questions
about this codebase the wiki should now answer in one hop, and flag any it
can't. Add a staleness rule: update this file in the same PR that changes
the behavior it describes.
Then measure it: run a real task once with the wiki loaded and once without, and compare how well each followed your conventions and how many rewrites you'd need before merge. If the wiki doesn't move that needle, it's documenting the obvious — go back to step 2 and find the rules that actually bite.
AI can write the code now. The bottleneck moved upstream — to context, to what the agent knows about your system before it starts typing. The LLM wiki is that context, written for the reader that now does most of the work. Build it the way you'd build any grounding layer: in the repo, layered, current, answerable, and measured.
The model is a commodity. The context is yours — so write it down, for the machine.