Claude Code: Inicialização de Projeto e Estrutura

Última atualização: 2026-08-31

O Claude Code analisa automaticamente a estrutura do projeto ao entrar nele, mas você também pode guiá-lo ativamente através do CLAUDE.md.

💡 Dica: A inicialização do projeto não é apenas sobre o Claude Code ler arquivos — é sobre como ele entende "convenções implícitas" como estilo de código, normas de diretório e estratégias de teste. O CLAUDE.md é o portador explícito dessas convenções.

📋 Pré-requisitos: Capítulo 5 - Integração com VS Code e JetBrains

1. O Que Você Vai Aprender

Como o Claude Code entende a estrutura do projeto
Funcionalidades de inicialização para diferentes projetos de framework
Papel e geração automática do CLAUDE.md
Janela de contexto e tamanho do projeto
Estratégias de otimização para projetos grandes

2. Como o Claude Code Entende Projetos

(1) Fluxo de Análise Automática

graph TB
    A[Entrar no diretório do projeto] --> B[Ler CLAUDE.md]
    B --> C[Escanear estrutura de diretórios]
    C --> D[Identificar framework/linguagem]
    D --> E[Ler arquivos de config chave]
    E --> F[Construir contexto]

Passo	Arquivos Lidos	Propósito
CLAUDE.md	CLAUDE.md raiz	Obter convenções e instruções do projeto
Arquivos de config	package.json, pom.xml, go.mod, etc.	Identificar stack tecnológica e dependências
Estrutura de diretórios	src/, lib/, tests/, etc.	Entender organização do código
README	README.md	Obter visão geral do projeto

(2) Stacks Tecnológicas Reconhecidas

Arquivo de Config	Reconhecimento	Comportamento Automático
`package.json`	Projeto Node.js	Usar npm/yarn/pnpm
`pom.xml`	Java Maven	Usar comandos mvn
`go.mod`	Projeto Go	Usar comandos go
`requirements.txt`	Projeto Python	Usar pip/pytest

▶ Exemplo 1: Saída da Análise de Projeto

TEXT 📖 Somente leitura

$ claude

╭─ Claude Code ──────────────────────────────╮
│  Project Analysis:                          │
│  Type:      Node.js / TypeScript            │
│  Framework: Express.js                      │
│  Test:      Jest                            │
│  Package:   npm                             │
│  Structure:                                 │
│    src/                                     │
│      routes/      (12 route files)          │
│      models/      (8 model files)           │
│      middleware/   (4 files)                │
│      utils/        (6 utility files)        │
│    tests/                                   │
│    config/                                  │
│  Key deps: express, mongoose, jest          │
╰─────────────────────────────────────────────╯

3. Configuração de Projeto com CLAUDE.md

(1) Gerar CLAUDE.md Automaticamente

BASH

# Pedir ao Claude Code para analisar o projeto e gerar CLAUDE.md
claude /init

(2) Escrever CLAUDE.md Manualmente

MARKDOWN

# CLAUDE.md

## Project Overview
Sistema admin de e-commerce, usando Express + TypeScript + Prisma

## Tech Stack
- Runtime: Node.js 20
- Framework: Express 4.x
- ORM: Prisma 5.x
- Test: Vitest
- Lint: ESLint + Prettier

## Common Commands
- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Code Conventions
- Usar sintaxe ES Module
- Todas as respostas de API usam formato unificado { code, data, message }
- Tratamento de erros usa classe customizada AppError
- Arquivos de rota ficam em src/routes/
- Cada arquivo de rota corresponde a um arquivo de teste

## Don'ts
- Não usar var, apenas const/let
- Não usar mongoose diretamente, usar Prisma
- Não modificar prisma/schema.prisma a menos que explicitamente solicitado

▶ Exemplo 2: CLAUDE.md para Diferentes Projetos

MARKDOWN

<!-- Go project CLAUDE.md -->
# CLAUDE.md

## Project
RESTful API service, Go 1.22 + Gin + GORM

## Commands
- Run: `go run ./cmd/server`
- Test: `go test ./...`
- Build: `go build -o bin/server ./cmd/server`

## Conventions
- Usar layout padrão de projeto (cmd/, internal/, pkg/)
- Retornos de erro usam pacote pkg/errors
- Todos os handlers recebem gin.Context
- Operações de banco apenas na camada repository

