LLM Best Practices

How to write a CLAUDE.md from scratch

Last updated 4 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 is loaded into every Claude Code session as context, so it should hold only what the agent cannot derive from the code and needs every time. Run /init for a first draft, then rewrite it with the steps below. Claude treats the file as guidance, not enforcement; use hooks for anything that must always run. See claude-code-claude-md for the reference rules.

Steps

1. State the mission in one paragraph

What the repo does, who it serves, and where it deploys. No adjectives that carry no information.

## Mission
`api.example.com`: a FastAPI service serving product data to the mobile app. Deployed to Fly.io from GitHub Actions.

2. Record commands and non-default conventions

Concrete, checkable lines beat general advice: “Run npm test before committing” over “test your changes”; “API handlers live in src/api/handlers/” over “keep files organized”. Skip anything a linter enforces or the code makes obvious.

3. Document the schema if the repo produces typed artifacts

List each field, its allowed values, and its case. Without it the agent invents its own.

4. Add a “how to add a X” checklist

The most valuable section: numbered steps for the most common change, ending in the command that proves it worked.

## How to add a route
1. Add a handler in `src/routes/<domain>.py` and register it in `src/main.py`.
2. Add a Pydantic schema in `src/schemas/<domain>.py`.
3. Add `tests/test_<domain>.py`; run `pytest` and confirm it passes.

5. Keep it short and split the rest

Target under 200 lines per file. Move rules that apply to part of the codebase into .claude/rules/*.md with a paths: glob in frontmatter, so they load only when matching files are read. @path/to/file imports help organization but still load at launch, so they do not save context. Block-level HTML comments are stripped before injection; use them for maintainer notes.

6. Add personal and shared variants

CLAUDE.local.md holds your uncommitted preferences (gitignore it). Claude Code reads AGENTS.md by itself only when no CLAUDE.md exists in or above the working directory; when you keep both, put @AGENTS.md at the top of CLAUDE.md instead of duplicating it.

Verify it worked

In a new session run /context and confirm CLAUDE.md is listed under Memory files. Then ask “How do I add a route here?” and check the answer follows your checklist without extra prompting. Run /doctor prompt-audit to find contradictions and stale references.

Common errors

  • The agent ignores a rule. The file contradicts itself, the rule is vague, or the file is too long; tighten it, and for must-run behavior use a hook.
  • The file is not listed in /context. Place it at ./CLAUDE.md or ./.claude/CLAUDE.md, or in a parent directory of the working directory.
  • A subfolder file does not apply at launch. Subdirectory CLAUDE.md files load on demand when Claude reads files there.
  • Instructions disappear after /compact. Conversation-only instructions are lost; add them to the file.

FAQ

How long should a CLAUDE.md file be?

Target under 200 lines per file, and move rules for part of the codebase into .claude/rules/*.md with a paths: glob so they load only when matching files are read.

Do @ imports in CLAUDE.md save context?

No; @path/to/file imports help organization but still load at launch.

Does Claude Code read AGENTS.md?

Only when no CLAUDE.md exists in or above the working directory. When you keep both, put @AGENTS.md at the top of CLAUDE.md instead of duplicating it.

How do I check that CLAUDE.md loaded?

Run /context in a new session and confirm CLAUDE.md is listed under Memory files; /doctor prompt-audit finds contradictions and stale references.

Is CLAUDE.md enough to enforce a rule?

No; Claude treats the file as guidance, so use a hook for anything that must always run.

Backlinks