Projeto novo com Claude Code: o que decidir antes da primeira linha de código?

O Claude Code escreve rápido em cima do esqueleto que você entregar

Esqueleto indefinido vira retrabalho, e o retrabalho não aparece no primeiro prompt, aparece na terceira sessão, quando você percebe que cada arquivo saiu com um padrão diferente

Este post é sobre as decisões que continuam sendo suas em um projeto novo: linguagem, framework, estrutura de pastas, convenção de branch, limites de segurança, o que vai versionado e o que fica na sua máquina

E, principalmente, sobre COMO registrar essas decisões num lugar que o agente lê antes de escrever a primeira linha

O que você precisa ter em mãos antes de começar

Três coisas, e nenhuma delas é prompt:

• um repositório git já iniciado (o histórico é a sua rede de segurança, falo disso lá no passo 10)
• o Claude Code instalado e funcionando no terminal
• as decisões mínimas de produto já tomadas: linguagem, framework e gerenciador de pacotes

Repare que a escolha da stack é SUA, e continua sendo sua depois que o agente entra em cena

O trabalho daqui pra frente é pegar essa escolha e transformar em contexto que o agente lê toda sessão

O fluxo inicial recomendado na documentação é curtinho: iniciar com o comando claude, gerar o guia do projeto com /init e pedir ao Claude que faça commit do CLAUDE.md gerado no repositório

Bora abrir isso passo a passo?

Passo a passo: preparar o terreno antes da primeira linha de código

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

1. Rode claude e depois /init

O /init faz o Claude Code analisar o codebase e gerar um arquivo CLAUDE.md com os comandos de build, as instruções de teste e as convenções que ele descobre

cd meu-projeto
claude

Dentro da sessão:

/init

Existe também um fluxo interativo em várias fases, habilitado pela variável de ambiente CLAUDE_CODE_NEW_INIT=1, no qual o /init pergunta quais artefatos configurar (CLAUDE.md, skills e hooks) e explora o codebase com subagentes antes de apresentar as propostas

O erro comum deste passo: rodar o /init numa pasta vazia esperando convenções prontas

Ele analisa o repositório, então repositório sem nada dentro devolve pouco, e o trabalho de escrever a convenção volta pro seu colo (o que é bom, veja o passo 3)

Outro detalhe que evita susto: se já existir um CLAUDE.md, o /init sugere melhorias em vez de sobrescrever o arquivo

2. Decida o escopo do contexto: usuário ou projeto?

Os arquivos CLAUDE.md são lidos no início de cada sessão e vivem em escopos diferentes

• escopo de usuário: ~/.claude/CLAUDE.md
• escopo de projeto: CLAUDE.md ou .claude/CLAUDE.md

A ordem de carga vai do mais amplo pro mais específico: usuário primeiro, projeto depois

Na prática isso quer dizer que a instrução do projeto entra no contexto DEPOIS da sua instrução pessoal

O erro comum deste passo: jogar preferência sua (tema, jeito de responder, atalho pessoal) dentro do arquivo do projeto e versionar aquilo pro time inteiro engolir

Gosto pessoal vai pro escopo de usuário, regra do projeto vai pro escopo de projeto, e pronto

Se quiser conferir a mecânica completa, a documentação de memória do Claude Code é a referência

3. Escreva no CLAUDE.md o que é decisão SUA

Aqui é o coração do post

O conteúdo recomendado inclui comandos bash, estilo de código, etiqueta de repositório (nomenclatura de branch, preferência entre merge e rebase) e setup do ambiente de desenvolvimento, mantendo o arquivo conciso e legível por humanos, sem formato obrigatório

Dá pra declarar políticas de segurança que o Claude Code referencia, como exigir statements parametrizados em consultas ao banco, autenticação em endpoints de API e proibição de segredos hardcoded na configuração

E dá pra customizar o comportamento de compactação, com instrução pra preservar informação crítica como a lista completa de arquivos modificados e os comandos de teste

Um esqueleto de arquivo fica mais ou menos assim:

# API de pedidos

## Comandos
- instalar: npm ci
- rodar em dev: npm run dev
- testar: npm test
- lint: npm run lint

## Estilo de código
- TypeScript com tipos explícitos nas fronteiras de módulo
- nada de default export

## Etiqueta de repositório
- branch: feat/nome-curto, fix/nome-curto
- rebase na branch de trabalho, merge commit só na main

## Setup de ambiente
- Node na versão do .nvmrc
- variáveis em .env.local, nunca commitadas

## Segurança
- toda consulta ao banco usa statement parametrizado
- todo endpoint de API exige autenticação
- nenhum segredo hardcoded na configuração

## Compactação
- ao compactar, preserve a lista completa de arquivos modificados e os comandos de teste

