Claude Code 的 CLAUDE.md 最佳實踐：應寫甚麼、略去甚麼及範本

Originally published on Homingo Learn.

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.

What CLAUDE.md is (and is not)

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.

Where CLAUDE.md files go

• Project: ./CLAUDE.md or ./.claude/CLAUDE.md, committed so the whole team shares it.
• Personal, all projects: ~/.claude/CLAUDE.md.
• Personal, this project: ./CLAUDE.local.md (add it to .gitignore yourself).
• Organisation: a managed policy file that IT deploys to every machine (for example /etc/claude-code/CLAUDE.md on Linux).

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.

How to create a CLAUDE.md with /init

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.

What belongs in CLAUDE.md

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:

• Commands: how to build, test, lint and run one test, with the exact command.
• Conventions that differ from the defaults: “use pnpm, not npm”, “API handlers live in src/api/handlers/”.
• Sources of truth: which file wins when two disagree, which files are generated and must not be edited.
• Pitfalls and their reasons: one line each, with the why, so Claude can apply it to cases you did not list.
• Boundaries: what to ask before doing (new dependencies, migrations, anything that deploys).

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

What to skip in CLAUDE.md

• Anything Claude can read from the code: folder trees, dependency lists, descriptions it can rebuild in seconds. Keep the non-obvious architectural decisions and their reasons.
• Multi-step procedures and one-area knowledge: move them into a skill (only its short description is always loaded; the body loads when needed) or a path-scoped rule.
• Rules that must never be broken: enforce them with permissions or hooks; a sentence can be missed.
• History and changelogs: what changed last month is git’s job.
• Secrets: never. Project files are committed, and anything in a memory file can end up in Claude’s context.

CLAUDE.md template and example

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

CLAUDE.md skeleton

# <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>

Filled in for a Remotion repository that renders vertical videos from a spec file:

CLAUDE.md

# 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

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.

Imports and path-scoped rules

@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.

.claude/rules/scenes.md

---
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

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.

How long should CLAUDE.md be? Size and upkeep

• Aim for under 200 lines per file. Longer files cost context in every session and lower adherence; Claude Code warns at startup when a file is over the recommended length.
• Remove contradictions. If two lines (or two files) disagree, Claude may pick either. Re-read the file when you add to it.
• Leave notes for humans in HTML comments. Block-level <!-- ... --> comments are stripped before the file reaches Claude, so they cost no tokens.
• Prune with each change. When a rule stops being true, delete it in the same commit that changed the code.

CLAUDE.md vs auto memory, skills, subagents and hooks

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.