Your CLAUDE.md Is the Onboarding Doc You Never Wrote

TL;DR: A CLAUDE.md is not configuration. It’s the onboarding doc your team never wrote — the tribal knowledge that normally lives in one senior engineer’s head, written down at last because something finally needed to read it. The twist: your “second brain” was never really for you. The agent is the first reader your notes have ever had, and the first one that acts on what it reads.

For about a decade we told ourselves a story about personal knowledge management. Capture everything. Link your notes. Build a second brain. Most of us built the vault, filled it for three weeks, and never opened it again. The notes were real. The reader never showed up.

The reader showed up. It’s just not human.

When you write a CLAUDE.md — or an AGENTS.md, or whatever your coding agent reads at the start of every session — you are doing the thing PKM always promised and rarely delivered: writing knowledge that gets consumed. Not filed. Consumed, on every task, by something that turns it into action. And the moment notes have a reader that acts, everything about how you should write them changes.

What a CLAUDE.md actually is

A CLAUDE.md is executable tribal knowledge: the undocumented operational facts about a codebase, written down because an agent now needs them to work, and loaded into context on every session so they actually get used.

That’s the whole thing. It reads like config — a markdown file in your repo root — but it isn’t. Config tells a machine what to do. A CLAUDE.md tells an agent what you know that isn’t in the code: the port another local app squats on, the test that fails for unrelated reasons, the directory you must never touch, the deploy that happens on push and not via the obvious command. The knowledge a new hire extracts painfully over their first month by breaking things and asking in Slack.

Anthropic’s own guidance lands in the same place: the question to ask when writing one is “what would I tell a new engineer in their first five minutes on this repo?” That is not a config prompt. That is an onboarding doc.

The onboarding doc you never wrote

Here’s the uncomfortable part for anyone running a team. You almost certainly do not have a good onboarding doc for humans. Nobody does. Onboarding docs rot the instant they’re written, nobody is incentivized to maintain them, and the real knowledge stays where it always was — in the head of the one person who’s been there longest. We’ve all just agreed to call this “ramp-up time” and absorb the cost.

The agent doesn’t accept that arrangement. It has, in Karpathy’s memorable phrase, anterograde amnesia — no memory across sessions by default. Every session is its first day. So either you write the knowledge down or the agent relearns the codebase, badly, every single time. The economics that let human onboarding docs rot — “we’ll just have someone explain it” — collapse, because there’s no someone, and the explaining happens fifty times a day.

So teams that maintain a good CLAUDE.md are doing something they never managed to do for people: they’re keeping an onboarding doc alive, because a daily user finally forces the maintenance. That’s not a side effect to shrug at. Tribal knowledge becoming executable and version-controlled is one of the quietly large shifts in how engineering orgs work, and most teams are doing it by accident while thinking they’re just configuring a tool.

If you want the tactical version of how one of these files evolves under real use, I wrote about what my CLAUDE.md looked like after 50 commits — what stayed, what got cut, and why most of it was operational trivia no human doc would have bothered to record.

CLAUDE.md vs. the team wiki

This is where people get confused, so let me be precise about it. A CLAUDE.md is not your Confluence. The two hold different knowledge for different readers, and conflating them is how you end up with a 4,000-line CLAUDE.md that the agent ignores.

The rule that falls out of this: put in CLAUDE.md only what the agent needs to not screw up, and put it there because leaving it out has a visible cost. Everything conceptual — why the architecture is the way it is, the history, the org chart — belongs in the human wiki, which will continue to rot, because nothing forces it not to. The lesson isn’t “make your wiki more like CLAUDE.md.” It’s that the forcing function is what was always missing, and the agent supplies it for free.

When a markdown file beats your vector database

The second-brain crowd’s reflex is to reach for retrieval. Embed everything, stand up a vector store, RAG it back. And for a genuinely large corpus, you’ll need that. But the interesting claim — Karpathy’s, and increasingly mine after running it — is that the threshold where you need it is much further out than people assume.

His framing is a literal wiki the agent maintains: a git repo of markdown, a read-first index.md that catalogs every page in one line each, and the model just… reads the index and opens what’s relevant. No embeddings. The analogy he uses is sharp: Obsidian is the IDE, the LLM is the programmer, the wiki is the codebase. It works, he argues, up to hundreds of pages before retrieval earns its keep.

Why does the dumb version hold up so well? Because a curated index is a precise, deterministic table of contents, and a context window is now big enough to swallow what the index points to. RAG trades fidelity for scale — it can miss the right chunk, surface the wrong one, and needs reindexing every time you change embedding models. A markdown wiki trades scale for fidelity: perfect recall of exactly what you wrote, version history for free, nothing to drift. (When you do cross into needing real retrieval, that’s its own discipline — I got into the weeds of running pgvector RAG in Phoenix and the arcana is real.)

The decision, stated plainly:

• Direct-load it (CLAUDE.md, imports) when it’s a small, always-needed core. Repo rules. The handful of facts every session needs.
• Link it (a wiki of cross-referenced markdown) when the corpus is up to a few hundred pages and the connections between notes carry meaning.
• Embed it (RAG) only when you’ve genuinely outgrown what an index-and-open workflow can hold.

Most people start at the bottom of that list and should start at the top. Reach for the vector DB last, not first.

So what do you actually put in it

Keep it to the things that are true, non-obvious, and costly to get wrong:

• Operational landmines. The port conflict, the flaky test, the build that lies, the directory that’s gitignored-but-load-bearing. The stuff that makes a new session waste twenty minutes rediscovering a fact you already knew.
• Conventions the code doesn’t enforce. “We use this tag taxonomy.” “Never commit to main directly.” “Format on save or precommit trips.” Rules that live in people’s habits, not in a linter.
• The shape of the workflow. How to run things, what to run before committing, what ‘done’ means here. This is where a CLAUDE.md shades into the rest of your agent setup — skills, not just one mega-file, each loaded only when its task comes up, so the always-on core stays lean. My daily agentic workflow leans on exactly that split.

And keep it short. Every line you add is loaded on every task and competes for the model’s attention with the actual work. A CLAUDE.md that tries to be the wiki becomes noise the agent learns to skim. The discipline is the value. This is “context engineering” — the term Karpathy popularized for filling the context window with just the right information for the next step — applied to the most mundane artifact in your repo.

The reader that never forgets

There’s a longer arc here that matters if you lead engineers. We’ve spent years worried about bus factor — the senior who carries the codebase in their head, the knowledge that walks out the door when they do. The standard fix is “write more docs,” and the standard outcome is docs nobody maintains. I’ve argued before that the AI shift is quietly changing how we grow senior engineers at all; this is the other half of it.

When the tribal knowledge has to be written down for the agent — and stays written down because the agent breaks without it — the bus factor problem gets attacked from a direction it never has been. Not “please document this.” Instead: the documentation is load-bearing, version-controlled, and decays visibly the moment it’s wrong, because something fails immediately.

That’s the inversion worth sitting with. The second brain was never going to work as long as the only reader was a future version of you who would never actually open it. The notes needed a reader who shows up every day, never gets bored of the maintenance, and turns what it reads into action. That reader exists now. It just isn’t human — and it’s reading your CLAUDE.md right now, treating your offhand operational notes as the most important onboarding doc your team has ever written.

Write it like you mean it.