Guide
How to write a CLAUDE.md that reflects how you actually work
A good CLAUDE.md is short, specific, and made of things you have already been burned by. Writing one takes an afternoon. Keeping it true is the real work.
Ahmet Karaca ·
What it is for
Claude Code reads CLAUDE.md at the start of a session — the one in your home folder for every project, and the one in the project folder for that project. It is the only thing you are certain it sees before it starts working, which is why it is worth getting right and worth keeping small.
What belongs in it
- Things you have corrected more than once. If you have said "no, ask first" twice, it is a rule.
- Boundaries: what must never happen without asking — deleting, pushing, paying, sending.
- How you want answers: length, format, language, what not to pad.
- Pitfalls that cost you an hour once: the environment variable format, the build flag, the platform quirk.
- Commands it cannot guess: how to run the tests, how to build, where the fixtures come from.
Write the reason next to the rule. A model that knows why you ask before deleting will also ask before overwriting; a model that only knows "never delete" will not.
# How I work - Ask before deleting files or running reset commands. (Lost a folder of drawings to a cleanup once.) - Plan in a few lines before touching more than three files. - Formulas over hard-coded numbers: base * level^2.2, not 340. - Short answers. No closing pleasantries. # Pitfalls - Railway env vars are Section__Key, double underscore. - Flutter web needs vercel.json rewrites to index.html.
What to leave out
- Anything the code already says. It can read the code.
- Aspirations. "I value clean code" changes nothing; "split a file before it passes 400 lines" does.
- Project status that will be stale next month. Put it somewhere that is expected to change.
- Essays. Every line is loaded in every session; a page of prose is paid for every time.
The hard part is keeping it true
The first version is easy, because you write what is on your mind. The rules that matter most are the ones that were not: you only discover them when something goes wrong, and at that moment you are fixing the problem, not editing a file. So the file collects the obvious and misses the real.
Then it drifts. A preference from last spring keeps being obeyed after you changed your mind. Two lines quietly contradict each other and the model picks one. Nothing in the file tells you which rules are still true, or what they were based on.
A practical habit: when you correct Claude, ask whether the correction is a rule. When you open the file, delete one line that is no longer you.
Where Coredence fits
Coredence writes this file's content from the evidence instead of from memory. It reads your Claude Code sessions — especially the moments you corrected it — and your git history and notes if you allow it, and distils rules like the ones above. Each rule keeps the messages it came from, its confidence is computed from how often it held, a rule seen once stays a draft, and contradictions are asked rather than resolved for you.
It hands the result to Claude Code as a skill and to every MCP client through a read-only server. Your own CLAUDE.md stays yours; Coredence is the part that keeps up.
You can see what it produces on a made-up person's identity in your browser, without installing anything.
Try it in your browser