The CLAUDE.md File That Runs All My Projects

Every project I work on has a CLAUDE.md file. It's the first thing Claude Code reads when it enters a repo, and it's the single biggest lever for getting consistent output across sessions.

Most guides tell you to run /init and call it done. That gives you a decent starting point, but it misses the things that actually matter: project-specific safety rules, deployment gotchas, and the mistakes you've already made.

Here's how I write mine, with real examples from three different types of projects.

What CLAUDE.md actually does

When you open Claude Code in a directory, it reads any CLAUDE.md file in the root. The contents get injected into the system prompt — before your first message, before any tool calls, before anything. It's persistent context that survives across sessions.

This means anything in CLAUDE.md is treated as a standing instruction. Not a suggestion. An instruction.

What to include

1. What this project is (2-3 lines)

Claude needs to know what it's working on. Keep it short.

# forex-ai
13-pair forex trading bot. MQL5 on MetaTrader 5.
Live on Fusion Markets via Windows VPS. A$5k balance.
Strategy: EMA(5) + dual RSI(21/14) on 1H bars.

Not a README. Not a product description. Just enough context that Claude knows the stakes and the tech.

2. What never to do

This is the most important section. Rules born from real mistakes.

## NEVER
- Never change magic numbers without grepping the ENTIRE codebase first
- Never deploy to VPS without reviewing the diff line by line
- Never modify check_max_hold without understanding all callers
- Never assume AutoTrading is enabled after VPS reboot
- Never use filling mode ORDER_FILLING_FOK without checking symbol support

These are specific. They reference real functions, real files, real failure modes. Generic rules like "be careful with production code" don't help — Claude needs to know exactly what "careful" means in this codebase.

3. Project structure

Which files matter and why. Skip the obvious stuff (node_modules, package.json) and focus on the non-obvious:

## Key files
- `Experts/ForexBot.mq5` — Main EA, all 13 pairs
- `Include/RiskManager.mqh` — Position sizing, max drawdown
- `Include/SignalEngine.mqh` — Entry/exit logic
- `Scripts/Backtest.mq5` — 24-year backtest runner
- `.github/workflows/compile.yml` — Syntax check on push

4. Common tasks and how to do them

The things you ask Claude to do repeatedly:

## Common tasks
### Adding a new pair
1. Add symbol to PAIRS array in ForexBot.mq5
2. Add filling mode detection for the symbol
3. Add to backtest config in Scripts/Backtest.mq5
4. Test compilation locally before deploying
 
### Updating parameters
1. Grep for the old value across ALL files
2. Show me every occurrence before changing anything
3. After changes, grep again to confirm zero remaining

Without this, Claude will figure out its own approach each time — and it might miss steps.

5. What not to include

This matters as much as what you put in. Every line of CLAUDE.md consumes context window. Wasted context means less room for actual work.

Don't include:

• Full API documentation (link to it instead)
• Commit history or changelogs
• Duplicate information from README
• Generic coding standards ("use TypeScript", "follow best practices")
• Environment variable values (security risk)

Keep it under 100 lines. If your CLAUDE.md is longer than that, you're probably including reference material that belongs in a separate doc.

Real examples

Trading bot (forex-ai)

# forex-ai
13-pair forex bot. MQL5/MT5. Live on Fusion Markets.
 
## CRITICAL
- Never rush deployments. Grep entire codebase before any identifier change.
- VPS is UTC. You are AEST (UTC+10). Don't panic about "old" timestamps.
- AutoTrading is GUI-only. Cannot be enabled via script.
 
## Structure
- Experts/ForexBot.mq5 — main EA
- Include/ — shared libraries (risk, signals, utils)
- Scripts/ — backtesting and analysis
 
## Deployment
1. Compile locally (Wine + MT5 on Mac)
2. Push to GitHub
3. SSH into VPS, pull, copy to MT5 data folder
4. Verify AutoTrading is ON after any reboot

SaaS product (AgentFloor)

# AgentFloor
Visual marketing SaaS. 27 AI agents on a graphical floor UI.
 
## Stack
Next.js 15, TypeScript, Tailwind v4, Supabase, Framer Motion, Stripe
 
## Conventions
- Australian English throughout
- All components in src/components/, co-located with tests
- Supabase client via lib/supabase.ts (never import directly)
- Stripe webhooks in app/api/webhooks/stripe/
 
## Design
- See docs/DESIGN-GUIDE.md for colours, typography, spacing
- Dark theme default, light theme support required
- All animations must respect prefers-reduced-motion

Marketing system (PropAutopilot marketing head)

# PropAutopilot Marketing Head
Autonomous marketing via Slack. Claude as CMO, human operator reviews.
 
## Architecture
- listener.py — Socket Mode daemon for real-time @mentions
- run.sh — Cron session runner (6am/10am/2pm/6pm AEST)
- webhook.sh — Posts to #marketing-propautopilot
 
## State files (log/)
- MARKETING-LOG, CONTENT-QUEUE, HASAN-TASKS, PERFORMANCE
 
## Rules
- Never touch ValuesIdentifier Notion pages from this system
- Only interact with #marketing-propautopilot channel
- Content must pass banned-cliches check before queuing

Global vs project-specific

I maintain two levels:

1. Global CLAUDE.md (in ~/.claude/) — Cross-project rules: Australian English, propagate learnings to MEMORY.md, slow down on live systems
2. Project CLAUDE.md (in each repo root) — Project-specific rules, structure, deployment

The global rules apply everywhere. Project rules apply only in that repo. If they conflict, project rules win (they're loaded after the global file).

The maintenance problem

CLAUDE.md files go stale. You add a rule after a mistake, then the codebase changes and the rule references a function that no longer exists. I review each project's CLAUDE.md when I start a new sprint — takes 5 minutes and prevents confusion.

The "NEVER" section is the most stable part. Deployment gotchas don't change often. The project structure section needs the most updates as the codebase grows.

I've tried elaborate setups — multi-file rule systems, auto-generated docs, dynamic CLAUDE.md builders. None of them worked as well as a single hand-written file that says "here's what this project is, here's what you must never do, and here's how things actually work around here." Simple, specific, and honest about past mistakes. That's the whole formula.