# The CLAUDE.md Protocol

*How to teach Claude what Aura is — and when to use it.*

## Overview

Claude Code reads a file named `CLAUDE.md` at the root of every project it works on. The file is injected into the system prompt of every conversation in that repo. It is the canonical way to give Claude persistent, project-specific instructions that override its default behavior.

Aura uses this protocol heavily. The [MCP server](/mcp-server) gives Claude the *ability* to perform semantic operations. `CLAUDE.md` tells Claude *when it must* perform them. Without `CLAUDE.md`, Claude has 29+ new tools it doesn't know when to call. With `CLAUDE.md`, Claude becomes a disciplined Aura user — snapshotting before edits, logging intent before commits, pulling teammate changes before touching shared functions.

The Aura source repo itself ships a reference `CLAUDE.md` that every Aura maintainer uses. Copying it into your own project is the fastest way to onboard Claude to Aura.

## Why It Works

Claude Code's system prompt is large but bounded. `CLAUDE.md` is the only mechanism that survives every turn, every compaction, and every new conversation in a project. Memory files decay; `CLAUDE.md` is a hard constraint.

Three properties make it effective for Aura:

1. **Always-on.** Claude re-reads it each turn. There is no "forgetting" on long sessions.
2. **Prioritized over defaults.** Anthropic explicitly instructs Claude to treat `CLAUDE.md` as authoritative over training defaults.
3. **Auditable.** It is a file, in the repo, under version control. A human can diff it. A reviewer can reject changes to it. An agent cannot silently mutate it without leaving a trace.

Compare this to prompt injection via chat: anything you type in the REPL lives for one session. `CLAUDE.md` lives forever.

## Setup

In a repo with Aura initialized:

```bash
aura init --with-claude-md
```

This generates a `CLAUDE.md` tuned to the project — detecting your language, package manager, and whether strict mode is enabled. If you already have a `CLAUDE.md`, Aura will append a fenced `# AURA SEMANTIC ENGINE` block rather than clobbering your existing instructions.

To regenerate just the Aura section:

```bash
aura claude-md sync
```

To preview without writing:

```bash
aura claude-md print
```

## The Template

The reference template has four sections. Every Aura-aware `CLAUDE.md` should contain at least these.

### 1. Identity and scope

```markdown
# AURA SEMANTIC ENGINE — MANDATORY PROTOCOL FOR CLAUDE CODE

> You are Claude (Anthropic), running inside Claude Code CLI.
> Aura Version: v0.14.x
> MCP Server: aura-vcs (29+ tools available)

## YOU MUST USE AURA. THIS IS NOT OPTIONAL.
```

This block is load-bearing. The imperative voice (`YOU MUST`) is deliberate — it significantly raises tool-call compliance.

### 2. Before writing any code

Lists the tools Claude must call at session start:

```markdown
1. Check semantic state — `aura_status`
2. Check cross-branch impacts — `aura_live_impacts`
3. Read team messages — `aura_msg_list` if notified
4. Plan multi-file features — `aura_plan_discover` for 3+ files
5. Verify logic paths — `aura_prove` with your goal
```

### 3. While writing code

The operational loop:

```markdown
- Snapshot before editing — `aura_snapshot` with the file path
- Log intent before every commit — `aura_log_intent`
- Review periodically — `aura_pr_review`
- Re-check impacts during long sessions — `aura_live_impacts`
```

### 4. What you must never do

The hard prohibitions. These are phrased as "never" rules because Claude follows explicit negative constraints better than fuzzy guidance:

```markdown
- Never commit without calling aura_log_intent first
- Never delete functions without explaining why in intent
- Never skip aura_plan_discover for features touching 3+ files
- Never edit a file without aura_snapshot first
- Never ignore team messages or agent messages
- Never edit a file that is BLOCKED by a team zone
```

## Configuration

You can tune the generated `CLAUDE.md` from `.aura/config.toml`:

```toml
[claude_md]
# Include the team collaboration section (only needed if using Mothership).
include_team = true

# Include the handover section (recommended if context often exceeds 50K).
include_handover = true

# Include the MCP tool inventory table.
include_tool_table = true

# Tone: "strict" (default), "firm", or "friendly".
tone = "strict"

# Extra instructions appended to the end.
preamble = """
This repo uses Rust 2024 edition. Run cargo test before logging intent.
"""
```

For monorepos, put `CLAUDE.md` at the root and use `CLAUDE.md` stubs in subdirectories that re-import the root:

```markdown
# See /CLAUDE.md for the Aura protocol. This subproject additionally requires:
- Python 3.12+
- All intents must reference a Linear ticket ID.
```

## Examples

### Minimal CLAUDE.md

If you want something shorter than the full reference protocol, this is the floor:

```markdown
# Aura Protocol (Minimal)

This repo uses Aura. You MUST:

1. Call `aura_status` at the start of every task.
2. Call `aura_snapshot` before editing any file.
3. Call `aura_log_intent` before every `git commit`.
4. Call `aura_pr_review` after completing a logical unit of work.

Never delete a function without explaining why in the intent.
Never commit without an intent.
```

