The CLAUDE.md Hierarchy

I have two projects: a professional training portal (blue palette) and a personal site (green/cream palette). For weeks, Claude would occasionally use the wrong colors. I’d correct it, it would happen again next session. The corrections weren’t sticking because they lived in conversation — they died when I typed /clear.

The fix is a three-tier context system:

Global (~/.claude/CLAUDE.md): loads into every session on every project. My name, my role, universal preferences like "never use pure black" and "always TypeScript." About 30 lines. Every line costs context window space on every project, so keep it lean.

Project (./CLAUDE.md at repo root): loads only for this codebase. Color palette with exact hex values, spacing rules, forbidden patterns, deployment targets. This is where "use #003763 for headers, NEVER use #3B412D" lives. About 150-200 lines.

Session (conversation): what you’re working on right now. Dies on /clear. Don’t put anything here you want to survive.

The compounding effect is the real payoff. Every time Claude makes a mistake and I correct it, I add the correction to the right tier. Week 1: "don’t use sticky toolbars." Week 2: "pt-12 after every toolbar." Week 3: "never use CSS padding shorthand — it kills Tailwind pt-* classes." By week 8, first-pass output quality is dramatically higher because the constraint set is tighter. Sessions are 2x faster than week 1.

What I tried that didn’t work: applying enterprise governance frameworks (Databricks Five-V’s, Google Cloud iterative eval) to improve CLAUDE.md. Those are designed for large-team data governance, not single-user agent instructions. CLAUDE.md works best flat, scannable, and concrete. Hex codes, not color philosophy. Spacing values, not spacing rationale. If removing a line wouldn’t change Claude’s behavior, it’s noise.