CLAUDE.md

CLAUDE.md is a file of project rules. It lives directly in the repository, and Claude reads it automatically at the start of each conversation. It doesn’t generate itself. I write it myself—either I just tell Claude “add to CLAUDE.md that...”, or I have Claude generate the first version by running /init, which has him read through the project and write the rules down.

What goes in it. Absolute directives: Session Init at the start of every conversation (load memory, check for drift), Skill Pipeline (nine-step process without exceptions), Discipline Rules (hard-won lessons). The list of MCP servers connected to him, background skills, the archive of what I don’t do anymore so Claude doesn’t waste energy on it.

The most important part: rules and lessons. For example, “Verify state with a concrete probe, never just by looking at URL and page title.” I learn that gradually, and CLAUDE.md is where we write it all down. “One commit per change.” That’s from the time I threw three things together and spent three days figuring out what broke where. These are five-line statements, but they’re worth months of operation.

Automatic Memory

Memory is separate from CLAUDE.md. While Claude works, he writes down notes about what happened, what to remember next time. These notes live in MEMORY.md, saved on my machine. Each session reads the first 200 lines—so it’s not infinite, I have to keep it clean. When MEMORY.md grows past 25 kilobytes, it’s time to clean it up and archive it.

What that looks like in practice. I tell Claude, “Update MEMORY.md: we added new content to the web today.” He writes something like, “2026-06-09: Euphronic web—added 4 new pages, Vercel deployment OK, user approved design. Next phase: newsletter setup.” The next time I talk to Claude, he already knows where we left off.

Why I do this: an agent by himself is like a person with amnesia. After each conversation, he forgets everything. Sessions go into history, but he doesn’t find them on his own. So alongside him, I keep a notebook. Notion is one form of that notebook (see My Stack), Obsidian is deeper (for things I’ll search for later). MEMORY.md is the fastest version—it loads at the start of every session and reminds Claude of the context.

Settings

Settings.json is one-file configuration. It says which model I want (I use Opus 4.8), how Claude should approach things (which MCPs he has access to). When I want Claude to connect to something new—say Notion—I tell him and he updates the settings himself.

There are permissions in there—what Claude can do on his own and what needs my approval. What he can’t do: delete anything without confirmation, push to main without my OK, send emails on my behalf without review. I have Gemini API turned off because autonomous mode was pulling costs unnecessarily.

CLAUDE.md describes how to work. Settings.json is the bridge to the outside world: which servers Claude has access to, which tokens, where files live. Claude updates it himself when I tell him to.

Hooks

Hooks are things that happen automatically. Think of them as signals. “Whenever Claude edits a file, format it.” Or: “At the start of a session, print all the rules from CLAUDE.md.”

I have three active hooks. PreToolUse—that runs before an action, checks what’s about to happen. UserPromptSubmit—when I type something in chat, it reminds Claude of the directives and what he should think about. Stop—when a session ends, it audits whether everything’s saved.

They work like a safety net. I’ve had moments where Claude didn’t read CLAUDE.md and kept going without context. Hooks are meant to prevent that. They’re loud reminders (I see them in chat) and also running in the background.

Commands and Statusline

Slash commands are shortcuts. “/init” means “read the project and write CLAUDE.md.” “/compact” means “compress context.” “/clear” is reset. The statusline is the row at the bottom showing model, effort, and remaining context tokens.

Honestly, I rarely use commands. /init once a month. I turned off /compact—I just tell Claude “context is filling up” and he decides what to archive. I watch the statusline when I want to know how much space is left. It also shows whether background processes are running—useful when I’m thinking “why is this taking so long?”

Permissions

Permissions determine what Claude can do on his own and what needs to wake me up. “Delete a file without warning”—no, he has to ask. “Push to GitHub”—no, I want to see it. “Write a note in Notion”—that’s fine.

Locks make sense in four places: files (what he can change), deployment (what goes straight, what waits for my OK), secrets (API keys only when needed), big decisions (architecture, removing old paths).

I set it in settings.json. I tell Claude “these files are read-only” or “warn me before pushing” and he knows. It’s prevention. I trust him not to mess up, but it’s better not to have to watch.

MCP Configuration and Teams

MCP servers are like USB drives I plug into Claude. One is GitHub—he pulls code, makes commits. Another is Notion—he reads notes, writes them back. A third is YouTube, a fourth is email, a fifth is web scraper. Overall I have 113 skills, all connected and running in the background.

Configuration: I tell Claude where the servers are (URL, token). He finds them and checks they work. Settings.json lists which ones I want available. To add a new MCP, I add it to settings and Claude activates it.

I start agent teams when I have more than three independent tasks. “Get 5 specialists and split this among them.” One reads GitHub, another writes content, another tests, another watches security, another looks at metrics. They work in parallel. When they’re done, I see all results at once. It’s like running a mechanic team—one on the engine, another on the fuel, another on brakes, all at once. Otherwise it would take 5 times as long.

It’s not required. I do it for bigger things. Normally Claude works alone. But it pays for itself: if I look at something big and it seems like an hour of work, I spin up a team and it’s done in 15 minutes. In the Max plan, that math works out when you have more than 2 or 3 tasks at once.

All of this together is one thing: talking to Claude like he’s a mechanic team. I say what I want. I assemble the team from agents, MCP servers, rules, and memory. None of it is magic. For what that looks like in practice, see My Stack.