CLAUDE.md Examples & Templates for Claude Code

# Project: <name>

## What this is
One sentence on what the project does and who uses it.

## Rules for every session
- Explore before you code: read the files this task touches first.
- Make the smallest change that solves the task. Do not refactor uninvited.
- After any change, run it and show me Ran: <command> / Saw: <result>.
- Never claim done without proof. If a test fails, say so with the output.
- Match the existing code style, naming, and file layout.

## Commands
- Install: <install command>
- Run: <run or dev command>
- Test: <test command>
- Build: <build command>

## Watch out for
- <known gotcha, fragile file, or thing not to touch>

Works for any repo. Drop it at the root as CLAUDE.md and Claude Code loads it as standing rules every session.

# CLAUDE.md - strict mode

## The contract
You do not get to say "this should work." Every change is proven with real output.

## Loop for every task
1. Restate the goal in one line and list the 3 ways you could get it wrong.
2. Make the smallest change toward the goal.
3. Run it. Paste the exact command and the real output.
4. If it failed, find the root cause - do not guess-and-change.
5. Repeat until the goal is verifiably met.

## Definition of done
- It builds. It runs. I can see it working.
- Nothing unrelated changed (revert any drive-by edits).
- You reported Ran: <command> and Saw: <result>.

## Never
- Never push or deploy unless I say so.
- Never edit files outside the task. Mention adjacent problems, do not fix them.

Use this when the agent keeps looking done but isn't. It forces run-and-prove and kills silent scope creep.

# CLAUDE.md - Web app (Node + React)

## Stack
Frontend: React + TypeScript (Vite). Backend: Node + Express. DB: <database>.

## Commands
- Dev: npm run dev
- Test: npm test
- Lint and format: npm run lint && npm run format
- Build: npm run build

## House rules
- TypeScript strict. No `any` unless you justify it in a comment.
- Function components + hooks only. No class components.
- Keep business logic out of components - put it in /lib or /hooks.
- API calls go through /lib/api. Never fetch() inline in a component.
- After a UI change, run the dev server and confirm it renders with no console errors.

## Do not touch
- /src/generated - auto-generated, will be overwritten.
- Env files and secrets. Ask before changing any .env.

Pins down the stack, the commands, and the patterns so the agent writes code that fits your app instead of its own defaults.

# CLAUDE.md - Python project

## Setup
Python 3.11. Virtual env in .venv. Deps in pyproject.toml.

## Commands
- Install: uv pip install -e ".[dev]"
- Run: python -m <package>
- Test: pytest -q
- Lint: ruff check . && ruff format .
- Types: mypy <package>

## Rules
- Type-hint every new function. Keep functions small and pure where you can.
- Add or update a pytest test for any behavior you change. Show the green run.
- Use pathlib, not os.path string-mashing. Use logging, not print, in library code.
- No new dependency without flagging it first.

## Careful
- <migrations, data files, or anything destructive>

Gives Claude Code your exact tooling (pytest, ruff, mypy) so it tests and lints the way your repo already does.

# CLAUDE.md - Unity (C#) game

## Project
Unity <version>. Scenes in /Assets/Scenes. Gameplay code in /Assets/Scripts.

## Rules
- MonoBehaviour: cache GetComponent in Awake, never call it in Update.
- No allocations in Update or FixedUpdate hot paths (no LINQ, no new in the loop).
- Serialize private fields with [SerializeField]; do not make them public just for the inspector.
- Save-game compatibility is sacred. Never break an existing save format.
- After a change, tell me how to test it in Play mode and what I should see.

## Do not
- Do not edit .meta files or reorder scene/prefab YAML by hand.
- Do not change anything in /Assets/ThirdParty.

Bakes in the Unity performance and save-safety rules that generic AI suggestions usually miss.

# CLAUDE.md - Monorepo

## Layout
/apps/* - deployable apps. /packages/* - shared libraries. Managed by <pnpm or turbo>.

## Rules
- Change one package per task when you can. Note every package a change ripples into.
- Shared code lives in /packages, never copy-pasted between apps.
- Run the affected workspace's tests, not the whole world: <test command> --filter <pkg>.
- Respect the dependency direction: apps depend on packages, never the reverse.

## Per-package context
Each package has its own CLAUDE.md with its commands and quirks - read that one too.

Stops the agent from leaking changes across packages or running the entire test suite on a one-package edit.

# CLAUDE.md - rules + automation hooks

## Standing rules
- Run-and-prove every change. Report Ran: / Saw:. Never "should work."
- Smallest change in scope. No drive-by edits.

## Hooks (configured in .claude/settings.json, run by the harness - not by you)
- A format-on-save hook runs <formatter> after edits. Do not also format by hand.
- A pre-commit hook runs <lint + tests>. If it blocks a commit, fix the cause, never bypass it.
- Never use --no-verify to skip hooks unless I explicitly ask.

## Slash commands worth knowing
- /test - run the suite. /ship - stage, commit with a why, push (only when I say).

## Note
Automations live in settings.json because the harness executes them, not the model. If I ask for
"always do X after Y," that is a hook, not a line in this file.

Clears up the #1 CLAUDE.md confusion: recurring automations belong in settings.json hooks, while CLAUDE.md holds the rules the model reads.