O erro comum deste passo: escrever o arquivo como se fosse documentação institucional

O objetivo é ser conciso e legível por humano, não é encher linguiça pra parecer completo

4. Estrutura de pastas e CLAUDE.md hierárquico

Em codebases grandes e monorepos dá pra usar arquivos CLAUDE.md em níveis diferentes (raiz, pacotes, componentes), e o Claude sobe a árvore de diretórios pra descobrir esses arquivos

O detalhe que muda o seu planejamento: os arquivos acima do diretório de trabalho são carregados por inteiro no lançamento da sessão, e os que estão em subdiretórios carregam sob demanda, quando o Claude lê arquivos daquelas pastas

Ou seja: a regra específica de um pacote MORA no pacote, e só entra no contexto quando ele for mexer ali

O erro comum deste passo: quebrar o arquivo em imports @path achando que economiza contexto

Não economiza

Dividir o conteúdo em imports ajuda a organizar, mas os arquivos importados carregam no lançamento da sessão do mesmo jeito

5. Regra condicional por caminho, com frontmatter

Dá pra escopar regra por caminho usando frontmatter YAML com o campo paths

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

Todo handler novo valida a entrada antes de tocar no banco
Nenhum handler devolve stack trace na resposta

Essa regra condicional só vale quando o Claude trabalha com arquivos que casam com o padrão

O erro comum deste passo: esquecer o campo paths e achar que a regra está "escondida" até ser relevante

Regra sem o campo paths carrega incondicionalmente, sempre

6. Decida o que entra no repositório

Aqui é decisão de time, não de ferramenta

• .claude/settings.json: o que é versionado e compartilhado com o time
• .claude/settings.local.json: o que não entra no controle de versão
• ~/.claude/settings.json: escopo global, lido em toda sessão, independentemente do projeto aberto

Detalhe bom: o Claude Code adiciona o settings.local.json ao gitignore global quando salva uma configuração nesse arquivo

O erro comum deste passo: colocar permissão frouxa da SUA máquina no arquivo versionado e distribuir isso pro time inteiro sem querer

7. Permissões: entenda a ordem de avaliação antes de liberar geral

A ordem é esta: hook PreToolUse, regras de negação, regras de permissão, regras de pergunta, checagem do modo de permissão, callback canUseTool e hook PostToolUse

Duas consequências práticas que valem ouro num projeto novo:

• deny é avaliado antes de allow, e regra de negação bloqueia mesmo em bypassPermissions
• regras de allow pré-aprovam ferramentas pra SESSÃO INTEIRA, não só pro turno atual

Então a lista de negação é o seu guardrail de verdade

É ela que continua valendo no dia em que alguém do time decidir rodar tudo no modo mais solto

O erro comum deste passo: aprovar algo "só dessa vez" achando que a permissão morre no turno seguinte

8. Automatize a convenção com um hook, em vez de repetir no prompt

Um hook PostToolUse com matcher Write|Edit pode rodar lint ou formatação depois que o Claude escreve ou edita um arquivo, configurado na chave hooks do settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "npm run lint -- --fix" }
        ]
      }
    ]
  }
}

O Claude Code observa os arquivos de configuração e recarrega quando eles mudam, então edição na maioria das chaves vale na sessão em curso sem reiniciar, hooks incluídos

O erro comum deste passo: tratar PostToolUse como guarda de portão

Ele não desfaz nada, porque a ferramenta já executou

Se a intenção é BLOQUEAR, o lugar é antes, na camada de permissão

9. Opcional no começo: subagentes e skills

Subagentes de projeto ficam em .claude/agents/ e são específicos do projeto e compartilháveis com o time, enquanto os de usuário ficam em ~/.claude/agents/ e valem em todos os projetos

Cada subagente é um Markdown com frontmatter YAML, e a descoberta acontece subindo a partir do diretório de trabalho atual, varrendo todo .claude/agents/ entre ele e a raiz do repositório

Skills seguem a mesma lógica de escopo: ~/.claude/skills/ pra pessoal e .claude/skills/ pra projeto, cada uma sendo um diretório com um SKILL.md, onde o campo description determina quando o Claude aciona aquilo

Skills de projeto carregam do diretório onde a sessão começou e de cada diretório pai até a raiz do repositório, e mudança em skill é detectada dentro da sessão em curso, sem reiniciar

É justamente por causa desse escopo e desse description que uma skill copiada de outro projeto às vezes simplesmente não dispara na sua máquina

O erro comum deste passo: montar seis subagentes no dia 1, antes de existir código

Deixe pra criar quando a dor aparecer

10. Defina a política de trabalho: plan mode e ritmo de commit

