🎬 Pacote Inicial (Starter Pack)

CLAUDE.md e um arquivo Markdown que vive no seu repositorio e funciona como memoria persistente do projeto. Toda vez que voce inicia uma sessao do Claude Code, ele le esse arquivo primeiro, ganhando contexto instantaneo sobre o que e o projeto, como funciona e quais sao as regras.

Sem CLAUDE.md, voce precisa re-explicar seu projeto a cada sessao: qual framework usa, como rodar testes, quais convencoes seguir. Com ele, o Claude ja sabe tudo isso antes de voce digitar a primeira palavra.

Pense no CLAUDE.md como um documento de onboarding para seu parceiro de codigo IA. Assim como voce onboarda um dev novo na equipe, voce onboarda o Claude com informacoes sobre stack, estrutura e padroes.

O CLAUDE.md resolve o problema de amnesia entre sessoes. Modelos de IA nao tem memoria entre conversas - cada sessao comeca do zero. O CLAUDE.md injeta contexto critico automaticamente, eliminando esse gap.

A diferenca entre um dev que usa Claude sem CLAUDE.md e um que usa com e brutal. O primeiro gasta 10-15 minutos por sessao explicando contexto. O segundo comeca a produzir em 10 segundos.

O CLAUDE.md nao e documentacao generica do projeto. E um documento especificamente escrito para o Claude entender. Foco em informacoes que ele precisa para gerar codigo correto: convencoes, comandos, restricoes.

Ao iniciar uma sessao, o Claude Code automaticamente busca e le todos os arquivos CLAUDE.md relevantes: o do diretorio raiz do projeto, os de subdiretorios onde voce esta trabalhando, e o global do seu sistema.

Entender quando o arquivo e lido ajuda voce a escrever conteudo mais eficaz. O CLAUDE.md e injetado como instrucoes de sistema, ou seja, tem prioridade alta na atencao do Claude.

A leitura e automatica e silenciosa. Voce nao precisa pedir. O conteudo e tratado como instrucoes persistentes que sobrevivem ate mesmo a compactacao de contexto com /compact.

O CLAUDE.md nao e um README para humanos, nem documentacao de API. E um arquivo escrito especificamente para o Claude interpretar. O publico-alvo e a IA, nao desenvolvedores humanos.

Muitas pessoas cometem o erro de copiar o README.md para o CLAUDE.md. Isso gera um arquivo cheio de badges, links e informacoes irrelevantes para o Claude, desperdicando tokens preciosos.

README.md: apresentacao para humanos. CLAUDE.md: instrucoes para a IA. O CLAUDE.md deve ser conciso, diretivo e focado em informacoes que impactam a geracao de codigo: stack, convencoes, comandos, restricoes.

Quando voce roda /compact, o historico de chat e resumido. Mas as instrucoes do CLAUDE.md sao recarregadas integralmente, pois sao tratadas como instrucoes de sistema, nao como historico.

Isso significa que suas regras e convencoes nunca se perdem, mesmo em sessoes muito longas. E a garantia de consistencia: o Claude pode esquecer o que voce disse no chat, mas nunca esquece o CLAUDE.md.

Instrucoes criticas devem ir no CLAUDE.md, nao no chat. Se voce disser "nunca use any" no chat, isso pode ser perdido apos compactacao. Se estiver no CLAUDE.md, persiste para sempre.

Com um CLAUDE.md bem escrito, o Claude gera codigo que segue seus padroes automaticamente: imports corretos, naming conventions da equipe, patterns preferidos, e evita armadilhas conhecidas do projeto.

O retorno sobre investimento e absurdo: 15 minutos escrevendo um CLAUDE.md economizam horas de correcoes e re-explicacoes ao longo de semanas. E o maior multiplicador de produtividade do Claude Code.

Principais beneficios: codigo consistente desde a primeira geracao, menos reviews de estilo, onboarding instantaneo em cada sessao, regras que nunca sao esquecidas, e compartilhamento de contexto entre membros da equipe.

A primeira secao do CLAUDE.md. Em 2-3 linhas, diz o que o projeto faz e com o que foi construido. Exemplo: "SaaSify e uma plataforma B2B de gestao de assinaturas. Construido com Next.js 14, TypeScript e Supabase."

O Claude precisa de contexto de alto nivel para tomar decisoes arquiteturais corretas. Saber que e um SaaS B2B vs um app mobile muda completamente como ele aborda problemas de autenticacao, permissoes e estrutura.

Mantenha curto e objetivo. Nome do projeto, tipo (SaaS, API, CLI, etc.), e tecnologias principais. Nao escreva um paragrafo longo - o Claude precisa de fatos, nao narrativa.

