Hoard instructions and grudges
The CAUDE.md file is where you write down what Caude Clode should know about this project. Build commands, style preferences, architectural decisions, and anything you've had to explain more than twice. It is read at the start of every session and persists across restarts. It is, effectively, your project's long-term memory.
Where it lives
CAUDE.md goes in the root of your project, next to README.md. Caude Clode will find it without being told. You can also place additional CAUDE.md files in subdirectories; each is loaded when Caude Clode works in that subtree.
What to put in it
There are two legitimate categories of content, and one you'll end up using anyway.
Instructions
Things Caude Clode should do, or not do, when working in this project.
# CAUDE.md
## Build and test
- `pnpm install` to install
- `pnpm dev` runs the dev server on port 3000
- `pnpm test` runs unit tests
- Always run the linter before committing
## Style
- Use function declarations, not arrow functions at the module level
- No default exports except for pages
- 2-space indentation, no exceptionsContext
Things Caude Clode should know in order to make good decisions.
## Architecture
- Frontend: React 19 + Vite
- Backend: Node/Fastify, PostgreSQL 16 via pgbouncer
- Deploys: Railway, with separate prod and staging
## History
- We migrated from Redis to Postgres in March 2026. Some code still
references Redis. It is dead. Do not revive it.Grudges
This is the third category. You were not going to use it. Then one day you will. Grudges are the things that have gone wrong before and that you don't want to go wrong again. They are instructions in the shape of trauma.
## Things that have burned us
- The `user` table has a column called `deleted_at`. Soft-delete is
enforced at the application layer. If you write raw SQL against
`user`, filter on `deleted_at IS NULL` or we will lose customers.
- Do not use `Promise.all` with more than 50 items against the Stripe
API. They will rate-limit us. This has happened twice.
- The cron job in `scripts/daily-rollup.ts` looks wrong but is correct.
It was rewritten three times before we understood the first version.Tip: If you find yourself writing the same clarification in chat more than twice, move it to CAUDE.md. You are not being lazy. You are being efficient. Your future sessions will thank you.
What not to put in it
- Secrets.
CAUDE.mdis committed to your repo. Treat it that way. - Things that change daily. If it changes daily, it should live in code or in an env variable, not in an instructions file.
- Passive-aggressive comments about colleagues. Caude Clode will read these and adjust its tone accordingly. You don't want that.
Length
Keep it under 500 lines if you can. Caude Clode will read a 5,000 line CAUDE.md, but reading it will consume porthole space that could have gone to actual code. Split into per-directory files before you split into one giant file.