Rules

What this layer is: plain-text files Claude reads at the start of every session. They tell it how you work. Why it matters: without them you repeat yourself every session. With them, a new session behaves like the old one.

Core (everyone)

Four files, four levels

Claude reads every CLAUDE.md on the path from the folder you start in up to the top, plus your user file.

Rule of thumb: put a line at the highest level where it is always true. "Always commit and push" is user-level. "Ridge ads start PAUSED" is project-level.

How to write a rule

1. One rule, one sentence.
2. Add a one-line why. The why lets Claude handle cases you did not think of.
3. Say what to do, not only what to avoid.
4. Use {{PLACEHOLDERS}} in templates, real values in your copy.

Bad: "Be careful with email." Good: "External email = draft only. I press Send. Why: a sent email cannot be taken back."

The keyword router

The workspace file has a table: "when I say X, read project Y's CLAUDE.md first, do not ask." This is what makes "check on ridge" work without you saying where the files are. Add one row per project, with synonyms you really use. See example/Work/CLAUDE.md.

Keep it short

Every line is loaded in every session and costs attention. Target: user file under 150 lines, workspace under 100, project under 60. If a section needs more, link to a doc.

Setup steps

1. Copy templates/claude-md/user.CLAUDE.md to ~/.claude/CLAUDE.md. Fill every {{...}} or delete the line.
2. Copy machine.CLAUDE.md to ~/CLAUDE.md and workspace.CLAUDE.md to ~/Work/CLAUDE.md.
3. For each project, copy project.CLAUDE.md into the project folder.
4. Start a new session and ask: "What rules are you following?" Check it lists your rules.

Advanced (developers)

• Precedence. More specific files are read later and win on conflict. Write conflicts out; do not rely on it.
• Imports. A CLAUDE.md can pull in another file with @path/to/file. Use it to share one rules file across repos.
• Symlink shared rules across accounts. ln -s ~/.claude/CLAUDE.md ~/.claude-work/CLAUDE.md. One edit, every account. See docs/ multi-account notes.
• Rules vs hooks. CLAUDE.md is advice. Claude can still slip. For "must never happen" things (force-push, deleting a folder, spending money), add a hook or a permission deny in settings.json. Pair the written rule with the enforced one.
• Version it. Keep workspace and project CLAUDE.md files in git. Keep the user file in a dotfiles repo. Never put secrets in them: name the file path where a secret lives, not the secret.
• Test a rule. Start a fresh session, trigger the situation, and see what it does. If it fails, make the rule shorter and put the why next to it.
• Be explicit about what does not exist. "The old monorepo was deleted, do not assume it exists" prevents long wrong searches.

Lessons from real use

• Rules that lived only in chat were forgotten. A preference given in conversation vanished next session. Rule: when you correct Claude twice, write it into CLAUDE.md or memory the same day.
• A skill said "ask in text", the user wanted popups. The skill won. Rule: write "this overrides any skill" next to rules that must beat skills.
• A long rules file was ignored in parts. Rules buried in paragraph 12 were skipped. Rule: one line per rule, group by theme, cut anything you cannot explain a why for.
• Wrong-side facts. Work facts got saved into a personal project. Rule: the machine file lists which folder each account owns, and says "write facts to the correct side".
• Assumed repos. Claude searched for a repo that had been split and deleted. Rule: the project file states what exists and what does not.