39 lines
1.9 KiB
Markdown
39 lines
1.9 KiB
Markdown
# CLAUDE.md Best Practices
|
|
|
|
CLAUDE.md is the single most important file for Claude Code. It's loaded automatically at the start of every session — it's who you are and how you work.
|
|
|
|
Anthropic's official framing of the extension stack:
|
|
- **CLAUDE.md** = always-on context (who you are)
|
|
- **Skills** = on-demand knowledge and workflows
|
|
- **MCP** = external connections (Jira, Slack, etc.)
|
|
- **[[Custom Commands]]** = shortcuts for repeated prompts
|
|
- **[[Hooks]]** = deterministic automation
|
|
|
|
## What Goes in CLAUDE.md
|
|
|
|
Keep it short. "Keeping your CLAUDE.md as short as possible is a fantastic forcing function for simplifying your codebase and internal tooling."
|
|
|
|
My rule: if you can't explain something concisely, it's not ready for CLAUDE.md.
|
|
|
|
Three sections that matter:
|
|
1. **What this project is** — one paragraph
|
|
2. **Domain rules** — the stuff Claude will get wrong without guidance
|
|
3. **Validation** — how to check that output is correct
|
|
|
|
## The Power of Negative Constraints
|
|
|
|
This was a revelation: "Codify failures into your project's CLAUDE.md. Adding specific negative rules (e.g., 'NEVER use X method for Y task') is often more valuable than positive guidelines because it prevents the AI from repeating costly mistakes."
|
|
|
|
When Claude makes a mistake, immediately add a NEVER rule. Your CLAUDE.md evolves from positive guidelines to battle-tested negative constraints over time.
|
|
|
|
Net Ninja flagged this too — Claude has a habit of using new features/hooks everywhere in your project after creating them. You need explicit "don't do this" rules.
|
|
|
|
## The Hierarchy
|
|
|
|
CLAUDE.md files cascade:
|
|
- `~/.claude/CLAUDE.md` — global (your preferences everywhere)
|
|
- `project/CLAUDE.md` — project-level
|
|
- `project/src/CLAUDE.md` — directory-level overrides
|
|
|
|
This maps to [[The Junior Employee Mental Model]] — it's the onboarding doc. [[Context Window Management]] matters here too: a bloated CLAUDE.md eats into your working context.
|