My CLAUDE.md explained - a tour of my personal AI operating system

CLAUDE.md is a plain markdown file that sits at the root of my Obsidian vault. Every time I open Claude Code in this directory, Claude reads it automatically before doing anything else. It is the closest thing I have to an instruction manual for my brain - it tells Claude where things live, how I like things done, and what the rules are.

Think of it like onboarding a new assistant. Instead of re-explaining the same thing every session ("articles go here, people notes go there, use British English, never use em dashes"), I write it down once and the AI reads it on every session start.

Why I built it this way

Three things drove the design.

My vault is my operating system. Notes, tasks, calendar, contacts, recipes, coursework - all of it lives in one Obsidian vault. If Claude does not understand the structure, it cannot help me. The alternative is re-orientating the AI on every session, which is friction that compounds badly over time.

I want signal, not ceremony. I would rather Claude just do the thing than ask five clarifying questions. CLAUDE.md front-loads all the context so it can act immediately.

Consistency compounds. When every note follows the same frontmatter schema, uses the same tags, lives in the right folder - the vault becomes queryable. Dashboards work. Backlinks surface real connections. The system gets smarter over time.

The folder structure layer

Every folder has a purpose and a number prefix so it sorts predictably. The main hub is a general notes folder. There is a separate folder for external sources (articles, podcasts), a contacts folder for my personal CRM, and an autonomous task system. The numbers are not aesthetic - they ensure Claude and I never have to guess where something belongs.

The rule in CLAUDE.md is simple: new file, wrong folder is a mistake. The file names the right folder for every content type and the condition under which a new folder is ever justified (almost never).

The frontmatter schema layer

Every note has a YAML frontmatter block with Source, Author (CamelCase, no spaces), Topics (from a fixed allowed list), and a short Description. This is not fussiness - it is what makes the "Related notes" query work. The query scores other notes by shared author, overlapping topics, and matching tags. Without strict frontmatter, none of it functions.

The allowed Topics list is fixed and lives in CLAUDE.md. The moment you allow free-form topics, the query silently returns nothing for half your notes because "AI and Technology" and "AI & Tech" do not match. One canonical list, enforced by the file.

The skill routing table

This is the heart of the file. I have built a library of custom skills - slash commands - for specific tasks. One for processing articles, one for logging outreach, one for weekly class prep, one for building contact cards, one for drafting emails in my voice.

The routing table tells Claude which skill to use for which content type. When I paste an article, it knows to run the article skill. When I describe a meeting I just had, it knows to run the transcript skill. I do not have to remember which command to call - I describe what I want and the table does the routing.

Most people using Claude Code just tell it what to do in the moment. The routing table codifies that mapping so the tool becomes predictable. It is a small thing that has a large effect on how much trust I place in the output.

The autonomous dispatcher layer

I have a small machine running 24/7 as a home server. It watches an inbox folder and processes any new capture automatically - enriching it with context from my vault and calendar, then moving it to an active queue. The whole loop runs without me in the loop for routine items.

This CLAUDE.md section tells every Claude session two things: do not manually process items the dispatcher handles, and every action should cross-reference the active queue. It makes the whole vault task-aware without requiring me to track state manually.

The dispatcher is also where the risk lives. An autonomous system that can write to your vault needs guardrails. CLAUDE.md documents exactly which operations require human sign-off and which can run headlessly. The line between those two categories is the most important thing in the file.

The writing style layer

I wrote my own style guide built from real emails and messages. CLAUDE.md forces Claude to read it before drafting anything. Key rules: no em dashes, British English, "v" for "very", lead with the idea not yourself, write then cut by a third, never re-explain someone's own work back to them.

The goal is that drafts actually sound like me, not like generic AI prose. There is a feedback loop too - after every draft I score it 1-5. Every few scores, the drafting skill distils patterns into a principles file that gets read before the next draft. The system learns my taste incrementally.

The calendar and location layer

Claude can read my Google Calendar via Python scripts that replaced an older, flakier approach. A set of rules teaches it to read context from the calendar - which commitments are movable, which are fixed, and what kind of day it is - so scheduling suggestions start from reality rather than a blank diary.

This matters when the scheduling tool is proposing meeting slots or when a draft needs to reference where I am. Rather than making Claude ask, CLAUDE.md encodes the inference rules so it can reason about location without interrupting.

The contacts CRM layer

I built a contact relationship manager inside Obsidian. Every person I interact with gets a note with frontmatter tracking last interaction date, interaction count, and relationship strength (New, Familiar, Active). It updates automatically when I process outreach - the relevant skill finds or creates the contact note, increments the counter, and appends to the interaction log.

CLAUDE.md documents the schema and the automation so any Claude session can maintain it correctly. The key rule: only ever append or update a contact note, never rewrite it. Rewriting destroys history.

The critical rules layer

A few hard constraints I have learned the hard way.

Never use horizontal rules (---) in note bodies - they cause frontmatter parsing to break. Wiki-links must match exact filenames including accents and emoji. The "Related" query block must be copied verbatim from the template - a single character change breaks it silently. Leave the Notes section empty - that is for me to fill in by hand.

These are guardrails against failure modes I have hit before. CLAUDE.md is where I encode lessons so I do not re-learn them.

The philosophy

CLAUDE.md is not really an AI prompt. It is documentation of how I work, written for a collaborator who is patient enough to read every line. That collaborator just happens to be an LLM.

The interesting thing is that writing it forces clarity. I could not describe the skill routing table until I actually had one. I could not write "never use em dashes" until I had noticed the pattern in my own writing. The act of onboarding an AI made me onboard myself.

It is also incremental. The file has grown section by section as I have built new automations - the task dispatcher, the CRM, the urgency scorer, the server. Every new capability gets a paragraph. Over time it becomes a living map of a personal operating system.

What I have not seen others do

A skill routing table that maps content types to specific slash commands. Most people tell Claude what to do in the moment - I have codified the mapping so the tool itself becomes predictable.

Day-zone inference rules built from actual life patterns. Claude reasons about physical location without being told, because the calendar events encode the answer.

An autonomous dispatcher running on a headless server, processing captures without me in the loop. CLAUDE.md is what makes every other Claude session aware of it - the sessions do not need to know how the dispatcher works, just that it exists and what it handles.

A self-improving draft feedback loop. The system learns taste over time, not through retraining but through a distilled principles file that gets updated every few sessions.

Vault-first CRM with automated interaction logging. No third-party tool - just markdown files with frontmatter and a query that surfaces the right contacts.

Who this is for

If you use Claude Code and have ever thought "I wish it knew where things go in my vault" or "I wish I did not have to re-explain my conventions every session" - CLAUDE.md is the answer. It is free, it is just a markdown file, and it compounds. Every hour you spend on it saves ten later.

The frontmatter schema, the skill routing pattern, the writing style section - most of it is transferable. The vault paths and personal rules you would adapt to your own setup. The architecture is what matters, not the specifics.

← Back to Writing