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 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:

Always-on. Claude re-reads it each turn. There is no "forgetting" on long sessions.
Prioritized over defaults. Anthropic explicitly instructs Claude to treat CLAUDE.md as authoritative over training defaults.
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:

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:

aura claude-md sync

To preview without writing:

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

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

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:

- 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:

- 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:

[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:

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

# 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, add:

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

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:

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:

- 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:

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.