Um arquivo de instruções do projeto é lido no começo de toda sessão, então cada linha é paga em toda requisição enquanto o arquivo existir. Esse único fato decide o que cabe nele e o que não cabe. Tudo que se descobre lendo o código — a linguagem, o framework, a estrutura de pastas — está sendo repetido para um leitor que já enxerga. O que vale o espaço é o contrário: o comando de teste que precisa de uma flag, a versão do Node que quebra o build, a convenção que alguém novo adivinharia errado, aquilo que já custou uma tarde a alguém. Este criador se organiza em torno dessas categorias, estima o que o arquivo custa e aponta as linhas que estão contando ao repositório coisas sobre ele mesmo.
Recursos
Seções guiadas pelo que cabe nelas, não por uma página em branco
Estimativa de tokens contínua: o custo em toda requisição, não uma vez
Aponta linhas que repetem o que o código já mostra
Aponta exortações vazias que não mudam nada
Avisa quando o arquivo cresceu até o tamanho em que passa a ser lido por cima
Nota quando não há títulos por onde podar
Seções vazias são descartadas em vez de escritas em branco
Baixa como CLAUDE.md
Como usar Instruções do projeto
Nomeie o projeto
Preencha só as seções em que tiver algo não óbvio a dizer
Acompanhe a estimativa de tokens enquanto cresce
Leia os avisos e baixe o arquivo
Exemplo
Entrada
This project is a React app.
Saída
Warning: the language and framework are visible from the manifest
O teste para cada linha: um leitor descobriria isso em dez segundos?
Erros comuns e solução de problemas
O arquivo é apontado como grande demais. — Mova o que só é relevante de vez em quando para um documento separado que a sessão possa ler quando precisar. O arquivo de instruções é para o que é sempre verdade.
Uma linha que eu queria é apontada como descobrível. — Ignore o aviso se ela for realmente essencial. A checagem é um convite a perguntar se um leitor descobriria de qualquer jeito, não uma regra.
Nada muda quando acrescento instruções. — Instruções específicas e verificáveis pegam muito melhor do que gerais. “Use as primitivas de components/ui” supera “escreva código limpo”.
Isso deve se chamar CLAUDE.md ou outra coisa? — O conteúdo é o mesmo. Salve com o nome que a sua ferramenta lê; a estrutura e a disciplina sobre o que entra não mudam.
Perguntas frequentes
O que realmente cabe num arquivo de instruções?
O que não se descobre lendo o código e de outra forma seria adivinhado errado: o comando que precisa de uma flag, a versão que quebra o build, a convenção que não aparece em nenhum arquivo específico e as proibições explícitas. O resto está sendo repetido a um leitor que já sabe ler.
Que tamanho ele deve ter?
Pequeno o bastante para continuar sendo lido. A estimativa aparece enquanto você digita; passados alguns milhares de tokens vale perguntar quais linhas são sempre relevantes, porque o resto pode viver num documento lido sob demanda.
Por que ele aponta “escreva código limpo”?
Porque não muda nada. Uma exortação geral custa tokens em toda requisição e não dá base para decisão nenhuma; uma convenção específica — onde a lógica fica, quais primitivas usar — dá.
Importa que isso seja pago em toda requisição?
É justamente a razão de podar o arquivo. Uma página de instruções é um custo pequeno uma vez e considerável ao longo de milhares de requisições, e por isso a estimativa fica ao lado do texto em vez de escondida.
Posso colocar segredos ou credenciais?
Não: ele é lido para o contexto em toda sessão e normalmente vai versionado. Mantenha credenciais no ambiente e cite-as pelo nome se as instruções precisarem mencioná-las.
Ferramentas relacionadas
Construtor de skills — Escreva um SKILL.md com o frontmatter verificado enquanto você digita.
Construtor de subagentes — Monte o arquivo de definição de um subagente com ferramentas e modelo.
Construtor de comandos — Crie um comando próprio, com argumentos e uma lista de ferramentas.
Planejador de contexto — Divida a janela entre prompt, ferramentas, histórico e a resposta.
Planejador de cache — Ordene os blocos para que o prefixo cacheável seja o mais longo possível.
Linter de prompts — Encontre contradições, instruções mortas e marcadores não preenchidos.
Mais ferramentas de IA e agentes
Construtor de skills — Escreva um SKILL.md com o frontmatter verificado enquanto você digita.
Linter de skills — Cole um SKILL.md e veja o que impede que ele seja associado a uma tarefa.
Construtor de subagentes — Monte o arquivo de definição de um subagente com ferramentas e modelo.
Construtor de comandos — Crie um comando próprio, com argumentos e uma lista de ferramentas.
Manifesto de plugin — Gere um plugin.json e veja a estrutura de pastas que ele espera.
Construtor de hooks — Monte hooks do settings.json e pegue os matchers que nunca disparam.