Lesson 455 of 2116
The CLAUDE.md File: Project Persona And Rules
CLAUDE.md is how you tell Claude Code what your project values, what your team's conventions are, and what it should never do. It is the single highest-leverage config you write.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1What CLAUDE.md does
- 2project memory
- 3system prompt
- 4conventions
Concept cluster
Terms to connect while reading
Section 1
What CLAUDE.md does
Claude Code reads CLAUDE.md at the start of every session. Whatever you put there becomes part of the system prompt for the rest of that session. It is project-scoped (lives in your repo), version-controlled (commit it), and shared with anyone using Claude Code on your codebase.
What belongs in CLAUDE.md
- 1Project overview: what this codebase is, who it's for, the architecture in 3-5 lines
- 2Tech stack: language, framework versions, package manager, testing tools
- 3Conventions: naming, file structure, code style choices that aren't enforced by linters
- 4Commands you want it to use (`pnpm test`, `pnpm lint`) and ones it should avoid
- 5Hard rules: 'never push to main directly,' 'never edit files in /generated,' 'always run tests before committing'
- 6Domain context: the language of the business problem, key entities, the way you talk about them
What does NOT belong
- API keys, tokens, secrets — these belong in env vars and .gitignore
- Long-form documentation that already lives in /docs
- Pet phrases or vague vibes that don't translate to action
- Anything you'd be unhappy about appearing in a code review
- Personal preferences for individual developers — keep CLAUDE.md team-wide
Example skeleton
A starter CLAUDE.md. Keep it short, list rules, name your domain.
# Project: Acme Reporting API
Next.js 15 (App Router) + Postgres + Drizzle.
## Stack
- Node 20, pnpm, TypeScript strict.
- Tests: Vitest. Lint: Biome.
## Conventions
- Server logic in `src/server/*`. Components in `src/app/`.
- One feature per folder. No cross-imports between feature folders.
- Public env vars start with `NEXT_PUBLIC_`.
## Rules
- Never edit anything under `src/generated/`.
- Always run `pnpm lint && pnpm test` before commit.
- Use Drizzle migrations for schema changes — never raw SQL.
- Pause and ask before running any `db:reset` or destructive script.
## Domain language
- A 'report' is a user-defined query saved with a schedule.
- An 'audit row' is the immutable record produced by a report run.Key terms in this lesson
The big idea: CLAUDE.md is the team contract for the agent. Keep it short, keep it shared, and back the load-bearing rules with real tooling.
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “The CLAUDE.md File: Project Persona And Rules”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 10 min
Spaces: Building Team Knowledge Bases In Perplexity
Spaces are Perplexity's project containers — system prompts, files, and shared chat history. They turn the search engine into a research workspace.
Creators · 10 min
Your First Soul: A Ten-Minute Hello World
A minimal soul, a personality, a first message, a peek at memory. The point is not the soul — the point is feeling how OpenClaw thinks. Step 1 — Define the soul A soul lives in a folder, typically under `souls/`, and is defined by a small file that names it, gives it a persona, and points at the model it should use.
Creators · 9 min
OpenClaw Config And Project Layout
Where files live, what `openclaw.toml` controls, which env vars matter, and how to put the whole thing in version control without leaking secrets. Provider choice, default model, where files live, log level, default heartbeat cadence — all here.