Skip to main content
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

VariableRequiredDescription
DATABASE_URLYesPostgreSQL connection string
PORTNoHTTP port (default: 8080)
LOG_LEVELNoTracing 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us