O Shift+Tab alterna o modo de permissão da sessão, e dá pra pressionar até a barra de status mostrar o plan mode ativo

Planejar antes rende mais quando existe incerteza sobre a abordagem, quando a mudança altera vários arquivos ou quando o código a modificar não é familiar

Do outro lado da segurança está o git: pedir ao agente que faça commit do progresso com mensagens descritivas e escreva resumos do avanço é a melhor forma de obter bom comportamento, e commitar a cada unidade significativa de trabalho dá histórico recuperável e evita perda de trabalho

Se você ainda está decidindo quanto poder dar ao agente no Git, essa conversa merece acontecer ANTES da primeira feature

O erro comum deste passo: deixar o agente rodar três horas sem um único commit e depois tentar separar o que prestou do que não prestou

O que aprendi montando um projeto do zero com o Claude Code

O que mais me pegou gravando o tutorial: a primeira decisão não é o código, é ONDE a ferramenta vai rodar

Muita gente trava na linha de comando, e por isso eu costumo indicar a integração com o editor pra quem está começando

Depois vem a escolha da forma de login, que acontece antes de qualquer prompt, e eu fico na mais simples pra mim

Outra coisa que virou hábito: eu abro o terminal já DENTRO da pasta onde o projeto vai nascer

Parece bobo, mas escolher o diretório é passo anterior ao primeiro prompt, e a ferramenta ainda pede permissão explícita pra trabalhar naquela pasta, valendo tanto pra projeto novo quanto pra projeto que já existe

Já me ferrei com setup também: numa instalação no Windows o binário não ficou acessível no terminal por falta de permissão, e eu tive que ajustar a variável de ambiente na mão antes de conseguir usar

Tome cuidado com isso, porque nessa hora não é o modelo que está errando, é o ambiente 😅

No primeiro teste eu pedi uma calculadora de IMC com HTML, CSS e JavaScript, pedindo interface bonita, e a ferramenta montou os arquivos do zero na pasta vazia

Abri no navegador, conferi funcionando, e só então segui

E aqui está a parte que conversa com o post inteiro: aquele pedido funcionou de primeira porque era pequeno e o padrão não importava

Projeto de verdade não é assim

Quanto mais precisas as instruções, menos correções são necessárias: referenciar arquivos específicos, mencionar restrições e apontar padrões de exemplo reduz o retrabalho

É exatamente isso que o CLAUDE.md faz por você em toda sessão, sem você redigitar

Sobre autonomia, testei os modos e a diferença é gritante

No modo que pede confirmação antes de editar, o desenvolvimento fica pausado o tempo todo, com uma pergunta a cada ação

Nos modos mais soltos ele anda sozinho, e dá pra acompanhar o raciocínio ao longo das etapas pra entender como ele planejou cada funcionalidade

Não existe modo certo universal: cada pessoa precisa testar pra descobrir a qual se adapta melhor

Minha recomendação pra trabalho em equipe ou dentro de empresa é ficar nos modos mais pausados, sem romance

Ah, e a própria ferramenta avisa que pode errar antes de começar a trabalhar, o que já diz muito sobre revisar o que sai

No vídeo abaixo eu mostro esse fluxo inteiro na tela, do setup até o projeto rodando:

O que o agente resolve sozinho e o que continua sendo decisão sua

Com esqueleto pronto e convenção escrita, o agente vai muito bem

Sem isso, ele inventa um padrão por arquivo, e você vira revisor em tempo integral

Sobre a última linha da coluna da esquerda: git worktrees permitem checar múltiplos branches do mesmo repositório em diretórios separados, cada um com arquivos isolados e compartilhando o mesmo histórico

Isso viabiliza rodar várias sessões do Claude em partes diferentes do projeto ao mesmo tempo

Massa, né? Só que repare no pré requisito escondido: sessão paralela só não vira bagunça se a convenção já estiver escrita e valendo pros dois lados 😀

Conclusão

Meia hora decidindo e escrevendo o CLAUDE.md evita horas corrigindo padrão inventado depois

A ferramenta escreve o código, mas stack, estrutura, convenção de branch, limite de segurança e o que entra no repositório continuam sendo escolha sua, e ela só obedece o que estiver escrito

O próximo passo é bem concreto:

1. rode claude na pasta do projeto
2. dê /init pra gerar o CLAUDE.md a partir da análise do repositório
3. revise o arquivo gerado colocando as SUAS convenções (comandos, estilo, etiqueta de repositório, setup, segurança)
4. peça o commit do CLAUDE.md no repositório

Só depois disso você pede a primeira feature

Se quiser aprofundar nas recomendações da própria Anthropic, o material de boas práticas de engenharia com Claude Code é uma boa leitura de fim de semana

Até o próximo post!