Lista explicita de todas as tecnologias do projeto: linguagem, framework, banco de dados, ORM, CSS, testes e package manager. Cada item em uma linha com versoes quando relevante.

Sem essa secao, o Claude pode sugerir Express quando voce usa Fastify, ou npm quando voce usa pnpm. A stack define o vocabulario que o Claude deve usar no seu projeto.

Seja especifico: nao diga "React", diga "Next.js 14 com App Router". Nao diga "banco de dados", diga "PostgreSQL via Supabase". Quanto mais preciso, menos correcoes voce fara.

Lista dos comandos essenciais do projeto: dev server, build, testes, lint, type check, migracoes. Cada comando com sua sintaxe exata. Exemplo: "Dev: pnpm dev", "Test: pnpm test", "Lint: pnpm lint".

Esta e a secao mais util do CLAUDE.md. Quando o Claude precisa verificar se seu codigo funciona, ele usa esses comandos. Sem eles, ele pode tentar "npm test" quando voce usa "uv run pytest".

Inclua todos os comandos que voce usa no dia a dia. Dev server, build, testes unitarios, testes e2e, lint, format, type check, migracoes de banco. O Claude usa exatamente o que voce colocar aqui.

Regras de estilo e padroes do projeto: named exports vs default, file naming (kebab-case vs PascalCase), aspas simples vs duplas, uso de Server Components vs Client Components, validacao com Zod, etc.

Sem convencoes explicitas, o Claude usa seus padroes default que podem conflitar com os do seu projeto. Se voce prefere named exports e o Claude gera default exports, voce precisa corrigir toda vez.

Documente o que e unico no seu projeto. Nao diga "use TypeScript" (ele ja sabe). Diga "use Server Components por padrao, Client Components somente com 'use client' quando necessario". Foque no especifico.

Lista explicita de anti-patterns e proibicoes. Exemplos: "Nunca use any - use unknown e narrow", "Nao use Pages Router - apenas App Router", "Nunca commite .env files", "Nao instale dependencias sem discutir primeiro".

Prevenir erros e tao poderoso quanto guiar comportamento. Uma linha "nunca use any" no CLAUDE.md evita dezenas de correcoes ao longo do projeto. Restricoes claras geram codigo mais consistente.

Inclua erros que voce ja cometeu ou que o Claude ja fez no seu projeto. Se ele sempre sugere uma biblioteca que voce nao quer, adicione "Nao use X, prefira Y". Construa essa lista iterativamente.

Secao para informacoes que nao se encaixam nas anteriores: links para docs relevantes, quirks conhecidos, processo de deploy, variaveis de ambiente necessarias, dependencias externas.

Projetos reais tem nuances que nao cabem em categorias fixas. Um bug conhecido no ORM, uma API externa com rate limit, um processo de deploy que requer passos especificos. Esse contexto evita surpresas.

Use com moderacao. O CLAUDE.md e lido a cada sessao e consome tokens. Coloque apenas informacoes que o Claude realmente precisa para gerar codigo melhor. Se e informacao que so humanos consultam, deixe no README.

O CLAUDE.md na raiz (project-root/CLAUDE.md) e o arquivo principal. Aplica-se a todo o projeto, independentemente de qual diretorio voce esta trabalhando. E o que a maioria dos projetos precisa.

Este e o ponto de partida. 90% dos projetos so precisam desse unico arquivo. Ele define stack, convencoes e comandos que valem para todo o codebase.

Coloque na mesma pasta do package.json, pyproject.toml ou Cargo.toml. O Claude detecta automaticamente. Inclua informacoes globais do projeto: stack, comandos, convencoes universais.

Um CLAUDE.md dentro de um subdiretorio (ex: src/CLAUDE.md ou tests/CLAUDE.md) se aplica somente quando o Claude esta trabalhando naquele diretorio. Permite regras especificas por area do projeto.

Monorepos e projetos grandes tem areas com regras diferentes. O diretorio de testes pode ter convencoes diferentes do codigo de producao. Subdiretorios permitem essa granularidade.

Exemplo: src/components/CLAUDE.md com "Todos os componentes devem usar forwardRef e ser exportados com displayName". So se aplica quando o Claude trabalha em src/components/. O CLAUDE.md da raiz continua valendo tambem.

O arquivo em ~/.claude/CLAUDE.md se aplica a TODOS os projetos no seu sistema. E sua configuracao pessoal global: preferencias de idioma, estilo de comunicacao, padroes que voce usa em todo lugar.

