Guia prático para escrever CLAUDE.md: comandos, arquitetura, operações proibidas e referências a arquivos, com um projeto Rails real.
Toda vez que você abre o Claude Code, ele começa do zero — sem memória da sessão anterior, sem saber o que seu projeto faz, sem saber se o comando de teste é rspec ou pytest, e sem conhecer as operações que estão proibidas.
O CLAUDE.md resolve isso. É um arquivo de instruções persistente que você escreve para o Claude e que é carregado automaticamente no início de cada conversa. Um bom CLAUDE.md faz o Claude entrar no modo de trabalho imediatamente — sem perguntas desnecessárias, sem erros básicos.
O Claude Code suporta um sistema de CLAUDE.md em camadas com três níveis:
~/.claude/CLAUDE.md: Configuração global, aplica a todos os seus projetos. Use para preferências universais como "nunca faça auto-commit no git" ou "responda em português".CLAUDE.md na raiz do projeto: Configuração em nível de projeto. O local mais comum.CLAUDE.md em subdiretórios: Carregado apenas quando o Claude trabalha com arquivos daquele diretório. Ideal para dar instruções específicas ao frontend/, api/ ou infra/.Múltiplos arquivos CLAUDE.md se acumulam — arquivos mais específicos têm prioridade sobre os mais gerais.
Um parágrafo dizendo ao Claude o que é o projeto e quais tecnologias usa:
## Project Overview
**Pickful AI** is a Ruby on Rails 8 cryptocurrency-focused social media platform.
Users can create posts, follow others, earn points, track coin prices,
and participate in a gamification system with leaderboards and VIP status.
- **Ruby Version:** 3.3.2
- **Rails Version:** 8.0.2
- **Database:** PostgreSQL with 4 separate databases (primary, cache, queue, cable)
Incluir os números de versão é importante. Saber que é Rails 8 evita que o Claude sugira padrões da era Rails 6. Saber que há 4 bancos de dados evita erros nas migrations.
Esta é a seção de maior retorno em qualquer CLAUDE.md. Sem ela, o Claude adivinha — e erra.
## Development Commands
### Running the Application
bin/dev # Start Rails server (port 3000) + Tailwind watcher
bin/rails server # Start Rails server only
### Testing
bundle exec rspec # Run all tests
bundle exec rspec spec/models # Run model tests
bundle exec rspec spec/path/to/file_spec.rb:42 # Run test at line 42
### Linting & Security
bin/rubocop # Run RuboCop linter (Rails Omakase preset)
bin/rubocop -a # Auto-correct offenses
bin/brakeman # Security vulnerability scan
### Deployment (Kamal)
bin/kamal deploy # Deploy to production
bin/kamal app logs # View application logs
bin/kamal app console # Remote Rails console
Esta lista diz ao Claude: testes rodam com bundle exec rspec, não rails test; o deploy é com Kamal, não Capistrano ou Fly.io; o linter é RuboCop com o preset Rails Omakase. Sem isso, o Claude tem que adivinhar tudo.
O objetivo das notas de arquitetura é documentar decisões que não são visíveis no código. O Claude consegue ler a estrutura de diretórios; ele não consegue saber por que está organizada dessa forma.
## Key Architectural Patterns
**Services Layer:**
Complex business logic extracted to `app/services/`.
Keep controllers thin, delegate to services.
**Authorization:**
Pundit policies in `app/policies/`.
Check UserPolicy, PostPolicy, etc. for permission rules.
**Background Jobs:**
Use `app/jobs/` for async processing.
Solid Queue handles job processing.
Esses três pontos dizem ao Claude: não acumule lógica de negócio nos controllers; procure as regras de permissão em app/policies/; use Solid Queue para qualquer coisa que precise de processamento assíncrono.
Agrupar os modelos de domínio por área funcional também tem valor:
## Core Domain Models
**Social Features:** User, Follow, Block, Referral
**Content:** Post, Comment, Topic, Tag, Draft
**Engagement:** Like, Favorite, Share, Report
**Cryptocurrency:** Coin, CoinPrice, Payment
**Gamification:** PointTransaction (VIP status at 400+ points)
Isso é mais eficiente do que fazer o Claude escanear o app/models/ por conta própria, e também transmite semântica de negócio — como o fato de que 400 pontos é o limite VIP, algo que não é óbvio lendo o código.
Esta é a seção mais ignorada e, frequentemente, a mais crítica:
## Important Configuration
**Multi-Database:**
Always be aware of the multi-database setup.
Most migrations should target the primary database
unless working with cache/queue/cable features.
**Lexxy Integration:**
The app uses Lexxy gem (beta) for enhanced ActionText editing.
Configured in config/application.rb with:
config.lexxy.override_action_text_defaults = false
**Asset Handling:**
Uses Propshaft (not Sprockets).
Assets in app/assets/ are served without fingerprinting in development,
with fingerprinting in production.
Esses três pontos são do tipo "não escreva e você vai se arrepender": múltiplos bancos de dados requerem especificar o alvo da migration; Lexxy é uma gem em beta com comportamento diferente do ActionText padrão; Propshaft funciona de forma diferente do Sprockets.
Esta é a seção mais subestimada. Dizer ao Claude o que não fazer é muito mais eficiente do que corrigi-lo depois.
## Do Not
- Do NOT run `git commit` automatically — always ask me to confirm first
- Do NOT modify files in `db/migrate/` that already exist
- Do NOT touch `.kamal/secrets*` files — production secrets, handle manually
- Do NOT run `bin/kamal deploy` without explicit instruction
O primeiro item pertence a quase qualquer projeto. O comando de deploy é ainda mais importante — um bin/kamal deploy errado vai direto para produção.
O CLAUDE.md suporta referências @ para incluir outros arquivos:
Configuração de deploy: @config/deploy.yml
Schema do banco de dados: @db/schema.rb
O Claude lê esses arquivos quando necessário. db/schema.rb é especialmente útil — em projetos Rails é a fonte única da verdade para a estrutura do banco de dados.
Escrever demais: O CLAUDE.md consome janela de contexto. Colar o README inteiro deixa menos espaço para o Claude trabalhar com o código real. Escreva apenas o que o Claude não consegue derivar lendo o código.
Diretrizes vagas: "Escreva bom código" não serve de nada. Seja específico: "Não coloque lógica de negócio diretamente nos controllers — delegue para app/services/".
Esquecer de atualizar: Se você migrou de Sprockets para Propshaft e o CLAUDE.md não acompanhou, o Claude operará com suposições obsoletas. Inclua a atualização do CLAUDE.md no checklist de qualquer refatoração importante.
Escrever exemplos de código: Exemplos consomem contexto, e o Claude lê código real com mais precisão do que snippets ilustrativos. Use referências @ para apontar para arquivos reais.
# [Nome do projeto]
[Descrição em uma frase]
- **Ruby:** x.x.x
- **Rails:** x.x.x
- **Database:** PostgreSQL
## Development Commands
bin/dev # Start server
bundle exec rspec # Run tests
bin/rubocop # Lint
bin/kamal deploy # Deploy (ask before running)
## Architecture
[Como se dividem as responsabilidades entre Services / Jobs / Policies]
[Modelos de domínio agrupados por área funcional]
## Important Notes
[Configuração não óbvia, comportamento especial de gems]
## Do Not
- Do NOT run git commit automatically
[Outras operações de alto risco]
Comece aqui e preencha o que o seu projeto realmente precisa. Não é preciso cobrir tudo — um CLAUDE.md com cinco pontos precisos vale mais do que um cheio de ruído.