CLAUDE.md: Teaching the Agent Your Rules

Tier 1 · Fundamentals 9 min read

Every time Claude Code starts a session, before it does anything else, it reads a file called CLAUDE.md. Whatever is in that file becomes the agent’s standing instructions for the session: your house rules, your project conventions, your hard limits, your identity preferences — all of it, loaded once and in force for the whole run.

Getting CLAUDE.md right is the highest-leverage configuration work you can do on a Claude Code system.

What it is

CLAUDE.md is a plain Markdown file that Claude Code reads automatically on session start. There is nothing magic about the format — it’s text. What matters is where it lives and what you put in it.

When a session starts, Claude Code looks for CLAUDE.md files in a specific order:

User-global: ~/.claude/CLAUDE.md — applies to every session you run, everywhere.
Project-level: CLAUDE.md (or .claude/CLAUDE.md) at the root of your working directory — applies to sessions in that project.
Additional context: files you pass explicitly, or additional files the project-level CLAUDE.md imports.

Instructions in these files override the agent’s defaults. If your global CLAUDE.md says “never run git push --force,” the agent will refuse, even if you ask it to in the session. If your project-level file says “all test files go in /tests/unit/,” it follows that convention without being told again each time.

What to put in a global CLAUDE.md

The global file is for rules that apply everywhere, regardless of what you’re working on. Good candidates:

Identity and context. Who you are, what timezone, what email address to use, what external accounts the agent can act on your behalf.
Hard limits. Things the agent should always refuse or always confirm before doing: destructive commands, force pushes, dropping tables, sending emails.
Engineering discipline. Surgical changes, root-cause-first, no gold-plating.
File layout conventions. Where state files live, where logs go, what the naming conventions are.
Tool preferences. “Always use the gog CLI for Gmail, never the MCP Gmail server” — the kind of operational detail that varies by setup and must be explicit.

What to put in a project-level CLAUDE.md

The project file is for rules specific to that codebase or task:

Tech stack conventions. What framework, what test runner, what linter settings, how the build works.
Role context. “You are a specialist agent responsible for the analytics pipeline — don’t touch the storefront code.”
Key file paths. Where the state lives, which files are authoritative, what to read on startup.
Standing permissions. Which commands are pre-approved vs which need confirmation for this project.

A concrete example

Here is a condensed version of the kind of project-level CLAUDE.md that makes an agent immediately useful:

# Project: Analytics Suite

## Role
You are the analytics agent for this project. Stay in this directory.
Don't touch ~/clawd/projects/nerve-center-v5/.

## Tech stack
- Python 3.12
- pytest for tests (run `pytest -q` before committing)
- ruff for linting (`ruff check . --fix` then `ruff format .`)

## State files
- Current task: state/current-task.md
- Open issues: state/issues.yaml
- Log shipped work: `bash ~/agent-system/scripts/clawd-log.sh analytics-suite "what shipped"`

## Hard limits
- Never commit to main directly — always use a feature branch.
- Never run DROP TABLE without explicit confirmation.
- Never edit files outside this directory without asking.

An agent that reads this at session start knows what it’s doing, where to log work, and what the guardrails are — without you repeating any of it.

Instructions override defaults — with limits

CLAUDE.md instructions are powerful, but they work best for concrete rules: paths, commands, conventions, confirmations. They work less reliably for subtle behavioral guidance. The honest experience of running agents over months is that behavioral instructions drift with context — as the session fills, behavioral guidance from early in the conversation or even from CLAUDE.md can fade.

This is why hard operational rules (“never run this command,” “always write state here”) live in CLAUDE.md, while automatic behaviors that truly can’t be forgotten are enforced by hooks instead. We cover hooks in T1-08.

The practical division:

CLAUDE.md: rules, conventions, paths, identity, guardrails.
Hooks: automated behaviors that must fire regardless of context — things infrastructure enforces rather than the model remembers.

Keeping it honest

CLAUDE.md files grow. Engineers add rules over time, and nobody removes the ones that became irrelevant. The file ends up as a palimpsest of past decisions. Useful, but worth periodically reviewing: does every rule in here still apply? Is anything in conflict? Is there a rule that should be in a hook instead?

A concise CLAUDE.md that the agent reads fully is more useful than a 10,000-word manifesto that front-loads its context budget.

Next: Tools 101 — the built-in hands: Read, Edit, Write, Bash, Grep, and how the agent decides which one to reach for.