CLAUDE.md Mastery — The Agent Constitution

If you get one thing right in your Claude Code setup, make it this. CLAUDE.md is the file that tells every Claude session — before it reads a single line of your code — what matters, what is forbidden, how you operate, and what it should never do. It is not documentation. It is standing orders.

Every elite operator you will ever encounter has a sharp CLAUDE.md. This lesson teaches you to write one that compounds.

The Hierarchy

Claude Code loads instruction files in a defined order. Understanding the hierarchy tells you exactly where to put each instruction.

Global: ~/.claude/CLAUDE.md Applies to every Claude Code session on your machine, regardless of which project is open. This is where you put universal preferences — your commit email, your branch policy, security rules that should never be violated anywhere. If you have been burned by Claude committing directly to main, put the rule here.

Project Root: ./CLAUDE.md The most important one. Applies to the entire project. Stack, conventions, deploy commands, what files to ignore, the branch policy for this specific repo, any constraints specific to this codebase. Read on every session start.

Nested: ./src/api/CLAUDE.md Scoped to a subdirectory. When Claude is working inside src/api/, it picks up these instructions in addition to the project root. Use this for module-specific constraints — "this package never makes external HTTP calls" or "all functions here must have JSDoc" — that would pollute the top-level file if placed there.

Tiered File Importance

On any project with more than 20 files, context is a resource. Burning it on files Claude will never need in a given session is waste. The tier system fixes this.

Tier 1 — Always Load. Files so central that Claude needs them in every session. Entry points, the main config, the deploy script, the database schema. These go in a prominent table at the top of CLAUDE.md. Claude sees this immediately.

Tier 2 — Load On Demand. Files that are relevant only when working in a specific area. The blog system files if you are working on the blog. The trading engine files if you are working on the trading engine. Mark these clearly so Claude knows to reference them when the work enters that domain.

Tier 3 — Ignore. Generated files, build output, auto-managed content, external vendor code. Explicitly list these. If you do not, Claude may waste tokens reading a node_modules path it stumbled into.

## Key Files (Tiered)

### Tier 1 — Always Reference
| File | Purpose |
|------|---------|
| `app/layout.tsx` | Root layout — NavBar, fonts, providers |
| `lib/posts.ts` | Blog post loading — all public functions |
| `tailwind.config.ts` | Design tokens, brand colors |

### Tier 2 — Load on Demand
- `components/blog/` — Only when working on blog features
- `lib/academy.ts` — Only when working on academy content

### Tier 3 — Ignore
- `content/posts/*.mdx` — Auto-generated, never manually edit
- `.next/`, `out/` — Build output, never edit

Writing Effective Instructions

The quality of your CLAUDE.md is the quality of your Claude Code sessions. Here is how operators at the top of the performance distribution write it.

Lead with what is forbidden, not just what to do. Claude can infer a lot from context about how to do something. It cannot infer your hard constraints. "Never commit directly to main" is more valuable than ten paragraphs about your git workflow. Explicit prohibitions prevent the most expensive mistakes.

Be specific about tech choices. "We use Python 3.12 via Homebrew at /opt/homebrew/bin/python3" is worth far more than "Python project." The version, the path, the reason — all of it prevents class-of-error mistakes.

Document your non-obvious conventions. If all launchd plists must use /opt/homebrew/bin/bash, write it. If images must use a specific React component for zoom behavior, write it. Claude will repeat the pattern once it knows it.

Include the why for critical rules. "Never use localhost in Alpine Docker containers — use 127.0.0.1 because Alpine resolves them differently" teaches Claude a pattern it can generalize, rather than a rule it might override if it seems locally irrelevant.

Use headings and tables aggressively. CLAUDE.md is scanned, not read linearly. Make the structure obvious. Claude finds structured information faster and uses it more reliably.

That is the spirit of CLAUDE.md. Write it so Claude could make the right call in a situation you have not anticipated.

Common Anti-Patterns

The empty CLAUDE.md. Worse than no file because it signals you thought about it and decided context does not matter. Either write a real one or do not create the file.

Instructions Claude ignores because they are buried. If a rule matters, it goes near the top. CLAUDE.md is read from the start and the token budget is finite.

Vague conventions. "Write clean code" accomplishes nothing. "All new functions require a docstring with Args, Returns, and Raises sections" is actionable.

Instructions contradicting each other. "Never run npm install" in one section and "run npm install before testing" in another creates ambiguity. Audit for contradictions when adding rules.

Not updating CLAUDE.md when the project changes. Stale instructions are actively harmful. When you change your stack, change your CLAUDE.md in the same commit.

The Power of a Shared Global CLAUDE.md

Most developers stop at project-level. Operators build a ~/.claude/CLAUDE.md that crystallizes everything they have learned across all their projects. Your commit email. Your preferred test runner. Your security scanning mandate. Your branch policy. Deployed once, applies everywhere.

The first 10 minutes after reading this lesson: create ~/.claude/CLAUDE.md and put in it the three rules you are most tired of repeating.

Lesson 56 Drill

Audit your current project's CLAUDE.md — or create one from scratch if it does not exist.

Checklist:

• Branch policy explicit? ("Never commit to main")
• Tech stack with versions and paths?
• At least 3 explicit anti-patterns or constraints?
• Tiered file table present?
• At least one "why" explanation for a non-obvious rule?

If your CLAUDE.md does not pass all five: fix it now. The best time to write it was before you started the project. The second best time is today.

Bottom Line

CLAUDE.md is the highest-leverage file in any project. It is the difference between a Claude session that fights you and one that compounds. Write the global one for universal rules. Write the project one for stack and conventions. Use tiers to respect the context budget. Explicit prohibitions prevent the expensive mistakes. Update it after every lesson learned. No other single artifact does more to improve your output per session.