Se voce sempre prefere respostas em portugues, ou sempre usa Conventional Commits, ou sempre quer type hints em Python, coloque no global em vez de repetir em cada projeto.

Ideal para: idioma preferido, estilo de commit, preferencias de editor, padroes pessoais. Nao coloque informacoes de projeto especifico aqui. O global e para o que vale em qualquer repositorio.

O Claude le todos os CLAUDE.md relevantes e combina suas instrucoes. A ordem e: global primeiro, depois raiz do projeto, depois subdiretorios. Instrucoes mais especificas complementam (nao substituem) as mais gerais.

Entender a precedencia evita conflitos. Se o global diz "use aspas duplas" e o projeto diz "use aspas simples", o Claude segue o mais especifico (projeto). Saber disso evita confusao quando regras parecem ser ignoradas.

Todos os arquivos sao lidos e combinados. Nao ha "substituicao" - e acumulativo. Se houver conflito, o mais especifico tende a prevalecer. Mantenha os escopos complementares, nao conflitantes.

Em projetos grandes ou monorepos, voce pode ter uma estrategia com multiplos CLAUDE.md: raiz com convencoes globais, packages/ com regras por pacote, tests/ com padroes de teste especificos.

Projetos que crescem precisam de regras granulares. O frontend pode ter convencoes de CSS diferentes das regras de API do backend. Multiplos arquivos permitem essa separacao sem poluir o CLAUDE.md raiz.

Estrategia recomendada: CLAUDE.md raiz com stack e comandos gerais. Subdiretorios so quando as regras realmente diferem. Nao crie CLAUDE.md em todo diretorio - cada arquivo consome tokens. Use com intencao.

Regra pratica: Global para preferencias pessoais universais. Raiz para tudo especifico do projeto. Subdiretorio somente quando uma area tem regras que conflitam ou complementam significativamente as da raiz.

Muita gente erra por exagero (CLAUDE.md em todo diretorio) ou por falta (nenhum CLAUDE.md). O equilibrio certo e ter cobertura sem desperdicio de tokens e sem confusao de regras.

Comece so com o da raiz. Adicione global quando perceber que repete instrucoes entre projetos. Adicione subdiretorios quando uma area consistentemente precisa de instrucoes diferentes. Evolua organicamente.

Exemplo real: "SaaSify e uma plataforma B2B de gestao de assinaturas. Construido com Next.js 14 (App Router), TypeScript e Supabase." Duas linhas que dao ao Claude todo o contexto de alto nivel.

Ao saber que e um SaaS B2B, o Claude automaticamente pensa em multi-tenancy, permissoes por empresa, planos de assinatura e billing. Esse contexto muda completamente as sugestoes de arquitetura.

Inclua o tipo de negocio (B2B, B2C, marketplace), a proposta principal e a stack core. Nao detalhe features - o Claude descobre isso lendo o codigo. Foque no que ele nao consegue inferir sozinho.

Stack detalhada: "TypeScript (strict mode), Next.js 14 com App Router, Supabase (PostgreSQL), Tailwind CSS + shadcn/ui, Vitest + Playwright, pnpm". Cada tecnologia com versao e variante.

"strict mode" muda como o Claude trata tipos. "App Router" vs "Pages Router" muda toda a estrutura de arquivos. "shadcn/ui" diz que componentes ja existem prontos. Cada detalhe importa.

Especifique o package manager (pnpm, nao npm). Especifique o test runner (Vitest, nao Jest). Especifique o CSS approach (Tailwind + shadcn, nao styled-components). O Claude adapta todo codigo gerado a essas escolhas.

Comandos reais: "Dev: pnpm dev", "Build: pnpm build", "Test: pnpm test", "E2E: pnpm test:e2e", "Lint: pnpm lint". Exatamente como voce digita no terminal.

O Claude usa esses comandos para verificar se o codigo que ele gerou funciona. Se voce diz "pnpm test" e ele tenta "npm test", o comando falha e ele perde tempo debugando um falso problema.

Inclua comandos de teste unitario E e2e separados. Inclua lint E format separados. Se tem type check separado (npx tsc --noEmit), inclua tambem. Cada comando que voce usa no dia a dia deve estar listado.

Convencoes reais: "Server Components por padrao, Client Components so quando necessario", "Named exports para todos os componentes", "kebab-case para arquivos, PascalCase para componentes", "Zod para validacao".

Essas convencoes eliminam 90% das correcoes de estilo. Sem elas, voce vai constantemente dizer "nao, use named export" ou "nao, esse componente deve ser Server Component". O CLAUDE.md automatiza essa correcao.

