CLAUDE.md

CLAUDE.md is a project-level instruction file that gets injected into the system prompt, giving Claude persistent context about your codebase.

CLAUDE.md is a Markdown file you place at the root of your project. Claurst discovers it automatically and injects its contents into the system prompt as project context before every session.

How it works

When Claurst starts, the ContextBuilder in cc-core walks upward from the current working directory to the filesystem root, collecting every CLAUDE.md file it encounters. It also reads ~/.claude/CLAUDE.md for user-level preferences. All discovered files are concatenated and injected into the system prompt.

working directory
    └── CLAUDE.md        ← loaded first (most specific)
parent directory
    └── CLAUDE.md        ← loaded next
~/.claude/
    └── CLAUDE.md        ← loaded last (most general)

The constant governing the filename is:

pub const CLAUDE_MD_FILENAME: &str = "CLAUDE.md";
pub const CONFIG_DIR_NAME: &str = ".claude";

What to put in CLAUDE.md

A useful CLAUDE.md gives Claude the context a new contributor would need to work effectively on your project.

Project overview

A short description of what the project does, its goals, and its architecture.

Coding conventions

Style rules, naming conventions, formatting standards, and linting requirements.

Key files

A map of important files and directories and what each one does.

Commands

How to build, test, lint, and run the project.

Example: Rust project

CLAUDE.md

# my-service

Async HTTP microservice built with Axum and Tokio. Persists data to PostgreSQL via SQLx.

## Architecture

- `src/main.rs` — Entry point, sets up router and starts server
- `src/handlers/` — Axum route handlers (one file per resource)
- `src/db/` — SQLx query functions and migration runner
- `src/models/` — Serde-serializable domain types
- `src/config.rs` — Loads config from environment variables

## Development commands

```bash
# Run tests (requires DATABASE_URL set)
cargo test

# Run with live reloading
cargo watch -x run

# Lint
cargo clippy -- -D warnings

# Format
cargo fmt --check

Coding conventions

• No unwrap() in production paths — use ? and anyhow::Result
• All public functions must have doc comments
• SQL queries live in src/db/ only; no inline SQL in handlers
• Use tracing::instrument on async functions that make DB calls
• New endpoints need integration tests in tests/

Environment variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
PORT	No	HTTP port (default: 8080)
LOG_LEVEL	No	Tracing filter (default: info)

## Global CLAUDE.md

`~/.claude/CLAUDE.md` applies to all projects. Use it for personal preferences that should carry across every session.

```markdown ~/.claude/CLAUDE.md
## My preferences

- Write commit messages in imperative mood ("Add feature" not "Added feature")
- Prefer explicit error handling over panics
- Always suggest adding tests for new functionality
- When editing files, preserve existing comment style

Keep ~/.claude/CLAUDE.md short. It is loaded for every project and contributes to your token budget even when the instructions are not relevant to the current task.

Token budget considerations

CLAUDE.md content is injected on every turn. Long files reduce the context window available for your actual conversation and tool results.

Claurst’s auto-compact threshold is 0.9 of the context window (200,000 tokens for current Claude 4 models). A large CLAUDE.md moves you closer to this threshold from the start of every session.

Practical guidelines:

• Keep your project CLAUDE.md under 500 lines
• Move rarely-needed reference material to separate files and mention where they live
• Avoid embedding large code samples directly in CLAUDE.md

Disabling CLAUDE.md

Pass --no-claude-md at the command line, or set no_claude_md: true in your Config, to skip CLAUDE.md discovery entirely:

claude --no-claude-md

This is reflected in the Config struct in cc-core:

pub struct Config {
    // ...
    pub no_claude_md: bool,
    // ...
}

Initializing CLAUDE.md

The /init slash command generates a starter CLAUDE.md for your current project by inspecting the directory structure, build files, and recent git history:

/init

This creates a .claude/CLAUDE.md (or CLAUDE.md at the project root) pre-populated with inferred project context.

Discovery behavior

The full discovery algorithm in cc-core::context::build_user_context:

1. Start at the working directory

   Claurst begins in the current working directory passed to the session.

2. Walk upward

   At each directory, checks for a CLAUDE.md file. If found, reads and collects it.

3. Stop at the filesystem root

   Traversal stops when it reaches / (or the drive root on Windows).

4. Append global CLAUDE.md

   Reads ~/.claude/CLAUDE.md and appends it to the collected content.

5. Inject into system prompt

   All collected content is placed in the memory section of the system prompt, which is cached per-section for prompt efficiency.