Onde guardar as specs do projeto para o Claude Code achar sem colar tudo de novo

Toda sessão nova, o mesmo ritual: abre o chat e cola de novo aquele documentão de especificação que você já colou ontem, e anteontem

Só que o Claude Code não precisa disso

Ele já tem lugares definidos onde lê instrução sozinho no começo de cada sessão, e a escolha do arquivo certo é o que decide se a sua spec chega ao contexto ou fica dormindo no repositório sem ninguém abrir 🙂

Bora organizar isso de vez?

O que você precisa antes de organizar as specs

Nada de PC da Nasa aqui, a lista é curta:

• Claude Code instalado e rodando de dentro da pasta do projeto
• o projeto num repositório git, porque a memória automática é gravada por repositório, em ~/.claude/projects/<project>/memory/, ou seja, FORA do seu projeto (todos os worktrees do mesmo repositório dividem esse mesmo diretório)
• e a parte que quase todo mundo pula: saber quais são os quatro níveis da hierarquia de instrução

Esses quatro níveis são aditivos, todos contribuem conteúdo pro contexto ao mesmo tempo:

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

E um aviso pra tu não perder tempo: o ./CLAUDE.local.md consta como deprecated na documentação de memória

Se algum dia foi ali que você guardou a spec, é hora de mudar de lugar

Quer espiar o que o Claude já anotou por conta própria? O comando /memory abre a pasta de auto memory de dentro da sessão, e os arquivos são markdown puro, editáveis e apagáveis

Passo a passo: deixar a spec no lugar que o Claude Code lê sozinho

A lógica aqui é simples: o que precisa valer SEMPRE vai pro arquivo que carrega sozinho, o que é detalhe de um trabalho específico fica num arquivo versionado que você aponta na hora certa

1. Rode /init na pasta do projeto

Ele analisa o projeto e gera um CLAUDE.md inicial com comandos de build, instruções de teste, diretórios-chave e as convenções que detectou

cd meu-projeto
claude
/init

O erro comum deste passo: achar que /init só serve em projeto zerado

Ele também roda em projeto que JÁ tem o arquivo, revisando o que está lá e sugerindo melhorias, então não tem medo de rodar de novo

2. Escolha entre a raiz e a pasta .claude, e commite

A instrução de projeto pode ficar em ./CLAUDE.md ou em ./.claude/CLAUDE.md, tanto faz, o importante é que ela entra no git junto com o código

git add CLAUDE.md
git commit -m "docs: instrucoes do projeto pro Claude Code"

O erro comum deste passo: deixar o arquivo no gitignore "porque é config minha"

Aí o colega clona o repo, abre a sessão e o Claude não sabe nada do projeto

3. Mantenha o CLAUDE.md curto

Esse arquivo é carregado INTEIRO, independentemente do tamanho, e a documentação é direta ao dizer que arquivos menores geram melhor adesão às instruções

O erro comum deste passo: transformar o CLAUDE.md no manual do projeto, com histórico, decisões antigas e explicação de cada endpoint

Ele não é a spec, ele é o mapa que diz onde a spec mora

4. Quebre em imports quando fizer sentido, sabendo o que isso resolve

Dentro do CLAUDE.md você importa outros arquivos com a sintaxe @caminho/do/arquivo, aceitando caminho relativo e absoluto, inclusive na home do usuário

# Projeto X

Regras de commit: @docs/commits.md
Padrão de teste: @docs/testes.md

As importações podem ser recursivas, com um limite de 5 saltos

O erro comum deste passo (e esse é o mais caro): achar que quebrar em imports economiza contexto

Não economiza

Os arquivos importados carregam junto na abertura da sessão, você ganha ORGANIZAÇÃO, não espaço

5. Aponte o documento certo no começo da sessão com @

Dentro do prompt, o @ referencia arquivos e pastas com correspondência aproximada do nome, então @auth acha auth.js ou AuthService.ts

@prd.md leia a spec e me diga por onde começar

Tem um bônus que pouca gente sabe: ao referenciar um arquivo com @, os CLAUDE.md do diretório desse arquivo e dos diretórios pais entram automaticamente no contexto

O erro comum deste passo: colar a especificação inteira no chat mesmo tendo ela salva no repositório

É o mesmo conteúdo, ocupando contexto duas vezes

6. Mova a referência que não é usada sempre pra .claude/rules/ ou pra Skills

O Claude Code suporta regras com escopo por caminho, gravadas em arquivos markdown dentro de .claude/rules/, um tópico por arquivo (testing.md, api-design.md, por aí vai)

O segredo é o frontmatter YAML com o campo paths:

---
paths:
  - "src/api/**/*.ts"
---

Toda rota nova precisa de teste de contrato

Essa regra só carrega quando o Claude trabalha em arquivos que casam com o padrão, e não a cada uso de ferramenta

Isso sim economiza contexto

A própria documentação recomenda tirar conteúdo de referência do CLAUDE.md sempre carregado e mover convenções e material de referência pra Skills, Plugins ou servidores MCP, que carregam só quando são relevantes

7. Confira com /context o que realmente foi carregado

