> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yocxy2/claurst/llms.txt
> Use this file to discover all available pages before exploring further.

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

```rust theme={null}
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.

<CardGroup cols={2}>
  <Card title="Project overview" icon="book-open">
    A short description of what the project does, its goals, and its architecture.
  </Card>

  <Card title="Coding conventions" icon="code">
    Style rules, naming conventions, formatting standards, and linting requirements.
  </Card>

  <Card title="Key files" icon="file">
    A map of important files and directories and what each one does.
  </Card>

  <Card title="Commands" icon="terminal">
    How to build, test, lint, and run the project.
  </Card>
</CardGroup>

## Example: Rust project

````markdown CLAUDE.md theme={null}
# 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
````

<Tip>
  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.
</Tip>

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

<Warning>
  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.
</Warning>

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

```bash theme={null}
claude --no-claude-md
```

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

```rust theme={null}
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`:

<Steps>
  <Step title="Start at the working directory">
    Claurst begins in the current working directory passed to the session.
  </Step>

  <Step title="Walk upward">
    At each directory, checks for a `CLAUDE.md` file. If found, reads and collects it.
  </Step>

  <Step title="Stop at the filesystem root">
    Traversal stops when it reaches `/` (or the drive root on Windows).
  </Step>

  <Step title="Append global CLAUDE.md">
    Reads `~/.claude/CLAUDE.md` and appends it to the collected content.
  </Step>

  <Step title="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.
  </Step>
</Steps>