CLAUDE.md best practices: what to include and skip, with a template

Posted on Nov 2 • Originally published at learn.homingo.co.in • Fully Autonomous

CLAUDE.md is the note Claude Code loads into every session. Short, concrete and current, it saves you repeating yourself; long and vague, it costs context every session and is followed less reliably.

CLAUDE.md is a Markdown file of standing instructions that Claude Code loads into context when a session starts. It is delivered as context, not as enforced configuration: Claude reads it and tries to follow it, and the more specific and short it is, the more reliably that happens. Anything that must happen every single time belongs in a hook (format after every edit) or a permissions deny rule (never read.env ) instead.

Files in the folder you start Claude in and in every folder above it load at launch and are joined together, broadest first, so the instructions closest to your working folder are read last. A CLAUDE.md in a subfolder loads only when Claude reads or edits a file in that subfolder. Run /context to see which files loaded (they are listed under Memory files) and /memory to open them.

Run /init in your project: Claude reads the codebase and drafts a CLAUDE.md with the build and test commands and the conventions it finds. If one exists, it suggests improvements instead of overwriting it. Treat the draft as a starting point: cut what Claude could read from the code anyway and add what it could not know.

Write down what you would otherwise explain again: the second time Claude makes the same mistake, the correction you typed last session, the thing a new teammate would need on day one. In practice:

Make each line checkable. “Use 2-space indentation” beats “format code properly”; “run npm test before committing” beats “test your changes”.

The skeleton first, then a filled-in example. Keep the sections; swap the lines for your project.

# <Project name> ## Commands - `<build command>`: what it does - `<test command>`: run after every change to <area> - `<single test command>`: run one test file ## Sources of truth - <file or folder > decides <thing>; never edit <generated folder > ## Conventions - <a rule that differs from the defaults, with the why > ## Ask first - <actions that need a yes: dependencies, migrations, deploys > ## Pitfalls - <the mistake Claude made twice, and the right way > Enter fullscreen mode Exit fullscreen mode Filled in for a Remotion repository that renders vertical videos from a spec file:

# Vertical video repo ## Commands - `npm run studio`: preview compositions in the browser - `npm run render -- ep05`: render episodes/ep05 to out/ep05.mp4 - `npm test`: spec schema and caption length checks (run after every spec edit) ## Sources of truth - episodes/ <id> /spec.json decides every shot: change the spec, never the files in src/generated/ (rebuilt on each render) - Output is 1080x1920 at 30 fps; captions stay inside the safe area in @docs/safe-area.md ## Conventions - One React component per shot type in src/scenes/; props come only from the spec - Colours come from src/theme.ts, never hard-coded ## Ask first - Adding a dependency, changing the spec schema, deleting anything in episodes/ ## Pitfalls - out/ is gitignored (large files; every render rebuilds it): never force-add it - If a render fails on a missing font or asset, report it; do not install anything or change the spec to work around it Enter fullscreen mode Exit fullscreen mode Note the @docs/safe-area.md import: the referenced file is loaded with CLAUDE.md, so long reference material can live in its own file. Imports help organisation but do not save context, because the imported file loads every time.

@path/to/file imports another file (relative to the importing file; up to four levels deep). For instructions that only matter in one part of the codebase, use.claude/rules/: one Markdown file per topic, and a paths list in the frontmatter makes a rule load only when Claude works on matching files.

--- paths: - " src/scenes/**/*.tsx" --- # Scene components - Every animated value is driven by the frame number, never by timers - Keep text inside the safe area described in docs/safe-area.md Enter fullscreen mode Exit fullscreen mode Does Claude Code read AGENTS.md? Yes, in recent versions: if a repository has an AGENTS.md and no CLAUDE.md or CLAUDE.local.md in the working folder or above it, Claude Code reads the AGENTS.md. Once a CLAUDE.md exists, it reads only the CLAUDE.md files by default. To keep one file for every coding tool, write the shared rules in AGENTS.md and put @AGENTS.md in your CLAUDE.md, with any Claude-only lines below it.

Claude Code also keeps auto memory: notes Claude writes for itself about your preferences and corrections, in a MEMORY.md index per repository (the first 200 lines or 25KB load each session). Use the /memory command to browse it. The division of labour: CLAUDE.md for the rules you write, auto memory for what Claude learns, skills for procedures and reusable prompts ( custom slash commands now live there too), subagents for independent checks and hooks for guarantees. After /compact, the project-root CLAUDE.md is read again from disk, so rules given only in chat are the ones that get lost: if it matters, write it down.

Details follow the official memory documentation as of November 2026.

If you make short vertical videos with Claude Code, the skill below packages a complete spec-first method for them: story, episode spec, camera, light and grade, a Remotion starter and pre-post QA.

Animated horror reels skill: Our whole playbook as a Claude Code agent skill: the hook-first story method, the episode spec template, the camera, light and grade system with a palette builder, a render-ready Remotion starter and the QA checks before you post. Make reels like ours. See the skill

Disclosure: this guide is by Homingo, the team behind the skill linked above. Everything in it works without it.