Even this minimal version prevents the majority of agent mistakes.

### Team-mode CLAUDE.md

For repos using [Mothership](/mothership-overview), add:

```markdown
## Team Collaboration

- 🔄 SYNC: N function updates available → call `aura_live_sync_pull`
- 💬 TEAM: N unread messages → call `aura_msg_list`
- 📨 SENTINEL: N unread messages from another AI agent → call `aura_sentinel_inbox`
- 🚨 TEAM ZONE WARNING/BLOCKED → respect the zone, message the owner
```

These emoji-prefixed lines match the exact strings the MCP server emits in tool responses. Claude learns to pattern-match on them.

### Referencing the Aura source repo

The Aura maintainers use their own `CLAUDE.md` as a living reference. If you want the bleeding-edge version, pull it from the public repo:

```bash
curl -fsSL https://raw.githubusercontent.com/Naridon-Inc/aura/main/CLAUDE.md > CLAUDE.md
```

Then trim the sections that are Aura-specific (e.g. references to `aura-cloud/`).

## Troubleshooting

**Claude ignores CLAUDE.md.** Confirm it's at the repo root and named exactly `CLAUDE.md` (case-sensitive on Linux). Run `/status` in Claude Code; it lists which `CLAUDE.md` files were loaded.

**Claude calls the wrong tool.** This usually means your `CLAUDE.md` describes a tool that isn't exposed by your MCP server. Run `aura mcp list-tools` to see what is actually available and prune `CLAUDE.md` accordingly.

**CLAUDE.md is too long.** Anthropic softly warns when `CLAUDE.md` exceeds ~5K tokens. If yours is bigger, split project-specific rules into a `RULES.md` and reference it from `CLAUDE.md`. Aura's generated template is ~2K tokens by default.

**Changes to CLAUDE.md aren't picked up.** Claude Code caches `CLAUDE.md` for the lifetime of a conversation. Start a new conversation after editing.

**Another agent (Cursor, Windsurf) doesn't respect CLAUDE.md.** `CLAUDE.md` is a Claude-specific convention. For Cursor use `.cursorrules`; for Windsurf use `.windsurfrules`. Aura can generate all three in sync:

```bash
aura rules sync --target claude,cursor,windsurf
```

## Anatomy of a Well-Written Rule

Not all rules are equal. Aura has tested dozens of phrasings and tracked compliance rates against each. A few empirical observations:

**Imperative beats descriptive.** "You MUST call `aura_status`" outperforms "Claude should check status." The imperative phrasing is ~30% more likely to produce a tool call on the first turn.

**Explicit triggers beat implicit ones.** "Call `aura_log_intent` before every `git commit`" outperforms "Log your intent before committing." Naming the trigger — the exact command Claude is about to run — raises recall.

**Negative constraints beat positive suggestions.** "Never commit without calling `aura_log_intent`" outperforms "Remember to log intents." Negations are sticky.

**Concrete examples beat abstractions.** A rule like `aura_log_intent("Refactored retry_logic to use exponential backoff")` with a full example call outperforms "log what you changed and why."

**Grouping helps.** Rules batched by phase (before / during / after) are easier for Claude to internalize than a flat list. This matches how humans plan work.

**Short wins.** Rules over ~2 sentences get truncated in attention. Keep each rule atomic.

## Keeping CLAUDE.md Fresh

`CLAUDE.md` rots. New Aura versions add tools; old tools are deprecated. Stale rules cost compliance. Run `aura claude-md sync --check` in CI to fail the build if `CLAUDE.md` references tools your installed Aura version no longer exposes:

```yaml
- name: CLAUDE.md drift check
  run: aura claude-md sync --check
```

The check returns exit 1 if drift exists, with a diff showing which tool references need removal or addition.

## Measuring Compliance

Once `CLAUDE.md` is in place, measure whether Claude is actually following it. Aura exposes a compliance report:

```bash
aura claude-md report --since 7d
```

Output:

```
Sessions analyzed: 42
Intent calls before commit: 38/42 (90%)
Snapshot calls before edit: 118/124 (95%)
Status calls at session start: 36/42 (86%)
Plan-discover calls on multi-file features: 7/9 (78%)
```

Track the numbers over time. If they drop, your `CLAUDE.md` has rotted, the rules are unclear, or the protocol is too heavy for the project. Tune.

## Interaction with System Prompts

If your team uses a system prompt layer on top of Claude Code (via `~/.claude/system.md` or an enterprise deployment), note that `CLAUDE.md` is merged *after* the system prompt. That means project-specific Aura rules override global system rules — which is what you want. A global rule saying "do not install packages without permission" coexists fine with a project rule saying "always call `aura_snapshot` before editing."

If conflicts arise, Claude defers to the more specific (project-level) rule unless the system prompt marks itself as `priority: absolute`.

## See Also

- [MCP server](/mcp-server) — the tools `CLAUDE.md` instructs Claude to call.
- [What is Aura](/what-is-aura) — the engine under the protocol.
- [Mothership overview](/mothership-overview) — the team-mode references.
- [Custom plugins](/custom-plugins) — extending the protocol with your own tools.