"Colocate testes junto ao codigo como *.test.ts" e uma regra que muda onde o Claude cria arquivos de teste. "Zod para input validation" faz ele usar Zod em vez de validacao manual. Cada regra tem impacto direto.

Restricoes do projeto: "Nunca use any - use unknown e narrow", "Nao use Pages Router - apenas App Router", "Nunca commite .env", "Nao instale dependencias sem discutir primeiro".

"Nao instale dependencias sem discutir primeiro" e poderoso porque o Claude tende a sugerir npm install para resolver problemas. Essa regra forca ele a usar o que ja existe antes de adicionar pacotes novos.

Construa essa lista iterativamente. Cada vez que o Claude faz algo que voce nao quer, adicione ao CLAUDE.md. Com o tempo, essa secao vira seu escudo contra erros recorrentes.

Apos criar o CLAUDE.md, teste-o pedindo ao Claude para gerar codigo e verifique se ele segue as convencoes. Peca um componente e veja se usa named export, Server Component por padrao e Zod.

Um CLAUDE.md que nao e testado pode ter instrucoes ambiguas ou faltantes. O teste revela gaps: "ele usou default export, preciso ser mais claro na secao de convencoes".

Teste com 3-4 pedidos diferentes: criar componente, escrever teste, criar rota de API, refatorar codigo. Se em todos os casos ele segue as convencoes, seu CLAUDE.md esta funcionando. Ajuste iterativamente.

Exemplo: "FastAPI backend para um dashboard de analytics em tempo real." Uma linha que define o dominio (analytics), a natureza (real-time) e o framework (FastAPI). O Claude ja sabe que vai lidar com WebSockets, filas e performance.

O contexto de dominio muda as decisoes do Claude. "Analytics em tempo real" implica queries otimizadas, caching agressivo e endpoints async. Um "blog simples" teria abordagem completamente diferente.

Para backends, mencione se e REST, GraphQL ou gRPC. Mencione se tem processamento async, filas ou workers. O Claude adapta patterns de acordo: async handlers, background tasks, connection pooling.

Stack detalhada: "Python 3.12, FastAPI, PostgreSQL com SQLAlchemy, uv como package manager." Especificar uv (nao pip) e fundamental porque muda todos os comandos de instalacao e execucao.

O Claude por padrao sugere pip e venv. Se voce usa uv, ele precisa saber para gerar "uv run pytest" em vez de "python -m pytest". A diferenca entre uv e pip muda como dependencias sao gerenciadas.

Especifique a versao do Python (3.12 tem features diferentes de 3.9). Especifique o ORM (SQLAlchemy vs Tortoise vs SQLModel). Especifique o package manager (uv vs pip vs poetry). Cada escolha impacta o codigo gerado.

Comandos com uv: "Dev: uv run uvicorn app.main:app --reload", "Test: uv run pytest", "Lint: uv run ruff check .", "Format: uv run ruff format .", "Migrate: uv run alembic upgrade head".

O padrao "uv run" antes de cada comando e o que faz o Claude executar tudo no ambiente virtual correto. Sem isso, ele pode tentar rodar pytest diretamente e falhar por falta de dependencias.

Note que lint e format sao separados (ruff check vs ruff format). Note que migracoes usam Alembic. Cada detalhe que voce especifica e um erro a menos que o Claude vai cometer.

Convencoes: "Type hints em todas as funcoes", "Pydantic models para request/response", "Dependency injection para database sessions", "Async handlers para todos os endpoints".

"Async handlers para todos os endpoints" forca o Claude a usar async def em vez de def. "Pydantic models para request/response" forca validacao automatica em vez de dicts soltos. Cada regra torna o codigo mais robusto.

Convencoes Python sao diferentes de JavaScript. Foque em: type hints (obrigatorios vs opcionais), async vs sync, ORM patterns (Unit of Work, Repository), validacao (Pydantic vs manual), e testes (fixtures, factories).

Restricoes Python: "Nunca use raw SQL - use SQLAlchemy ORM", "Nao use chamadas sync de DB em handlers async", "Nunca exponha IDs internos - use UUIDs". Anti-patterns que destroem performance e seguranca.

"Nao use chamadas sync de DB em handlers async" e critico: uma query sync bloqueia o event loop inteiro do FastAPI, derrubando performance. O Claude precisa saber disso para nao gerar codigo que funciona mas escala mal.

Anti-patterns Python comuns: raw SQL com string formatting (SQL injection), sync DB em async (blocking), expor IDs sequenciais (enumeration attack), importar models circulares. Cada um pode virar um incidente de producao.

Comparacao das duas abordagens: Next.js foca em Server/Client Components e UI patterns. FastAPI foca em async handlers, dependency injection e ORM patterns. O CLAUDE.md reflete essas diferencas fundamentais.

