🧠 CLAUDE.md — The Project's Brain

O CLAUDE.md is a Markdown file that Claude Code reads automatically at the beginning of each session. It works as a system prompt persistent: everything you write there will influence how Claude behaves in your project. It's not a suggestion; it's an instruction. The model treats the contents of CLAUDE.md as high-priority guidance.

Without CLAUDE.md, Claude Code is generic. It doesn’t know your project uses TypeScript, that you prefer tabs over spaces, or that you have a specific naming convention. With CLAUDE.md makes it a specialist in your project from the very first message. The difference is dramatic: instead of asking "what framework do you use?", it already knows and acts accordingly.

The mechanism is simple: when you start a session with claude, the agent looks for CLAUDE.md files in your environment, reads their contents, and injects them as part of the system prompt. This happens before you type anything. It’s like an automatic briefing the agent receives every morning before starting work.

Claude Code reads CLAUDE.md from three locations, in this order: ~/.claude/CLAUDE.md (global, applies to all projects), ./CLAUDE.md (at the project root) and subdir/CLAUDE.md (in any subfolder where you're working). All three are read and concatenated to form the full context.

The cascade works by addition: the content of each level builds on the previous one. The global file sets personal preferences (“never use em dashes,” “prefer TypeScript”). The project file sets the stack and conventions. The folder file sets rules specific to that area of the code. Together, all three form the full context the agent receives.

This hierarchy is powerful because it allows for separation of responsibilities. You define your personal preferences once (globally) and never have to repeat them in each project. Each project defines its own rules without interfering with the others. And special subfolders (such as src/api/) can have additional rules without cluttering the main CLAUDE.md.

~/.claude/CLAUDE.md          ← global (todas as sessoes)
./CLAUDE.md                  ← projeto (raiz do repo)
./src/CLAUDE.md              ← pasta (regras do /src)
./src/api/CLAUDE.md          ← subpasta (regras do /api)

# Todos sao lidos e somados. Mais especifico refina o geral.

The format is plain Markdown. Use headings (## Stack, ## Convencoes), bulleted lists, and code blocks for examples. The ideal tone is imperative and concrete: “Always use async/await” works better than “it would be good to consider using async/await when possible.” The model follows direct instructions much more consistently than vague suggestions.

Some conventions that work well: group by section (Stack, Conventions, Prohibitions), use bold for emphasis, include code examples when the rule is technical, and keep the file between 50 and 200 lines. Beyond that, the returns diminish and you use context unnecessarily. Every line in CLAUDE.md consumes tokens from the context window.

Avoid repeating what the model already knows. There’s no need to say "write readable code" or "use best practices." Claude already does that by default. CLAUDE.md should contain what is different in this project or in the way you work. If the default works, don't waste lines on it.

# Projeto XYZ

## Stack
- Next.js 14 (App Router)
- TypeScript strict
- Tailwind CSS
- Prisma ORM + PostgreSQL

## Convencoes
- Arquivos: kebab-case (user-profile.ts)
- Componentes: PascalCase (UserProfile.tsx)
- NUNCA usar `any`. Sempre tipar explicitamente.

## Proibicoes
- NUNCA deletar arquivos sem confirmar
- NUNCA commitar .env ou secrets
- NUNCA usar console.log em producao

The types of instructions that have the greatest impact are: stack and technologies ("this project uses Next.js 14 with App Router"), code conventions ("file names in kebab-case"), explicit prohibitions ("NEVER delete files without confirming"), and project patterns ("use the service layer pattern in src/services/").

Uppercase prohibitions (NEVER, ALWAYS) are followed more consistently. This isn't superstition: the model gives more weight to emphatic tokens. Use them sparingly so they don't become noise, but don't hesitate when the rule is critical. A well-placed "NEVER use sudo" can prevent serious accidents.

Another powerful category: workflow instructions. “Always run tests before committing,” “ask for confirmation before deleting,” “use git commit with Portuguese messages.” These instructions shape how the agent works, not just what it produces. They turn Claude from a passive tool into a disciplined coworker.

## Stack
- Next.js 14 (App Router)
- TypeScript strict
- Tailwind CSS
- Prisma ORM + PostgreSQL

## Convencoes
- Arquivos: kebab-case (user-profile.ts)
- Componentes: PascalCase (UserProfile.tsx)
- NUNCA usar any. Sempre tipar explicitamente.
- Testes: colocar em __tests__/ ao lado do arquivo.

## Padroes
- API routes usam o pattern em src/app/api/[resource]/route.ts
- Validacao com Zod em todo input de API

## Workflow
- Sempre rode npm test antes de commitar
- Commit messages em portugues, imperativo

Good CLAUDE.md examples share a few characteristics: they’re short (rarely over 150 lines), focus on what is different in that project (they don't repeat generic knowledge), and include at least one section of explicit prohibitions. Studying real examples is the fastest shortcut to writing an effective CLAUDE.md.

A common anti-pattern is a CLAUDE.md that tries to teach the model programming ("use good coding practices"). Claude already knows good practices. What it needs to know is what the your specific practices. Another anti-pattern: copying the entire framework documentation. The model already knows React, Next.js, etc. Tell it which version you use and how you use it, not what it is.

An excellent example is the CLAUDE.md in Anthropic's own Claude Code repository. It's concise, focuses on internal conventions (how to run tests, how to commit, which architectural patterns to follow), and has clear prohibitions. Another good example: popular open source projects that have adopted the practice and publish their CLAUDE.md files on GitHub.

The CLAUDE.md should go in the git, along with the code. This ensures anyone (or any agent) who clones the repo gets the context automatically. Treat it like a config file: versioned, reviewed, and updated along with the project. Pull requests that change the stack or conventions should include the corresponding update to CLAUDE.md.

A healthy routine: review the CLAUDE.md once a month or when something significant changes in the project (a new lib, a new pattern, a new team member). Between reviews, use /memory to add quick notes that persist without editing the file directly. /memory is the shortcut; CLAUDE.md is the canonical source.

An outdated CLAUDE.md is worse than none at all, because the agent will confidently follow incorrect instructions. If you removed a library from the project but CLAUDE.md still says "use lib X," Claude will try to use it and fail. If you changed ORMs, update CLAUDE.md. If you changed naming conventions, update it. The rule is simple: if it changed in the code, change it in CLAUDE.md.

Manutencao do CLAUDE.md:
[ ] Commitar no git junto com o codigo
[ ] Revisar mensalmente ou ao mudar stack
[ ] Remover instrucoes obsoletas imediatamente
[ ] Usar /memory pra notas rapidas entre revisoes
[ ] Incluir atualizacao em PRs que mudam convencoes
[ ] Manter entre 50-200 linhas (nao deixar inchar)