Ele mostra o uso do contexto por categoria, ao vivo, incluindo quais arquivos CLAUDE.md e de auto memory entraram, com sugestões de otimização

/context

O erro comum deste passo: nem rodar

Antes de você digitar UMA letra, o CLAUDE.md, a auto memory, os nomes de ferramentas MCP e as descrições de skills já estão ocupando contexto

Monorepo, regras por caminho e Skills: quando cada lugar ganha

Não existe um lugar único certo, existe o lugar certo pro TIPO de conteúdo

Monorepo: o pacote onde você abre a sessão importa

O Claude Code carrega o CLAUDE.md do diretório de trabalho e de todos os diretórios pais no início da sessão

Na prática, iniciando a sessão de dentro de packages/api/, carregam o packages/api/CLAUDE.md e o CLAUDE.md da raiz

E nada de packages/web/ entra no contexto

Já o CLAUDE.md de um subdiretório carrega SOB DEMANDA: ele entra quando o Claude lê um arquivo daquela pasta com a ferramenta Read, não na abertura da sessão

Isso muda seu ritual: se a spec é do pacote, abra a sessão dentro do pacote

Regras de escopo estreito: .claude/rules/ com paths

Aquele monte de convenção que só vale pra uma parte do código (padrão de teste, desenho de API, regra de migration) não merece morar no arquivo que carrega sempre

Um tópico por arquivo, o paths no frontmatter, e pronto: a regra aparece quando o Claude toca nos arquivos daquele escopo

Material de referência longo: Skills

Skills vivem em arquivos SKILL.md, com frontmatter YAML (o campo description é recomendado) mais o conteúdo em markdown

O ponto forte: por padrão, só as DESCRIÇÕES carregam no início da sessão, o conteúdo completo vem sob demanda

E tem divulgação progressiva: o essencial fica no SKILL.md e a referência detalhada vai pra arquivos separados, que o Claude lê só quando precisa

É o oposto do CLAUDE.md, que entra inteiro sempre

O que aprendi levando um plano pronto para o Claude Code executar

No vídeo do projeto completo eu comecei querendo montar um prompt único, gigante, com tudo que o app precisava ter

Olhei aquilo e troquei de ideia na hora

Virou um PRD, e o motivo é bem prático: prompt muito grande atrapalha o Claude Code e faz ele pular partes do pedido

Aí o fluxo ficou assim: copiei o PRD, criei um arquivo prd.md dentro da pasta do projeto e colei o conteúdo lá

Detalhe bobo que economiza tempo: o texto já sai formatado em Markdown, bastou apagar a primeira linha de resposta do assistente antes de salvar

Depois eu abri o Claude Code numa pasta vazia e dei a primeira instrução referenciando o prd.md junto de um prompt curto, em vez de despejar a especificação inteira no chat

Mudou a execução

O documento fica no projeto, versionado, e a conversa fica leve

Uma coisa que eu recomendo antes de soltar a ferramenta pra editar arquivo: use o modo plano

Nele o Claude pesquisa e propõe as mudanças SEM editar nada

O Shift+Tab entra e sai do modo plano, o /plan prefixa um prompt único, a barra de status mostra o ⏸ plan mode e o Ctrl+G abre o plano proposto no seu editor de texto padrão

Ler o plano antes é o mesmo hábito de entender o fluxo do primeiro projeto ao deploy: você para, lê, discorda, e só então deixa rodar

E aqui vai o lembrete honesto pra fechar: instruções em CLAUDE.md são seguidas de forma probabilística

O Claude lê e tenta seguir, sem garantia de cumprimento estrito, ainda mais quando as instruções são vagas ou conflitantes

Por isso vale saber o que perguntar antes de aceitar qualquer coisa que ele te devolve, mesmo com a spec redondinha no lugar certo

Ali você me vê montando o plano, salvando ele em arquivo dentro do projeto e mandando o Claude Code executar em cima do documento, sem colar a spec no chat

Próximo passo

A regra prática cabe em três linhas:

• CLAUDE.md curto e commitado, com o mapa do projeto
• spec detalhada em arquivo versionado, apontado com @ no começo da sessão
• referência pesada em .claude/rules/ com paths ou em Skills

Seu próximo passo concreto é rodar /init e, na MESMA sessão, rodar /context

Você vai ver, por categoria, quanto a abertura já consome antes de digitar qualquer coisa: CLAUDE.md, auto memory, nomes de ferramentas MCP e descrições de skills

Esse número é o seu ponto de partida real

E tem uma convenção de comunidade que combina bem com isso: modo plano, CLAUDE.md e uma pasta /specs commitada no repositório, pro spec ficar diffável no pull request

Deixo explícito: isso NÃO é padrão oficial da Anthropic, é prática de quem usa (inclusive já existe plugin de spec-driven development de terceiros, tipo o sdd, com agentes especializados e planos de implementação em fases)

A ideia por trás é a mesma do spec-driven development: a especificação versionada como fonte única da verdade, primeiro o spec, depois o plano, depois as tarefas, depois o código

Testa aí e me conta se o teu /context deu um susto…

até o próximo post! 😀