CLAUDE.md Guide
What It Is
CLAUDE.md is a context file that Claude Code reads automatically at the start of every session. It’s the primary mechanism for giving Claude persistent knowledge about you, your company, your projects, and your preferences.
In EvoNexus, CLAUDE.md is generated by the setup wizard (make setup). setup.py generates CLAUDE.md inline — no template file needed. It serves as the “working memory” layer — the hot cache that every agent reads before doing anything.
What Goes In It
The generated file includes these sections:Identity
Who you are, your company, your role, your timezone, your email addresses.Folder Structure
Where things live in the workspace. Agents use this to know where to read from and write to.Active Projects
Current projects with status. Agents reference this to understand what’s in progress.Agents
The full agent table — names, commands, domains. This tells Claude which agent to route requests to.Routines
Schedule of all automated routines with times and responsible agents.Skills
Skill index organized by prefix. Agents use this to find the right skill for a task.Integrations
Connected services (Google Calendar, Gmail, GitHub, Stripe, etc.) and what each one does.Memory (Hot Cache)
Key people, terms, and preferences that agents need frequently. This avoids looking up the same information every session.Behavior Rules
What Claude should and should not do — language preferences, file conventions, permission boundaries.How Agents Use It
Every agent readsCLAUDE.md at session start. This gives them:
- Context — who you are, what you’re working on, who your team is
- Routing — which agent handles which domain
- Conventions — file naming, language, tone preferences
- Integration awareness — what tools are connected and available
/flux to invoke the finance agent, Flux already knows your company name, your Stripe setup, your ERP system, and your financial conventions — because it read CLAUDE.md.
The Two-Tier Memory System
CLAUDE.md is tier one — fast, always loaded, limited in size.
The memory/ directory is tier two — deeper, loaded on demand:
memory/ when they need detail beyond what’s in the hot cache. For example, CLAUDE.md might say “Guilherme — Dev backend (Brius)” while memory/people/guilherme.md has his full profile, communication preferences, and recent work.
Best Practices
Keep it concise.CLAUDE.md is loaded every session. If it’s too long, it wastes context window. Put detailed information in memory/ files instead.
Use tables for structured data. People, projects, agents, integrations — tables are dense and scannable.
Update it as things change. When a project status changes or a new team member joins, update the relevant section. The memory sync routine (make memory) does this automatically at end of day.
Don’t put secrets in it. API keys go in .env. CLAUDE.md is checked into version control.
Prefix Claude-created files with [C]. This convention (defined in CLAUDE.md itself) lets you distinguish between files you wrote and files Claude generated.
Regenerating
To regenerateCLAUDE.md:
setup.py, which generates CLAUDE.md inline from config/workspace.yaml values — no template file needed. If you’ve manually edited CLAUDE.md, back it up first — setup overwrites it.