Inicializando um Novo Projeto com /init
/init é um comando de barra do Claude Code que escaneia um repositório novo (ou existente) e cria um CLAUDE.md inicial para você, para que você não precise escrever a memória do projeto a partir de uma página em branco.
Resumo
Todo novo projeto eventualmente precisa de um CLAUDE.md descrevendo suas convenções, estrutura e regras.
Escrever um do zero significa re-derivar coisas que o Claude Code já pode ver por si só, como a linguagem, o layout das pastas e a configuração de testes.
/init preenche essa lacuna fazendo com que o Claude Code olhe para o projeto primeiro e produza um rascunho, que você então lê e corrige.
É o caminho mais rápido de "sem memória de projeto" para "um CLAUDE.md funcional", mesmo que o resultado ainda precise de uma passagem humana.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
cd my-project
claude
# once inside the Claude Code session:
/initQuando usar isso:
- Iniciando um projeto totalmente novo e querendo ter a memória do projeto em vigor desde o primeiro dia.
- Herdando um repositório existente que ainda não tem um CLAUDE.md.
- As convenções do projeto mudaram o suficiente para que valha a pena regenerar e revisar o CLAUDE.md existente.
- Você quer uma primeira passagem rápida para documentar a estrutura antes de refiná-la manualmente.
Exemplo de Trabalho
Aqui está uma sessão completa, de um CLAUDE.md vazio a um revisado, em um pequeno projeto de API Node.js.
# 1. Start Claude Code inside the project root
cd order-service
claude
# 2. Run /init inside the session
/init
# Claude Code scans package.json, the folder structure, existing
# README content, test setup, and any config files, then writes
# a first-pass CLAUDE.md to the project root.
# 3. Review what it produced
cat CLAUDE.mdUm rascunho inicial típico do /init se parece com isto:
# Project: order-service
## Overview
A Node.js REST API for managing customer orders.
## Tech Stack
- Node.js, Express
- PostgreSQL via `pg`
- Jest for testing
## Structure
- `src/routes/` - Express route handlers
- `src/services/` - business logic
- `src/db/` - database access
- `__tests__/` - Jest test files
## Commands
- `npm test` - run the test suite
- `npm run dev` - start the dev server# 4. Edit the draft to add anything /init couldn't infer,
# like team-specific rules and hard constraints.## Hard Rules
- Never query the database directly from a route handler - go through `src/services/`.
- Always add a test in `__tests__/` for any new route.
- Do not commit directly to `main`.# 5. Commit the finished file
git add CLAUDE.md
git commit -m "Add CLAUDE.md via /init"O que isso demonstra:
/initproduz um rascunho estrutural inicial (pilha, pastas, comandos) a partir do que pode observar no repositório.- Regras específicas da equipe e restrições rígidas raramente são inferíveis apenas pelo código - você ainda as adiciona manualmente.
- O arquivo gerado destina-se a ser revisado e commitado como qualquer outro arquivo de projeto, não aceito cegamente.
- Executar
/inité rápido o suficiente para refazer sempre que a forma do projeto mudou significativamente.
Mergulho Profundo
Como Funciona
/initlê os arquivos do projeto (manuais de pacotes, estrutura de pastas, documentação existente, configurações) para inferir a pilha tecnológica e o layout.- Ele escreve o resultado em
CLAUDE.mdna raiz do projeto, em markdown simples. - Se um
CLAUDE.mdjá existir, executar/initnovamente o atualiza com base no estado atual do projeto em vez de criar um arquivo duplicado. - O comando não executa testes, não instala nada nem modifica código - ele apenas produz documentação.
- O que ele escreve ainda é carregado exatamente como um
CLAUDE.mdescrito manualmente no início de cada sessão futura.
O Que /init Captura Confiável vs O Que Não Captura
| Categoria | Capturado confiavelmente por /init | Geralmente precisa de uma passagem humana |
|---|---|---|
| Pilha tecnológica | Sim - inferido de manifestos/configurações | - |
| Estrutura de pastas | Sim - inferido da árvore de arquivos | - |
| Scripts/comandos existentes | Sim - de package.json ou similar | - |
| Convenções da equipe não visíveis no código | Não | Sim - adicionar manualmente |
| Regras rígidas ("nunca faça X") | Não | Sim - adicionar manualmente |
| Contexto de negócios / termos de domínio | Parcial, se documentado no README | Frequentemente precisa ser adicionado |
Reexecutando /init em um Projeto Existente
# CLAUDE.md already exists and is a bit stale
/init
# Claude Code re-scans the project and updates CLAUDE.md
# to reflect the current structure, rather than starting overArmadilhas
- Aceitar o rascunho sem lê-lo.
/initinfere o que pode ver, mas não pode conhecer convenções da equipe não escritas. Correção: sempre leia o arquivo gerado de ponta a ponta antes de fazer o commit dele. - Perder regras escritas manualmente em uma reexecução. Reexecutar
/initatualiza o arquivo com base no estado atual do projeto, o que pode se misturar com edições manuais anteriores se você não estiver prestando atenção. Correção: compare o arquivo após reexecutar/inite confirme que suas regras rígidas ainda estão lá. - Tratar o rascunho como exaustivo.
/initdocumenta o que existe, não o que nunca deve acontecer. Correção: adicione uma seção explícita de "Regras Rígidas" manualmente para qualquer coisa não negociável. - Executar /init no diretório errado. Se executado fora da raiz real do projeto, o escaneamento produz uma imagem imprecisa ou vazia do projeto. Correção: confirme que você está na raiz do projeto (
pwd, verifique o arquivo de manifesto do projeto) antes de executá-lo. - Deixar o rascunho ficar desatualizado. Um CLAUDE.md gerado uma vez no início do projeto pode divergir à medida que a base de código evolui. Correção: reexecute
/initperiodicamente, ou atualize o arquivo manualmente quando a estrutura mudar significativamente.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Escrever CLAUDE.md manualmente do zero | O projeto é pequeno e você já sabe exatamente o que documentar | Você quer um rascunho inicial rápido de fatos estruturais já visíveis no repositório |
/init e depois refinamento manual | Iniciando um novo projeto ou herdando um não documentado | O projeto já tem um CLAUDE.md completo e preciso |
| Copiar um modelo CLAUDE.md de um projeto semelhante | Você mantém vários projetos estruturalmente semelhantes | Cada projeto tem estrutura ou convenções significativamente diferentes |
FAQs
O que exatamente o /init faz?
Ele escaneia o projeto atual (pilha tecnológica, estrutura de pastas, documentação existente, arquivos de configuração) e escreve um CLAUDE.md de primeira passagem documentando o que encontra.
Preciso de um projeto vazio para executar /init?
Não. Ele funciona em um repositório novo ou em um existente. Em um projeto que já possui um CLAUDE.md, executá-lo novamente atualiza o arquivo com base no estado atual do projeto.
O /init substituirá minhas regras escritas manualmente?
Ele pode se misturar com edições manuais ao ser reexecutado, pois reescreve com base no estado atual do projeto. Sempre compare o arquivo após uma reexecução para confirmar que tudo o que você adicionou manualmente ainda está presente.
O /init executa testes ou instala dependências?
Não. Ele apenas inspeciona o projeto e escreve a documentação em CLAUDE.md - ele não executa etapas de compilação, instala pacotes ou modifica código.
O arquivo que o /init gera está pronto para commit como está?
Trate-o como um rascunho inicial. Ele captura confiavelmente fatos estruturais como pilha e layout de pastas, mas convenções de equipe e regras rígidas geralmente precisam ser adicionadas manualmente antes de ser genuinamente útil.
Onde o /init escreve o arquivo?
Em CLAUDE.md na raiz do projeto atual.
Posso executar /init em uma subpasta para obter um CLAUDE.md aninhado?
/init destina-se à raiz do projeto. Arquivos CLAUDE.md aninhados para pastas específicas são tipicamente escritos manualmente para as regras específicas desse escopo.
Com que frequência devo reexecutar /init?
Sempre que a estrutura do projeto mudou o suficiente para que o CLAUDE.md existente pareça desatualizado - não há um cronograma fixo, é uma decisão baseada em quanto a estrutura divergiu.
O que acontece se eu executar /init no diretório errado?
O escaneamento reflete qualquer projeto (ou falta dele) que esteja realmente naquele diretório, o que produz um rascunho impreciso ou quase vazio. Confirme que você está na raiz do projeto pretendido primeiro.
O /init sabe sobre as convenções específicas da minha equipe?
Apenas o que é visível no próprio repositório (padrões de código, documentação existente). Convenções de equipe não escritas e regras rígidas precisam ser adicionadas manualmente após a geração do rascunho.
O /init é obrigatório antes que o Claude Code possa trabalhar no meu projeto?
Não. O Claude Code funciona sem um CLAUDE.md - ele apenas inicia cada sessão com menos contexto permanente sobre suas convenções. /init é uma conveniência para colocar esse contexto em vigor rapidamente.
Qual é a maneira mais rápida de verificar se o rascunho do /init é bom?
Leia-o de cima a baixo e pergunte se ele reflete com precisão onde as coisas estão localizadas e como o projeto realmente funciona hoje, em seguida, adicione qualquer coisa que ele não pôde inferir, como regras rígidas.
Relacionados
- O Que CLAUDE.md Realmente Faz - o conceito que
/initestá inicializando. - Noções Básicas de Gerenciamento de Contexto - onde
/initse encaixa entre as ferramentas principais da seção. - Escrevendo um Arquivo CLAUDE.md Que Realmente é Seguido - refinando o rascunho que
/initproduz. - Arquivos CLAUDE.md Aninhados e Como Funciona a Herança de Escopo - adicionando regras com escopo além do que
/initgera na raiz.
Versões da Pilha: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos de produtos mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.