4. Melhores Práticas de Estrutura de Projeto

(1) Estrutura Amigável ao Claude Code

Característica	Amigável	Não Amigável
Profundidade de diretório	3-4 níveis, nomenclatura clara	Aninhamento de 10+ níveis
Nomenclatura de arquivos	Convenções de nomenclatura consistentes	Nomenclatura arbitrária
Arquivos de config	Localizações padrão	Espalhados por toda parte
Localização de testes	Centralizados ou adjacentes	Sem testes
Documentação	README + CLAUDE.md	Sem documentação

5. Projetos Multi-Linguagem/Multi-Módulo

(1) Suporte a Monorepo

TEXT 📖 Somente leitura

my-monorepo/
├── CLAUDE.md           # Config global
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md   # Config do subprojeto frontend
│   ├── backend/
│   │   └── CLAUDE.md   # Config do subprojeto backend
│   └── shared/
│       └── CLAUDE.md   # Config da biblioteca compartilhada

(2) Configuração Independente por Subdiretório

BASH

# Iniciar Claude Code em diferentes subdiretórios lê o CLAUDE.md correspondente
cd packages/frontend && claude  # Lê frontend/CLAUDE.md
cd packages/backend && claude   # Lê backend/CLAUDE.md

6. Exemplo Completo: Inicialização Completa de Projeto

BASH

# Inicialização completa de projeto da Alice

# 1. Criar projeto
mkdir ecommerce-api && cd ecommerce-api
npm init -y

# 2. Inicializar git
git init

# 3. Lançar Claude Code para gerar esqueleto do projeto
claude "Initialize an Express + TypeScript project:
1. Configure tsconfig.json
2. Set up ESLint + Prettier
3. Create src/ directory structure (routes, controllers, models, middleware, utils)
4. Configure Jest testing
5. Create .gitignore
6. Generate CLAUDE.md"

# 4. Verificar CLAUDE.md gerado
cat CLAUDE.md

# 5. Ajustar CLAUDE.md conforme necessário

# 6. Commit do estado inicial
git add -A && git commit -m "feat: project initialization"

❓ Perguntas Frequentes

P: Qual a diferença entre CLAUDE.md e README.md? R: README é uma descrição do projeto para humanos; CLAUDE.md é instruções de trabalho para o Claude Code. CLAUDE.md foca mais em convenções de código, comandos comuns e restrições.

P: Projeto muito grande, o Claude Code não consegue ler tudo? R: O Claude Code seleciona inteligentemente arquivos chave, não carregando tudo. Você também pode especificar o escopo de trabalho no CLAUDE.md para reduzir consumo de contexto.

P: CLAUDE.md deve estar no diretório raiz obrigatoriamente? R: O CLAUDE.md raiz é config global. Subdiretórios também podem ter CLAUDE.md; o Claude Code os mescla.

P: Devo commitar o CLAUDE.md no git? R: Recomendado. Convenções de projeto compartilhadas pela equipe são mais valiosas que configs individuais. Não coloque informações sensíveis no CLAUDE.md.

P: O /init gerou um CLAUDE.md impreciso? R: Edite manualmente. /init é apenas assistência; a precisão do CLAUDE.md precisa de revisão e ajuste humano.

P: Cada pacote em um Monorepo precisa de CLAUDE.md? R: Necessariamente não. Se os pacotes são similares, um CLAUDE.md raiz basta. Se muito diferentes, configs separadas são recomendadas.

📖 Resumo

O Claude Code analisa automaticamente a estrutura do projeto e identifica stacks tecnológicas
CLAUDE.md é o portador explícito de convenções do projeto; /init pode gerá-lo automaticamente
Projetos amigáveis ao Claude Code: diretórios claros, nomenclatura consistente, configs padrão
Projetos grandes usam CLAUDE.md para limitar escopo de trabalho e reduzir consumo de Tokens
Monorepo suporta configuração de CLAUDE.md em múltiplos níveis

📝 Exercícios

Básico (⭐): Execute claude /init em um projeto existente, verifique se o CLAUDE.md gerado é preciso.
Intermediário (⭐⭐): Escreva manualmente um CLAUDE.md completo com convenções do projeto, comandos comuns e restrições.
Avançado (⭐⭐⭐): Desenhe configuração de CLAUDE.md em múltiplos níveis para um Monorepo, garantindo que cada subprojeto opere independentemente.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós