General Project Rules

When to use this

The default starting point for any project using Claude Code. Deliberately short, because the most common failure with these files is writing a long one that drifts out of date and then misleads the agent.

Start here and add only when you notice yourself repeating an instruction.

The template

# CLAUDE.md

## What this is

[One sentence.]

## Commands

- `[command]` [what it does]
- `[command]` [what it does]

Before saying a change is complete, run: `[test command]` and `[typecheck or lint command]`.

## Conventions

- [The pattern you want followed, with a file to copy from]
- [Where tests go]
- [How errors are handled]

## Do not

- [The thing you have already had to correct twice]
- Do not add dependencies without asking
- Do not commit unless asked

## Ask first

- Adding a dependency
- Changing config or CI
- Deleting files
- Anything touching auth, payments, or user data

What to change

Fill in the commands from your package.json or Makefile. These are the highest value lines in the file, because a wrong command wastes a whole exchange.

For conventions, point at a real file rather than describing a pattern in the abstract. "Follow the error handling in src/errors.ts" works better than a paragraph explaining your error philosophy.

Leave "do not" mostly empty at first. Fill it from experience, adding a line each time you correct the agent about the same thing twice. A rule that came from a real mistake is worth ten rules you imagined in advance.

Note on scope

Claude Code reads CLAUDE.md from the project root, and also ~/.claude/CLAUDE.md for rules that apply to everything you do. Personal preferences belong in the global file; project facts belong in the project file.