Let your coding agent own the docs

Every team I've worked with in twenty years has had a wiki. None of them were up to date. Not because people were lazy — because keeping the wiki current was nobody's actual job. The docs lived in Confluence, the code lived in git, and the two drifted apart one pull request at a time.

Coding agents made this worse, not better. Give the agent too little context and it guesses. Give it the whole codebase and it gets slow, expensive, and oddly less accurate. I've done both. Neither is great.

So here's what I'm proposing: put a small markdown wiki inside the repo, and make the agent maintain it. I built a sample repo so you can see the whole thing working.

This isn't my idea — it's a pattern

In April, Andrej Karpathy published his LLM Wiki gist. The idea is simple: instead of re-deriving answers from raw sources every session, the agent builds and keeps a set of small, linked markdown pages. In June, Google Cloud turned it into a spec — the Open Knowledge Format, or OKF.

Neither is a product. You don't install anything. Claude Code, or whatever agent you already use, does the work.

Three parts, all in the repo

• A router. CLAUDE.md (or AGENTS.md) at the root, under 150 lines. What the product does, a map of the code, the conventions that matter, and an index of the wiki. It's the only file the agent always loads.
• A wiki. A docs/ folder with one small page per topic — architecture, data model, one page per module, conventions, gotchas. Each under 200 lines.
• Rules. A few standing instructions that make the wiki the agent's job. Read the relevant pages before coding. Update them after.

That's the payoff. For any task, the agent reads the router and pulls in two or three pages. Not the whole repo. And there's a second payoff I didn't expect: onboarding. A new developer opens the repo and just asks the agent how things work.

What a page looks like

Plain markdown with a small YAML header. OKF only requires type. The rest tells the agent what the page covers and how fresh it is.

---
type: concept
module: deals
updated: 2026-09-14
status: current
---

# Deals

- Amounts are integer cents. Never floats.
- A deal can only be won from proposal.

Write pages for machines. Short facts, no filler, business rules stated out loud. If you run a few repos, CLAUDE.md can also link to shared company standards, so every repo follows the same patterns.

The part where every wiki dies

Keeping it current. So this gets its own mechanism: docs become part of the definition of done. Whoever makes the change — agent or developer — updates the affected pages in the same pull request as the code.

A PR checklist is the minimum. In the sample repo I went one step further: a CI check that fails any PR touching src/ without touching docs/, unless it has a docs-not-needed label. Crude, but it works.

Two prompts do all of it

The first is a bootstrap prompt you run once. It reads the code module by module, pulls in your old Confluence or Notion pages, and writes the router and the wiki. Where the old docs disagree with the code, the code wins.

The second is a set of standing rules that live in CLAUDE.md:

- You own this wiki. Keeping it accurate is part of every task.
- Before coding, load only the pages relevant to the task.
- After any change, update the affected pages and their
  'updated' date, in the same branch.
- If the code contradicts the docs, trust the code and fix the docs.

Both are in the repo, ready to paste: bootstrap.md and standing-rules.md.

How I'd roll it out

Start with one repo. Run the bootstrap prompt — that's about a day, and most of it is the team reviewing what the agent wrote. Then spend a few hours adding the rules and the PR check. Then pilot it for two sprints on real tickets before you touch the other repos.

Try it

Clone the sample repo, run npm test, open your agent and ask: "Can a deal skip from lead to proposal?" It should answer from docs/pipeline.md without reading the codebase. Then ask it to add a new stage, and check that the docs change with the code.

I've wanted this for years. The knowledge lives in git, next to the code, reviewed like code. The agent's context stays small, so the bill goes down. And the docs stay current because updating them is part of the job — not a chore someone promises to get to next sprint.

It's just markdown. That's the best part.