Comparar ajuda voce a abstrair o principio: o CLAUDE.md nao e um template fixo. E um documento que se adapta a sua stack. As secoes sao as mesmas, mas o conteudo muda radicalmente entre frontend e backend.

O principio e universal: diga ao Claude o que voce usa (stack), como voce usa (convencoes), como verificar (comandos) e o que evitar (restricoes). O conteudo especifico muda, mas a estrutura e a mesma.

O /init e um slash command que faz o Claude explorar seu repositorio (estrutura de pastas, package.json/pyproject.toml, configs) e gerar automaticamente um CLAUDE.md com overview, stack, comandos e convencoes detectadas.

E o atalho para quem nao quer escrever um CLAUDE.md do zero. Em vez de gastar 15 minutos digitando, voce roda /init e tem uma base solida em 30 segundos que so precisa de ajustes.

O Claude le package.json, tsconfig.json, pyproject.toml, Cargo.toml e outros configs. Detecta linguagem, framework, dependencias, scripts de build e test. Gera um CLAUDE.md estruturado com essas informacoes.

O /init e ideal para: projetos novos que ainda nao tem CLAUDE.md, projetos existentes onde voce quer um ponto de partida rapido, e quando voce esta entrando num repo desconhecido e quer que o Claude mapeie a estrutura.

Saber quando usar evita desperdicios. Rodar /init num projeto que ja tem um CLAUDE.md maduro pode sobrescrever regras refinadas. Use no momento certo: inicio do projeto ou primeiro contato com um repo.

Momentos ideais: setup inicial do projeto, clonando um repo open source pela primeira vez, migrando de outro editor/IA para Claude Code. Nao use para atualizar um CLAUDE.md existente - edite manualmente.

O /init gera um CLAUDE.md com as secoes padrao: Project Overview (baseado no repo), Tech Stack (detectada dos configs), Commands (extraidos de scripts no package.json), Code Conventions (inferidas do codigo existente).

Saber o que ele gera ajuda voce a avaliar a qualidade do output. Se o /init detectou "npm" mas voce usa "pnpm", voce sabe exatamente o que corrigir. Se faltou a secao de "Things To Avoid", voce sabe que precisa adicionar.

O output tipico cobre: nome e descricao do projeto, linguagem e framework, scripts de build/test/lint, estrutura de diretorios, e convencoes detectadas no codigo. A qualidade depende de quao bem estruturado e o repo.

Apos rodar /init, voce deve sempre revisar e customizar o CLAUDE.md gerado. Adicione convencoes que o Claude nao detectou, corrija informacoes erradas, e adicione a secao "Things To Avoid" que normalmente nao e gerada automaticamente.

O /init gera um bom ponto de partida, mas nunca um CLAUDE.md perfeito. As regras mais valiosas sao as que voce adiciona manualmente: preferencias de estilo, anti-patterns, e decisoes arquiteturais que nao estao no codigo.

Checklist pos-/init: verificar stack esta correta, adicionar "Things To Avoid", ajustar comandos (especialmente package manager), adicionar convencoes de naming e estilo, remover informacoes redundantes que consomem tokens.

O /init nao detecta: convencoes implicitas da equipe, decisoes arquiteturais nao documentadas, preferencias pessoais de estilo, anti-patterns especificos do projeto, e regras de negocio que impactam o codigo.

Confiar cegamente no /init cria um CLAUDE.md incompleto. As informacoes mais valiosas sao justamente as que ele nao consegue inferir: "nunca use any", "preferimos composition over inheritance", "deploy e feito via Vercel CLI".

Limitacoes praticas: pode confundir o package manager, nao detecta convencoes de naming consistentemente, nao cria secao "Things To Avoid", pode incluir informacoes redundantes, e a qualidade varia conforme a estrutura do repo.

O fluxo recomendado: rode /init para ter a base, revise e corrija a stack/comandos, adicione suas convencoes manualmente, crie a secao "Things To Avoid", teste com pedidos reais e itere. O melhor dos dois mundos.

Esse fluxo combina velocidade (automacao do /init) com qualidade (refinamento manual). Voce nao perde 15 minutos escrevendo do zero nem fica com um CLAUDE.md generico. Em 5 minutos voce tem um arquivo robusto.

Pipeline: /init > revisar stack > corrigir comandos > adicionar convencoes > adicionar restricoes > testar com 3 pedidos > ajustar conforme resultados. Repita o ciclo "testar e ajustar" nas primeiras sessoes ate o CLAUDE.md estar maduro.