LLM Best Practices

Claude Code: CLAUDE.md

Last updated 3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

CLAUDE.md files are instructions Claude Code loads at the start of every session. They arrive as a user message after the system prompt, so Claude tries to follow them but nothing enforces them. Auto memory is a separate mechanism: notes Claude writes itself to ~/.claude/projects/<project>/memory/, of which the first 200 lines or 25KB of MEMORY.md load each session. Write standing rules in CLAUDE.md; for anything that must happen every time, use a hook.

Put each rule at the narrowest scope that needs it

LocationScope
./CLAUDE.md or ./.claude/CLAUDE.mdProject, committed
./CLAUDE.local.mdYou, this project, gitignored
~/.claude/CLAUDE.mdYou, every project
/etc/claude-code/CLAUDE.md (Linux, WSL); /Library/Application Support/ClaudeCode/CLAUDE.md (macOS)Organization, cannot be excluded

Files in the working directory and every ancestor directory load at launch, concatenated from the filesystem root down. A CLAUDE.md in a subdirectory loads on demand when Claude reads a file there. In a monorepo, skip other teams’ files with claudeMdExcludes. Run /context to confirm what loaded and /memory to edit.

Keep it under 200 lines and cut what Claude can derive

Longer files cost context on every session and lower adherence. For each line ask whether removing it would cause a mistake; if not, cut it.

  • Keep: build and test commands Claude cannot guess, style and voice rules that differ from defaults, content schemas with their field rules, branch and PR conventions, non-obvious architecture decisions, environment quirks, known gotchas.
  • Cut: directory listings and dependency lists Claude can read from the repo, standard language conventions, API reference (link it), anything that changes weekly, “write clean code”.

/doctor proposes trims for a checked-in CLAUDE.md, and /doctor prompt-audit flags stale or conflicting instructions across your instruction files. Contradictory rules in two files leave Claude free to pick either.

Write rules Claude can verify

“Use 2-space indentation” works; “format code nicely” does not. Pin specific bans instead of adjectives. Write procedures as numbered imperative steps so Claude does not have to explore before acting.

## Add a page
1. Create `content/<category>/<slug>.md` with the full frontmatter.
2. Add a bullet to the folder's `index.md`.
3. Run `node scripts/lint-content.mjs` and fix every error.

If Claude skips one instruction, mark that line “IMPORTANT”. Emphasizing many lines makes none stand out.

Move conditional content out of the always-loaded file

  • Rules for part of the tree: .claude/rules/*.md with a paths frontmatter list of globs (for example src/api/**/*.ts). They load only when Claude reads matching files.
  • Multi-step procedures used sometimes: a skill; see claude-code-skills.
  • Anything that must run unconditionally: a hook; see claude-code-hooks.
  • @path/to/file imports (up to four hops deep) organize a long file but do not save context, because imported files also load at launch.

Share instructions with other coding tools through AGENTS.md

Claude Code reads AGENTS.md (v2.1.277 and later) only when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above it. When a repo needs both, keep AGENTS.md as the shared file and import it:

@AGENTS.md
 
## Claude Code
Use plan mode for changes under `src/billing/`.

Prefer the import over a symlink on Windows, where symlinks need elevated rights and clone as plain text.

Keep tasks out of CLAUDE.md

CLAUDE.md holds rules that change rarely; TODO.md holds the backlog that changes every session; README.md is for humans. A task list in CLAUDE.md makes Claude read stale work next to standing rules. After /compact the project-root CLAUDE.md is re-read from disk, so an instruction given only in chat is lost; add it to the file to make it stick.

Backlinks