CLAUDE.md — Instructing Your AI Agent

What Is CLAUDE.md?

CLAUDE.md is a markdown file that Claude Code reads automatically at the start of every conversation. It's injected directly into the context window — think of it as a permanent briefing document that the agent has already read before you type a single word.

Unlike a system prompt that you'd configure via API, CLAUDE.md is a plain file you commit alongside your code. It travels with the repo, gets updated as the project evolves, and is immediately visible to anyone (human or AI) who opens the project.

The Three Layers

Claude Code reads CLAUDE.md from multiple locations, merging them in order from broadest to most specific:

Anatomy of a Great CLAUDE.md

A well-structured project CLAUDE.md has six sections. Each serves a different purpose for the agent's cognition.

1. Developer Profile (global only)

Who you are, what languages you work in, your skill level. Claude adapts its explanations and suggestions based on this. Put this in ~/.claude/CLAUDE.md — it doesn't belong in individual repos.

2. Active Projects Table

A quick-reference table of repos the agent might need to navigate across. Path on disk, primary language, and a one-liner of purpose. This is critical for multi-repo work — Claude can cross-reference without you explaining the layout every time.

3. Conventions (the non-obvious ones)

This is the highest-value section. Capture things that are true of your project that Claude wouldn't guess from the code alone:

• Naming conventions that differ from community standards
• Currency / token names that are project-specific (e.g., testnet vs mainnet symbols)
• Authentication patterns your infrastructure uses
• File locations that are non-standard
• Which APIs require which parameters that aren't obvious

4. Build & Test Commands

Exact commands to build, test, and run the project. Not documentation — these are the literal commands Claude will run. Include flags that are required, not just the happy path.

5. Agent Team (global)

If you run multiple AI agents (a research agent, a monitoring agent, etc.), describe them in the global CLAUDE.md so the primary agent knows what resources exist and how to reach them.

6. Security Notes

What must never be committed. What gets security review before merge. What's real-money code. This is the section you'll be glad you wrote when Claude is about to do something irreversible.

Real Example: Blockchain + Embedded Project

Here's a condensed but realistic CLAUDE.md for a project spanning embedded C, Rust, and blockchain tooling:

# CLAUDE.md

## Project: chain-light-esp

ESP32-based blockchain light client. C/ESP-IDF for firmware,
Rust for the host-side sync tooling.

## Active Repos

| Repo | Path | Language | Purpose |
|------|------|----------|---------|
| chain-light-esp | ~/projects/chain-light-esp | C/ESP-IDF | ESP32 firmware |
| chain-sync-host | ~/projects/chain-sync-host | Rust | Host-side header sync |
| chain-scripts | ~/projects/chain-scripts | TypeScript | On-chain scripts |

## Conventions

- Testnet token is `tTKN`, NOT `TKN` (common mistake — mainnet only)
- Node RPC on local runs at 127.0.0.1:8114 (not 8545)
- Node API requires bearer auth token in every request header
  Token file: ~/.node-testnet/.secrets/api-token.txt
- ESP32 flash target: esp32s3 (not generic esp32)
- IDF version pinned to v5.2.1 — do not upgrade without full regression

## Build & Test

```bash
# Firmware (requires IDF environment active)
cd ~/projects/chain-light-esp
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

# Host sync tool
cd ~/projects/chain-sync-host
cargo build --release --features sqlite
cargo test

# Scripts (TypeScript)
cd ~/projects/chain-scripts
npm run build && npm test
```

## Security Notes

- On-chain scripts handle real value — treat as financial software
- Never commit .env files, private keys, or auth tokens
- Any signing code gets security review before merge
- Mainnet addresses have a distinct prefix — double-check before sending tx

What Goes in the Global File

Your ~/.claude/CLAUDE.md should hold things that are true regardless of which project you're in:

Pitfalls to Avoid

Template: Project CLAUDE.md Starter

Copy and adapt this for any new project:

# CLAUDE.md

## Project: [Name]

[One sentence: what this project does and why it exists.]

## Active Repos

| Repo | Path | Language | Purpose |
|------|------|----------|---------|
| [repo-name] | ~/path/to/repo | Lang | Description |

## Conventions

- [Convention 1 — non-obvious rule specific to this project]
- [Convention 2 — naming/symbol/auth quirk]
- [Convention 3 — external API or tool constraint]

## Build & Test

```bash
# Build
[exact build command with required flags]

# Test
[exact test command]

# Run / dev server
[exact run command]
```

## Security Notes

- [What must never be committed]
- [What requires security review]
- [Any real-money or sensitive data considerations]

Template: Subdirectory Override

Place this in a subdirectory that has different rules from the project root:

# Firmware Module — CLAUDE.md override

This directory is ESP-IDF C. Different rules apply here.

## Language: C (ESP-IDF v5.2.1)
## Target: esp32s3

## Key constraints
- No dynamic allocation in interrupt handlers
- Stack size for main task: 8192 bytes
- Use idf_component.yml for external dependencies, not git submodules
- UART0 is reserved for debug log — do not redirect it

## Build (from this directory)
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

Rules Files: Beyond CLAUDE.md

For cross-project standards (coding style, testing requirements, security policies), Claude Code also reads from ~/.claude/rules/. These are separate markdown files — one per topic — and are a cleaner way to manage long-form standards that would bloat your CLAUDE.md.

How Agents Actually Read It

CLAUDE.md content is injected at the top of the context window before any user message. This means:

• It's always present. Claude doesn't "check" it — it has already read it. You don't need to say "refer to CLAUDE.md" in your prompts.
• It competes with everything else for the context budget. A 600-line CLAUDE.md plus a large codebase can leave very little room for multi-file edits.
• Order matters. Information near the top of the file is more reliably attended to than information buried at the bottom.
• It's not secret. Anyone reading the repo can see it. Don't put sensitive information in the project-level CLAUDE.md.

Checklist: Is Your CLAUDE.md Good?

See also: Hooks & Safety · Writing Skills · Knowledge Graphs

← Back to AI Hub