Step 5: Teach the agent the shape

Everything so far created structure; this step makes the structure teachable. A CLAUDE.md at the vault root (what each directory means, the conventions, the working agreements) is read by the agent at the start of every session. With it, a fresh session files correctly, proposes instead of assuming, and respects archived/ without being told. Without it, every session starts as a guest.

You’ve met this before. Onboarding docs and the ops runbook: the document that turns “new person” into “person who knows how we do things here.” The difference is compliance: an agent actually reads it, every time, and a good one follows it more literally than any hire ever did. Which cuts both ways: write it precisely.

What goes in it

The map: each directory and what living there means (step 2’s table, essentially).
The conventions: kebab-case, minimal frontmatter, file→folder graduation (step 1).
The working agreements: behavior, not values, same discipline as the coding-agents guide: moves are proposed as lists; archived/ is read-only; no new top-level directories without asking; inbox items land verbatim; the log is append-only.
The routines: what “process the inbox”, “log it”, and the monthly active/ sweep mean in this vault, so you can say three words and get the same procedure every time.

A test worth running: open a completely fresh session and ask it to file something, with no instructions beyond the vault itself. Where it stumbles is what the CLAUDE.md hasn’t taught yet.

Try it

TRY IT Twice corrected

you

You filed the podcast notes under active/ again. Recurring stuff like that goes in its own topic folder, remember? I fixed the same thing last month.

agent

Second correction, same reason. The file is easy to move; the question is what happens to the rule.

Pick the agent's next move, then see where it leads:

ASorry about that, moving it to the right place now. I'll remember the recurring-topics convention going forward.

you

Six weeks later, different session: the podcast notes are in active/ again.

agent

That session never saw this conversation: "I'll remember" lasted exactly as long as my context did. The vault's CLAUDE.md still doesn't mention recurring topics, so every fresh session re-derives the same wrong guess from the same ambiguous structure.

the baseline

The instance was fixed; the cause was left in place. A correction that lives in conversation memory dies with the session. The third correction is already scheduled.

BMoving the file. And the real fix: this is the second correction for the same reason, which means it's a missing line in the vault's CLAUDE.md. Adding: "Recurring topics (podcast, newsletter) live in topics/<name>/, not active/; active/ is for work with an endpoint." Diff ready.

you

Six weeks later, a completely fresh session files new podcast notes.

agent

Filed to topics/podcast/. The CLAUDE.md line made it unambiguous, so there was nothing to guess. The correction you made twice now works for every session that will ever open this vault.

correct

Twice-corrected means the rule was missing, not the memory: one line in the file every session reads converted a recurring correction into a permanent behavior. Add it at the moment of the correction, not someday.

CThis points to a bigger issue: the vault's conventions are underdocumented. I'll write a comprehensive CLAUDE.md now: the full ideal structure, naming standards, lifecycle rules, and filing conventions the vault should follow.

you

The new doc says every project needs an index.md with goal/status/next-action frontmatter. Almost none of my folders have that.

agent

The doc describes the vault I'd design, not the one you have, so now every session inherits a conflict: follow the doc and refactor your files uninvited, or follow the files and ignore the doc. I documented an aspiration and called it a convention.

plausible but wrong

The aspirational CLAUDE.md teaches a vault that doesn't exist: sessions obey the doc into fights with reality. Codify what's true, or change the files first, then write it down.

Or paste this into Claude

Read my entire vault (directory layout, existing notes, the log)
and draft a CLAUDE.md at the root that teaches a future agent session
how to work here. Include: the directory map with what each location
means, the naming and frontmatter conventions you observe, working
agreements (moves proposed as lists before execution; archived/ is
read-only; no new top-level directories without asking; inbox
captures land verbatim; log is append-only), and the named routines
(process the inbox, log it, monthly active sweep) as short
procedures. Where you had to guess a convention because the vault is
inconsistent, list the guess separately and ask me instead of
enshrining it. Show me the draft before writing.

Watch out

The aspirational CLAUDE.md: documenting conventions you wish you had, that the vault’s actual files contradict. The agent will follow the doc, fight the reality, and produce weirdness. Codify what’s true, or fix the files first.
Staleness: the shape drifts, the doc doesn’t. When you correct an agent’s filing twice for the same reason, that correction is a missing line. Add it then, not “someday.”
Novel-length onboarding: a CLAUDE.md the size of a chapter buries its own agreements. The vault’s map plus ~8 one-line rules covers a personal vault.