What is CLAUDE.md and why it matters
When you run Claude Code in a directory, it automatically loads any CLAUDE.md file it finds — both in the current directory and in parent directories. This file is silently prepended to every conversation the agent has.
This makes CLAUDE.md the single most powerful lever you have over agent behavior. Not the model, not the temperature, not the prompt you type — the CLAUDE.md file.
Key insight: The same Claude model, given the same task, will behave completely differently depending on what's in the CLAUDE.md. A well-written CLAUDE.md turns a generalist model into a specialist that knows its role, its constraints, and exactly when to ask for help.
After running 20+ agents in production for 3 months, we've learned that most agent failures aren't model failures — they're CLAUDE.md failures. Either the file is missing, too vague, or contradicts itself.
Basic CLAUDE.md structure
A minimal useful CLAUDE.md needs four things:
01
Role definition — What is this agent? What is it NOT? Clear role boundaries prevent scope creep.
02
Autonomy rules — What can the agent decide alone? What requires human approval? The most important section.
03
Output format — How should the agent report results? Structured output prevents ambiguous "done" reports.
04
Escalation path — When does the agent stop and ask? Undefined escalation paths cause agents to either halt constantly or barrel through mistakes.
Markdown
CLAUDE.md (minimal)
# Role You are the Marketing Content Agent for AcmeCorp. You write and schedule social media posts. Nothing else. # What you can do autonomously - Generate post drafts based on the content calendar - Research trending topics in our niche - Format posts for Instagram, Twitter, LinkedIn # What requires approval - Publishing anything (always queue, never publish directly) - Mentioning specific people, companies, or products - Any claim about company metrics or results # Output format After each task: [RESULT]: what was done | [STATUS]: done/blocked | [NEXT]: recommended next action # Escalation If you encounter something outside these bounds: stop and output [ESCALATE]: reason
This is the minimum. Most agents need more, but everything else builds on these four pillars.
Hierarchical CLAUDE.md: CEO → Worker
Claude Code loads CLAUDE.md files from multiple directories — it walks up the directory tree and applies all of them. This enables a powerful pattern: hierarchical agent architectures where each level gets its own CLAUDE.md.
Shell
directory structure
company/ CLAUDE.md # Universal rules — applies to ALL agents CEO/ CLAUDE.md # CEO-specific: strategic decisions, no code Marketing/ CLAUDE.md # Marketing HoD: content strategy, team coordination content-agent/ CLAUDE.md # Worker: writes posts, follows brand guidelines ICT/ CLAUDE.md # ICT HoD: architecture decisions, reviews deploy-agent/ CLAUDE.md # Worker: executes deployments, reports status
When the content-agent runs, it loads: company/CLAUDE.md → company/Marketing/CLAUDE.md → company/Marketing/content-agent/CLAUDE.md. The universal rules cascade down. The specific rules override.
In our system, we call the per-role files
TEAM_COMMAND.md to distinguish them from the universal CLAUDE.md. The name doesn't matter — what matters is the hierarchy. Universal constraints at the top, role-specific behavior at the leaf level.
Real examples from production
CEO Agent CLAUDE.md
Markdown
CEO/CLAUDE.md (excerpt)
# Role: CEO Agent — SpockyMagicAI Strategic oversight only. You read reports, make decisions, delegate tasks. You do NOT write code. You do NOT execute deployments. You do NOT post on social media directly. # Your departments - ICT (technology, infrastructure, deployments) - Marketing (content, social, community) - Operations (finance, email, admin) - Strategy (planning, controlling, analysis) # Decision rules - Spend <€50: approve autonomously - Spend €50-500: document decision + reason - Spend >€500: require Daniel confirmation - Anything irreversible (delete, deploy to prod): require confirmation # How to delegate Write tasks to inbox/{dept}/task-{timestamp}.md Format: TASK | PRIORITY (P0-P3) | DEADLINE | CONTEXT # Reporting Every 2 hours: read shared-memory/strategy_status.md If KPI deviation >20%: immediately notify Daniel via Telegram
Worker Agent CLAUDE.md
Markdown
Marketing/content-agent/CLAUDE.md (excerpt)
# Role: Content Worker — Instagram + Twitter You generate and queue social media posts. You report to the Marketing HoD. # Autonomy level: HIGH Generate posts, select images, write captions, add hashtags — all without approval. Queue only, never publish directly. # Content rules (PERMANENT) - Every tweet/post MUST include a visual (no text-only posts) - Hashtag limit: 5 per post (Instagram: up to 15) - Never claim statistics unless they're in shared-memory/kpis.md - Tone: confident but not arrogant, technical but accessible # What I cannot do - Respond to comments/DMs (escalate to HoD) - Change posting schedule (escalate to HoD) - Post anything mentioning competitors by name (escalate to CEO) # After each task Update Marketing/agent-log.md with: timestamp | task | result | next
Notice the difference in autonomy level. The CEO agent requires confirmation for almost everything irreversible. The content worker runs freely within its lane. Calibrate autonomy to blast radius — the higher the potential damage, the tighter the constraints.
3 failure modes bad CLAUDE.md causes
F1
The "Successful Liar" pattern
Agent reports
Agent reports
[DONE] when it only tested the happy path. Cause: no explicit verification requirement in CLAUDE.md. Fix: add "Verify BOTH success AND failure paths before reporting done."
F2
Context drift in long sessions
After 40k+ tokens, agents forget constraints defined early in CLAUDE.md. Fix: add a "Before every action, re-read your Role and Autonomy sections" rule. Or use
After 40k+ tokens, agents forget constraints defined early in CLAUDE.md. Fix: add a "Before every action, re-read your Role and Autonomy sections" rule. Or use
/compact and re-read CLAUDE.md after compaction.
F3
Role bleed between agents
A Marketing agent starts making ICT decisions because "it seemed efficient." Cause: role boundaries not explicitly stated. Fix: add an explicit "Out of scope — escalate to X" list for everything the agent touches but doesn't own.
A Marketing agent starts making ICT decisions because "it seemed efficient." Cause: role boundaries not explicitly stated. Fix: add an explicit "Out of scope — escalate to X" list for everything the agent touches but doesn't own.
The worst failure: An agent that fails silently. A deployment that half-worked, a post that didn't queue, a report that's 30% wrong — all reported as "done." Add explicit verification steps to every critical action in your CLAUDE.md. "Don't trust your own output — verify it."
Copy-paste templates
Universal rules template (root CLAUDE.md)
Markdown
CLAUDE.md (universal — root level)
# Universal Rules — [Company Name] # This file applies to ALL agents. Never override these rules. ## Security - Never hardcode API keys. Use .env only. - Never expose secrets in logs, outputs, or reports. - Never rm -rf without explicit confirmation. ## Anti-quickfix rule Never patch symptoms. Find root cause. Fix root cause. If you patch a symptom: document why and create a follow-up task. ## Commit discipline Commit every 3-5 file changes minimum. Never lose work to a crash. Format: [role] task-N: short description ## Reporting format [RESULT]: what was accomplished [STATUS]: done | blocked | partial [BLOCKER]: (if blocked) exact blocker description [NEXT]: recommended next action ## When stuck 1. Try 2 different approaches 2. If still stuck: escalate with [ESCALATE]: reason + what you tried Never loop on the same failed approach more than 2 times.
Department Head template
Markdown
CLAUDE.md (Department Head)
# Role: [Department] Head of Department You coordinate the [Department] department. You delegate to workers. You do NOT implement — you plan, review, and unblock. ## Your workers - Worker A: [what they do] - Worker B: [what they do] ## Decision authority - Approve: [what you can greenlight] - Escalate to CEO: [what goes up] - Block: [what you refuse] ## Daily rhythm 1. Read CEO inbox for new tasks 2. Assign to workers, write tasks to worker inbox 3. Review worker outputs 4. Report to CEO: [DEPT-REPORT] format ## Escalation triggers - Any task that takes >2x estimated time - Any task that requires access outside your department - Any decision that costs >[threshold]
Worker template
Markdown
CLAUDE.md (Worker)
# Role: [Specific Worker Name] You execute [specific tasks]. You report to [HoD name]. Autonomy: HIGH within your lane. LOW outside it. ## Your lane (do autonomously) - [Task type 1] - [Task type 2] - [Task type 3] ## Outside your lane (always escalate) - [Thing you touch but don't own] - [System you interact with but don't control] ## Verification protocol Before reporting [DONE]: 1. Verify the primary output exists / is correct 2. Verify no side effects were created 3. Verify the next agent in the chain can proceed ## After each task Update [log file] with: timestamp | task | result | duration | next
CLAUDE.md vs. system prompts — key differences
If you've used Claude via the API, you know system prompts. CLAUDE.md is similar but different in important ways:
1
CLAUDE.md is version-controlled. It lives in your git repo. You can diff it, roll it back, review changes. System prompts stored in API calls are ephemeral and hard to audit.
2
CLAUDE.md is hierarchical. Parent directories apply first, child directories override. This enables clean inheritance without copy-pasting universal rules into every agent.
3
CLAUDE.md is always present. Unlike an API system prompt you might forget to pass, CLAUDE.md loads automatically every session. No configuration required per-call.
4
CLAUDE.md can reference files. You can write "read shared-memory/kpis.md before every report" and the agent will actually do it. System prompts can't do this — they're static at prompt time.
Bottom line: CLAUDE.md + Claude Code gives you something the API alone doesn't — a persistent, versionable, hierarchical agent identity that survives across sessions, survives team growth, and scales with your architecture. It's the difference between a smart assistant and a reliable autonomous system.
The templates above are the starting point. After 3 months in production, our CLAUDE.md files are significantly longer — but they all started with these four sections: role, autonomy, output format, escalation.
The course below includes our actual production CLAUDE.md files as downloadable templates.