Need AI Training/Help?CloudYeti.io/meet
MarkdownMe
Agent instruction guide

What Should Go in a CLAUDE.md File

Decide what belongs in CLAUDE.md and what belongs in the README, a path-scoped rule, or a skill. One test per line, applied to a real file.

Direct answer

Put in CLAUDE.md only the facts Claude needs in every session: build, test, and lint commands with exact flags, project layout, naming conventions, and concrete do-not-do rules. Apply one test per line: would removing this line cause a mistake Claude would not otherwise make? Anything Claude can read from the code belongs in the code. A multi-step procedure belongs in a skill. Guidance that applies to one file type belongs in a path-scoped rule under .claude/rules/. Claude Code documents a target of under 200 lines per file, because longer files reduce how consistently the instructions are followed.

Open CLAUDE.md Reviewer

When to use this

  • You are writing a CLAUDE.md from scratch and do not know where to start.
  • You ran /init and want to know which generated sections to keep.
  • Your file repeats the README and you cannot tell which lines earn their place.

Steps

  1. Paste your draft CLAUDE.md into the reviewer.
  2. For each line, ask if removing it would cause a mistake. Delete the lines that fail.
  3. Move any procedure with more than three steps into a skill under .claude/skills/.
  4. Move any rule that applies to one file type into .claude/rules/ with a paths frontmatter field.
  5. Keep exact commands, project layout, conventions that differ from tool defaults, and real anti-patterns your team has hit.

Example review focus

CLAUDE.md excerpt
# CLAUDE.md

This is a Next.js 16 app with TypeScript and Tailwind.

## Structure
- src/app holds routes
- src/components holds components
- src/lib holds helpers

## Rules
- Write clean code.
- Test your changes.
- Follow the existing patterns.

## Deploy
We deploy to S3 and CloudFront.
What to fix
Cut the structure section: Claude reads the directory tree already. Cut the three generic rules: none is verifiable. Replace them with the facts Claude cannot infer — `npm run test` uses Vitest not Jest, `npm run audit:ai` must pass before a commit, and the deploy fires from a push to main, so never run deploy.sh locally.

Common mistakes

  • Do not copy the README into CLAUDE.md; Claude can open the README when it needs it.
  • Do not write rules you cannot verify, such as write clean code or be careful.
  • Do not use @path imports to shrink the file; imported files still load into context at launch.
  • Do not put deploy checklists or release procedures here; those are skills that load on demand.

FAQ

How long should a CLAUDE.md be?
Claude Code's memory documentation gives a target of under 200 lines per file. Longer files consume more context and reduce adherence. Most repositories need far less than 200 lines.
Should I document my file structure in CLAUDE.md?
Usually no. Claude can read the directory tree. Document a path only when the name does not explain the contents, such as an API handler directory that is not called handlers.
What is the difference between CLAUDE.md and auto memory?
You write CLAUDE.md; Claude writes auto memory. Auto memory stores learnings Claude picks up from your corrections in ~/.claude/projects/<project>/memory/. CLAUDE.md stores the instructions and rules you decide on.
Where does the project CLAUDE.md go?
Either ./CLAUDE.md or ./.claude/CLAUDE.md at the repository root. Personal preferences that should not be committed go in ./CLAUDE.local.md, which you add to .gitignore.

Related CLAUDE.md guides

Review CLAUDE.md for Token Waste

Find vague, repeated, or unused CLAUDE.md instructions that cost tokens every Claude Code turn without improving behavior.

CLAUDE.md Missing Commands Checklist

Check whether a CLAUDE.md includes the build, test, lint, dev server, deploy, and verification commands an agent needs before editing.

CLAUDE.md Repo Boundaries and Rules

Write CLAUDE.md rules that tell agents which files to edit, which files to avoid, and how to handle dirty worktrees safely.

Review CLAUDE.md Before Converting to AGENTS.md

Clean a CLAUDE.md first, then convert it into AGENTS.md, Cursor rules, GitHub Copilot instructions, or Windsurf rules.

Claude Code Is Not Following CLAUDE.md — How to Fix It

Diagnose why Claude Code ignores your CLAUDE.md: the file never loaded, the rule is vague, two files contradict, or the rule needs a hook instead.

CLAUDE.md vs .claude/rules vs Skills — Which File Owns What

Route each instruction to the right file: always-loaded CLAUDE.md, path-scoped .claude/rules/, or on-demand skills. One question decides it.

CLAUDE.md Best Practices Checklist — Audit Your File Against 8 Rules

Run your CLAUDE.md through eight checks: size, specificity, exact commands, anti-patterns, structure, contradictions, enforcement, and staleness.

Desk gear for long writing sessions

A few things that help if you write docs, tickets, and specs on a laptop all day.

Dock

Anker 5-in-1 USB-C Hub

One cable turns a laptop into a desk setup. Drives a 4K display, charges at up to 85W, and adds three data ports.

  • 4K HDMI output
  • 85W max power delivery
  • 1x USB-C + 2x USB-A, 5Gbps each
  • MacBook Pro, MacBook Air, Dell
Check price on Amazon →Monitor · I use this

Dell 27" S2725QC 4K

The monitor I write and review documents on. 163 PPI keeps small text sharp, and USB-C carries video and power on one cable.

  • 3840x2160 IPS, 163 PPI
  • 120Hz, 4ms, FreeSync Premium
  • 99% sRGB
  • USB-C, HDMI, DisplayPort
Check price on Amazon →Laptop

Apple MacBook Neo 13" (A18 Pro)

The cheapest way into an Apple-silicon machine that runs local models. Fanless, and the Liquid Retina panel holds small text at a full day of reading.

  • A18 Pro chip, built for Apple Intelligence
  • 8GB unified memory, 256GB SSD
  • 13-inch Liquid Retina display
  • 1080p FaceTime HD camera
Check price on Amazon →

Amazon affiliate links. We earn a commission on qualifying purchases at no extra cost to you.