evolution-foundation/evo-nexus

# 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.

```markdown
## Who I Am
**Name:** Davidson Gomes
**Company:** Evolution API LTDA
**Timezone:** Brasilia (BRT, UTC-3)
```

### 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 reads `CLAUDE.md` at session start. This gives them:

1. **Context** — who you are, what you're working on, who your team is
2. **Routing** — which agent handles which domain
3. **Conventions** — file naming, language, tone preferences
4. **Integration awareness** — what tools are connected and available

When you type `/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/
  people/        — detailed profiles of team members
  glossary.md    — internal terms and acronyms
  projects/      — project history and decisions
  trends/        — weekly trend snapshots
```

Agents load from `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 regenerate `CLAUDE.md`:

```bash
make setup
```

The wizard runs `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.

## Related Files

| File | Purpose |
|------|---------|
| `setup.py` | Generates CLAUDE.md inline (no template file needed) |
| `config/workspace.yaml` | Values used to populate CLAUDE.md |
| `memory/` | Tier-two persistent memory (loaded on demand) |
| `.claude/agent-memory/` | Per-agent memory files |