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.

10 min · Reviewed 2026

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

Project overview: what this codebase is, who it's for, the architecture in 3-5 lines
Tech stack: language, framework versions, package manager, testing tools
Conventions: naming, file structure, code style choices that aren't enforced by linters
Commands you want it to use (`pnpm test`, `pnpm lint`) and ones it should avoid
Hard rules: 'never push to main directly,' 'never edit files in /generated,' 'always run tests before committing'
Domain 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

# 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.A starter CLAUDE.md. Keep it short, list rules, name your domain.

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 check

8 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-claude-code-claude-md-creators

What is the main idea of "The CLAUDE.md File: Project Persona And Rules"?
1. CLAUDE.md is how you tell Claude Code what your project values, what your team's conventions are, and what it should never do.
2. Use AI as the final authority for the whole decision
3. Avoid checking the answer once it sounds polished
4. Focus only on speed instead of judgment
Which concept is most central to "The CLAUDE.md File: Project Persona And Rules"?
1. system prompt
2. project memory
3. conventions
4. guardrails
Which use of AI fits this topic best?
1. Let the AI decide what matters without your review
2. Use the answer before checking whether it fits the situation
3. Project overview: what this codebase is, who it's for, the architecture in 3-5 lines
4. Treat the AI output as automatically correct
What should a careful learner remember about "Smaller is better"?
1. Use AI to draft or organize ideas about project memory, then verify before acting.
2. Skip the context so the tool can guess faster
3. Treat the output as private even after sharing it online
4. Use the answer without checking the source
You want to use AI after this lesson. What is the safest next step?
1. Act immediately because the AI answer is written clearly
2. Use AI for drafting and comparison, but verify before publishing or relying on it.
3. Hide uncertainty so the final answer looks cleaner
4. Use private or sensitive details before checking permission
How should AI output about project memory be treated?
1. As proof that no other source is needed
2. As a replacement for context, consent, or expert review
3. As a draft or helper output that still needs human judgment and verification
4. As something that becomes correct when it sounds confident
Name one way to verify an AI answer about project memory.
Which action would help you apply "The CLAUDE.md File: Project Persona And Rules" responsibly?
1. Use the tool to avoid thinking through the tradeoff
2. Keep going even if the output conflicts with a trusted source
3. Treat the AI output as automatically correct
4. Tech stack: language, framework versions, package manager, testing tools

← Back to interactive lesson

Tendril · Creators · Tools Literacy

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.

10 min · Reviewed 2026

What CLAUDE.md does

What belongs in CLAUDE.md

Project overview: what this codebase is, who it's for, the architecture in 3-5 lines
Tech stack: language, framework versions, package manager, testing tools
Conventions: naming, file structure, code style choices that aren't enforced by linters
Commands you want it to use (`pnpm test`, `pnpm lint`) and ones it should avoid
Hard rules: 'never push to main directly,' 'never edit files in /generated,' 'always run tests before committing'
Domain 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

# 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.A starter CLAUDE.md. Keep it short, list rules, name your domain.

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 check

8 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-claude-code-claude-md-creators

What is the main idea of "The CLAUDE.md File: Project Persona And Rules"?
1. CLAUDE.md is how you tell Claude Code what your project values, what your team's conventions are, and what it should never do.
2. Use AI as the final authority for the whole decision
3. Avoid checking the answer once it sounds polished
4. Focus only on speed instead of judgment
Which concept is most central to "The CLAUDE.md File: Project Persona And Rules"?
1. system prompt
2. project memory
3. conventions
4. guardrails
Which use of AI fits this topic best?
1. Let the AI decide what matters without your review
2. Use the answer before checking whether it fits the situation
3. Project overview: what this codebase is, who it's for, the architecture in 3-5 lines
4. Treat the AI output as automatically correct
What should a careful learner remember about "Smaller is better"?
1. Use AI to draft or organize ideas about project memory, then verify before acting.
2. Skip the context so the tool can guess faster
3. Treat the output as private even after sharing it online
4. Use the answer without checking the source
You want to use AI after this lesson. What is the safest next step?
1. Act immediately because the AI answer is written clearly
2. Use AI for drafting and comparison, but verify before publishing or relying on it.
3. Hide uncertainty so the final answer looks cleaner
4. Use private or sensitive details before checking permission
How should AI output about project memory be treated?
1. As proof that no other source is needed
2. As a replacement for context, consent, or expert review
3. As a draft or helper output that still needs human judgment and verification
4. As something that becomes correct when it sounds confident
Name one way to verify an AI answer about project memory.
Which action would help you apply "The CLAUDE.md File: Project Persona And Rules" responsibly?
1. Use the tool to avoid thinking through the tradeoff
2. Keep going even if the output conflicts with a trusted source
3. Treat the AI output as automatically correct
4. Tech stack: language, framework versions, package manager, testing tools

← Back to interactive lesson