CLAUDE.MD
The project's DNA, in text.
The file Claude reads every time it opens the project. It is not a README. README is for the human cloning the repo. CLAUDE.md is a briefing for an agent: what the project IS, the voice, the hard constraints, the dangerous commands, the safe shortcuts.
Keep it short. No narration. Point to detailed docs instead of duplicating them. If Claude keeps making the same mistake over and over, a line is missing here.
Concrete tip: start with the monorepo map, the non-negotiable conventions, and the shortcuts that keep you from wiping production. Everything else becomes a link.
In practice
# CLAUDE.md (repo root)
## Stack
- Next.js 16 + Convex backend
- Turbo monorepo, main app in apps/sapiens/
## Don'ts
- Never run `npx convex *` from the root, only inside apps/sapiens/
- No em-dash in .md files (a hook blocks it)
## Safe shortcuts
- npm run dev (starts sapiens + aitag + decks)
- npm run convex:deploy (prod deploy)This practice is part of Claude Code OS, the full blueprint of the practices that separate following a tutorial from actually working with Claude. Ler em português.