01 — Philosophy & CLAUDE.md
New here? Claude Code is a command-line tool that lets Claude run shell commands, edit files, and build on your machine. Out of the box it's generic.
CLAUDE.mdis the file that teaches Claude how you work — your rules, your stack, your preferences. Set it up once and every session starts already knowing what matters.
Why CLAUDE.md exists
Claude has no memory between sessions. Every conversation starts from zero. Without instructions, it makes safe, generic decisions — the kind that are correct for nobody in particular.
CLAUDE.md solves this. It's a plain Markdown file that Claude reads at session start. Anything you put there becomes standing context: your rules, your toolchain, your autonomy boundaries. You stop repeating yourself. Claude stops guessing.
One file, read once, shapes every session that follows.
The two-layer hierarchy
You need two files, not one.
~/.claude/CLAUDE.md — global rules
This is your system-wide constitution. Everything that applies across all projects goes here: your package manager preference, your debugging protocol, your autonomy rules, which models to use for what, how expensive tools get gated. These rules fire on every session regardless of what directory you're in.
[project-root]/CLAUDE.md — project rules
This is your per-codebase context. The tech stack, the relevant file paths, the business domain, any constraints specific to this project. Only loads when you're working inside that directory.
The split matters. Global rules handle invariants. Project rules handle specifics. Don't cross-contaminate: putting project-specific paths in global config creates noise; putting universal rules only in one project means every other project is flying blind.
What belongs in global CLAUDE.md
Tooling invariants
Decisions that don't change between projects: which package manager, which formatter, which linter. One rule written once prevents a thousand corrections.
- Use `npm` exclusively — never yarn, pnpm, or bun.
Autonomy boundaries
Tell Claude when to act without asking and when to stop and confirm. The split that works: act on routine work (file edits, running commands, fixing its own errors), confirm before anything destructive or visible to others (pushes, deploys, deletions, scope changes).
Debugging protocol
A good default: verify infrastructure first (network, auth, env vars, API access) before touching code. Stops Claude from rewriting perfectly good logic when the real problem is a missing environment variable.
Tool gates
Expensive tools (large models, paid APIs, automated actions) need conditions. Write those conditions explicitly. "Call the expensive reasoning model only when stuck after two failed attempts" is a rule. "Use it freely" is a budget leak.
Session rituals
Consistent behavior across sessions: naming pattern for session titles, what to do at session end, how to hand off context to the next session.
What belongs in project CLAUDE.md
Stack and architecture
Framework, language, key dependencies. Not an exhaustive list — the things Claude needs to make the right call when it has to choose between approaches.
File and directory conventions
Where components live. Naming patterns. What not to touch. Any paths that are out of scope.
Domain constraints
Things the codebase assumes that aren't obvious from reading code: business rules, compliance constraints, API rate limits, third-party quirks.
Active context
Current sprint focus. Known broken areas. Recent decisions and why they were made. This is the part that changes most often — keep it short so you'll actually maintain it.
The @-import pattern
Project CLAUDE.md files can pull in shared context from other files:
@path/to/shared-context.md
@path/to/design-rules.md
This is useful when you have content that multiple projects share — a brand voice doc, an API reference, a design system spec. Write it once, import it everywhere. No copy-paste drift.
What does NOT belong
Live project statuses. "Phase 2, 16 commits" is stale the moment you commit again. Claude doesn't need a progress report — it needs rules.
Credentials and key paths. Keep secrets out of any file that might get committed or shared. CLAUDE.md is not a .env.
Personal identity blocks. Claude doesn't need your bio to do its job. Rules, not autobiography.
Drift-prone counts. "23 enabled skills", "142 files" — these are wrong the moment you change anything. Use prose when you need to convey scale ("a handful", "dozens"), or leave it out.
Anything you wouldn't want public. Project files end up committed. If the repo is public, your CLAUDE.md is public. Audit it like any other file.
Working style rules that compound
The rules with the highest leverage are the ones that change Claude's defaults on every task, not just specific situations.
A few that work well:
- Simple over clever. One thing done right beats three things half-done.
- Correctness first. Priority order: correctness → maintainability → performance → new features.
- Parallelize independent steps. If two things don't depend on each other, do them at the same time.
- No trailing summaries. Concise responses. State what was done, skip the recap.
These aren't clever tricks. They're hygiene. Written once, they shape every interaction without you thinking about them.
The one-sentence summary
CLAUDE.md is the difference between Claude that starts informed and Claude that starts from scratch. Write your global rules once. Write your project rules per codebase. Keep both honest — stale rules are worse than no rules.