Claude.Md GLOBAL

Global CLAUDE.md

A compact global `CLAUDE.md` for [Claude Code](https://docs.claude.com/en/docs/claude-code). Place it at `~/.claude/CLAUDE.md` and it loads in every session, in every project, before any project-level `CLAUDE.md`.

This is not an "ideal" file — it's a compact operational contract, assembled deliberately and validated through several rounds of expert critique. Below is why it looks the way it does, and what every line means.

---

English

Why a separate global file

Claude Code reads two tiers of `CLAUDE.md`:

• Global (~/.claude/CLAUDE.md) — personal preferences that travel with you across any project.
• Project (/CLAUDE.md) — team and stack conventions specific to one repository.

The split is simple: anything about *you* (chat language, tone, working style, personal red lines) belongs in the global file. Anything about *the project* (architecture, stack, testing, team conventions) belongs in the project file.

Why the file is short

The global `CLAUDE.md` costs tokens **every session** and **after every `/compact`**. Rough estimate from [claude-code#34556](https://github.com/anthropics/claude-code/issues/34556): a ~3100-token file across 10 compactions per session = +31k tokens of overhead just to re-read it. So:

• Anthropic and community consensus as of April 2026: keep it within 50–100 lines (HumanLayer argues closer to 50).
• This file: 31 lines, ~520 tokens, 4 sections, 18 rules + 1 summary anchor.
• Every line must earn its token cost. The bar for inclusion is "this actually changes model behavior," not "this feels nice to read."

Design principles

1. Personal → global, team/stack → project. No stack-specific rules (pnpm, Python 3.12, TypeScript strict) in the global file — they fire in a Go repo where they don't apply. The only acceptable exception is conditional defaults of the form "unless project config says otherwise."
2. **Positive phrasing ("Prefer X") is more robust than bans ("