Write a CLAUDE.md That Actually Changes How Claude Code Works on Your Project

TL;DR: CLAUDE.md only changes Claude Code's behavior when it contains mechanically-followable instructions — constraints, exact commands, file paths, and anti-patterns, not descriptions of intent.

CLAUDE.md is Claude Code's project memory — read at the start of every session and consulted before every action. But most developers write it like a README: "This is a Next.js app using TypeScript and Tailwind." That describes the project; it doesn't constrain behavior. Claude already knows what TypeScript looks like. The patterns that actually work are ones Claude can check against mechanically.

---

1. Hard constraints (the most powerful)

Tell Claude what it must never touch. These are checked before any edit:

## Constraints
- Never edit `public/blog/posts.json` directly — all blog content goes through `scripts/publish-post.mjs`
- Never commit `.env*` files
- Never install a package without asking first — the pnpm workspace has strict version pins

2. Default commands

Claude Code tries to run tests and lint on its own. Tell it exactly what to use:

## Commands
- Test: `pnpm test`
- Lint: `pnpm run lint`
- Build: `pnpm run build` (runs type-check; never skip errors)
- Dev server: `pnpm run dev` at http://localhost:3000

3. Architecture that isn't obvious from filenames

Patterns Claude can't infer from structure alone:

## Architecture notes
- App Router is the live code (`app/`). The legacy `src/` tree is retired — don't touch it.
- Blog posts render from `posts.json`; there are no per-post `.md` files.
- All images live on the GitHub Release CDN, never in the repo.

4. Coding standards as negative rules

"Prefer X" is weak. "Never do Y" is strong:

## Code standards
- No default exports in component files — named exports only
- Never add console.log to committed code
- No `any` in TypeScript without a comment explaining why

5. Scope the file to this project

Project-agnostic preferences go in ~/.claude/CLAUDE.md (global). Your project file should only contain what is specific and different about this codebase. Mixing global preferences with project rules dilutes both.

---

What doesn't work:

• Long prose descriptions of the tech stack (Claude knows what React is)
• "Prefer readable code over clever code" (unmeasurable)
• Rules about things Claude doesn't touch (wasted tokens on every session start)
• Historical decisions ("We switched from X to Y because...") — put those in git commit messages

Keep it short. Every sentence costs tokens at the start of every session. The best CLAUDE.md files are 20–40 lines of precise constraints, not a 200-line architectural doc.

Sources: Claude Code project memory docs | Claude Code best practices