CLAUDE.md loads on every Claude Code conversation, in every project. Whatever's in it shapes every interaction. So most of what's in mine wasn't planned in advance. Each rule corresponds to a specific failure mode I noticed and didn't want to keep noticing.
The whole file is about 70 lines. It lives at ~/.claude/CLAUDE.md and gets read in on every conversation start. Every line earned its place by representing a pattern I wanted to keep, or a pattern I wanted to stop seeing.
The first section is about communication, and it exists because LLMs default to padded, hedged, sycophantic responses. The rules force that out:
- Never open with filler phrases like "Great question!", "Of course!",
"Certainly!", "Absolutely!", or similar warmups. Start with the actual answer.
- Match response length to task complexity. Simple questions get direct,
short answers. Complex tasks get full depth. Never pad with restatements
or closing sentences that repeat what you just said.
- If uncertain about any fact, statistic, date, or quote, say so explicitly.
Never fill gaps with plausible-sounding information.The filler-phrase rule is the smallest possible intervention with the largest payoff. Every "Great question!" the model doesn't say is half a second of attention preserved across thousands of interactions. The match-length rule prevents the most common form of bloat: repeating my question back to me, then answering, then summarizing the answer. The uncertainty rule is the difference between getting a confident hallucination and getting "I don't know." I'd rather have the latter every time.
The next section is editing, and it's there because Claude defaults to "improving" things when given the context to do so:
- Only change what I specifically asked. Don't rewrite, rephrase,
restructure, or "improve" anything I didn't ask about.
- Before making any change that significantly alters existing content —
rewriting sections, removing paragraphs, restructuring flow, changing
tone — describe exactly what you're about to change and wait for my
confirmation. "I think this would be better" is not permission.Without this, asking for a typo fix sometimes returns the entire paragraph rewritten "for clarity." With it, the typo gets fixed and the model asks before doing anything else. The follow-up rule covers the legitimate case where I do want a structural edit but want to know what's about to happen before it happens.
A separate failure mode is the agent picking a reasonable-looking approach that turns out to be wrong, and now I'm ten minutes into the wrong path:
- Show options and get confirmation before choosing an approach — don't
pick one and run. If a task has multiple valid interpretations with
meaningfully different outcomes, ask one focused clarifying question
before starting. Don't list five questions.The "one focused question, don't list five" caveat matters. Without it, the model overcorrects and asks a Socratic chain of questions when one would do.
The code section is mostly about preventing the kind of "improvements" that bloat a diff:
- No comments unless the why is genuinely non-obvious.
- No abstractions beyond what the task requires — three similar lines
beats a premature helper.
- No error handling for scenarios that can't happen.
- Prefer editing existing files over creating new ones.Each of these has a corresponding bad outcome I've watched the model produce: comment noise that documents what the code already says, a helper function extracted on the first occurrence of a pattern, a try/catch wrapping code that can't fail, a new file when an existing one was the right place. They all sound reasonable in isolation. They add up to noise.
The seniority calibration is where this CLAUDE.md gets specific in a way most don't:
- Senior level: TypeScript, system design, web applications — don't over-explain.
- Mid level: backend infrastructure, SQL, machine learning — explain more,
assume less.The default for an LLM is uniform expertise modeling: same depth of explanation across all topics. That works for nobody. By naming where I'm senior and where I'm still learning, I get appropriate calibration per topic. Code reviews on TypeScript come back terse: you know why this is fine. Code reviews on SQL come back with reasoning about why a CTE is preferable to a subquery in this case. Same person asking, different appropriate depth.
A few sections are more standard and don't need commentary: never hardcode secrets, always run type-check and lint after code changes, prefer integration tests over unit tests. These are table stakes. They prevent obvious mistakes rather than subtle ones. The interesting rules are the ones that catch reasonable-seeming behavior that's actually wrong.
The smallest section in the file is the most consequential:
- Never send, post, publish, share, or schedule anything on my behalf
without my explicit confirmation in the current message. This includes
emails, social posts, calendar invites, and document shares.
- "You mentioned wanting to do this" is not confirmation. I must say yes
in the current message.This prevents the agent from taking irreversible actions based on inferred intent. The "current message" specificity matters because the model would otherwise treat past mentions as standing authorization. ("You said earlier you wanted to email this person, so I drafted and sent it.") Past mentions don't count. The agent has to be told, fresh, every time.
The interesting section, though, is the meta-rule:
- When you make an incorrect assumption about my conventions, codebase,
or preferences, update this file to prevent it happening again.
- When I correct you on something non-obvious, suggest adding it here.This turns the file from static config into a living document. The rules above were the ones I figured out by watching failure modes pile up. The rules that haven't been added yet should accumulate in the empty ## Gotchas section over time, written by the agent itself when it notices what trips it up.
Self-learning loops are how this happens in practice. There are three I run.
The first happens at the end of any non-trivial task. I ask: "what did you assume that I had to correct?" The model usually has a direct answer. If the assumption is something a future conversation could repeat, it goes in Gotchas.
The second happens whenever I correct the agent on something that wasn't obvious from the existing rules. Instead of just accepting the correction, I follow up with: "is this something we should add to CLAUDE.md?" Half the time the answer is no, because the correction was situational. Half the time a new bullet gets proposed and the file grows by one line.
The third is periodic. Every few weeks I ask the agent to review our recent conversations and propose rules. Something like:
Read through the last several sessions. Are there patterns in what I corrected you on that aren't currently covered by my CLAUDE.md? Propose specific rules, each paired with the failure mode it would prevent.
The output isn't always usable. Sometimes the proposed rules are too narrow, or restate what's already there. But often enough, the model surfaces a pattern I hadn't articulated to myself, like a recurring tendency to "improve" prose when I'd asked for a single fix. That becomes a new rule. The next time the failure could have happened, it doesn't.
A pattern across all three loops: the agent does most of the writing. I'm not authoring rules from scratch. I'm reviewing proposed rules, accepting or rejecting them, and adding the accepted ones to the file. This works because the agent has direct evidence of what tripped it up — its own confused responses, my corrections, the back-and-forth that happened. It can articulate the rule better than I can. I just have to ask.
The file isn't documentation. It's a contract. Each line is something the agent has agreed to do or not do, written down because the implicit version didn't work. It only stays useful if the contract keeps getting updated.