🏗️ Arquitetura de um projeto
Estruturar um projeto que dura: pastas, módulos, separação de responsabilidades, escolha de stack, documentação de decisões e estratégia de crescimento incremental.
1 📁 Estrutura de pastas que faz sentido
Estrutura canônica de pastas — cada diretório com responsabilidade única
A estrutura de pastas é o primeiro contrato do projeto. Ela diz ao Claude (e a qualquer colaborador) o que vai onde antes de ler uma linha de código.
my-project/
├── src/
│ ├── components/ # UI e lógica de apresentação
│ ├── lib/ # Utilitários puros
│ ├── types/ # TypeScript interfaces
│ └── data/ # Artefatos JSON gerados
├── scripts/
│ ├── aggregate.ts # Data pipeline
│ └── setup.ts # Setup único
├── docs/
│ ├── adr/ # Architecture Decision Records
│ └── CHANGELOG.md
├── tests/
├── CLAUDE.md # Instruções do agente
├── package.json
└── .env.example # Template de variáveis✓ Fazer
- • Cada pasta com responsabilidade única
- • Nomes em minúsculas sem espaço
- • README.md ou index.ts em cada pasta
- • scripts/ separado de src/
- • docs/ para decisões e changelog
✗ Evitar
- • Pasta
misc/oustuff/ - • Utils gigante com 50 arquivos
- • Misturar scripts de build com código
- • Arquivos na raiz sem propósito claro
- • Aninhamento maior que 4 níveis
Dica prática
Mostre a estrutura de pastas no CLAUDE.md com tree -L 2. O Claude entende o projeto sem precisar explorar arquivo por arquivo.
2 🔩 Separação de responsabilidades
Cada módulo deve ter uma razão para existir e uma razão para mudar. Quando isso não é respeitado, qualquer alteração propaga efeitos inesperados para todo o sistema.
Como a separação evolui num projeto real
Tudo em um arquivo
Normal no início. Um index.ts com fetch, lógica e renderização misturados. Funciona, mas escala mal.
Separação por camadas
Data fetching em lib/api.ts, tipos em types/, componentes React isolados. Cada parte testável.
Módulos com interfaces definidas
Cada módulo exporta uma interface pública. Implementação interna pode mudar sem quebrar outros módulos. Claude modifica um módulo por vez.
✓ Módulo bem separado
- • Uma responsabilidade clara
- • Interface pública mínima
- • Dependências explícitas (parâmetros)
- • Testável isoladamente
- • Pode ser substituído sem cascata
✗ Módulo acoplado
- • Lê variáveis globais diretamente
- • Faz I/O e lógica no mesmo lugar
- • Importa half the codebase
- • Precisa de banco real para testar
- • Mudar quebra 5 outras coisas
Regra prática
Se você precisar explicar mais de duas coisas que um módulo faz, ele provavelmente faz coisas demais. Peça ao Claude: "Identifique responsabilidades misturadas neste arquivo."
3 🧱 Escolha de stack
Stack é uma decisão de longo prazo. Trocar de runtime no meio de um projeto é custoso. Escolher bem no início economiza meses de trabalho.
Critérios para escolher stack em projetos com Claude Code
✅ Critérios técnicos
- • Performance adequada para o problema
- • Ecossistema de pacotes maduro
- • TypeScript nativo ou fácil de adicionar
- • Suporte a testes integrado
🤖 Critérios para Claude
- • Stack popular = Claude conhece bem
- • Docs públicas bem indexadas
- • Exemplos abundantes no treinamento
- • Erros com mensagens claras
# ADR-001: Escolha de runtime — Bun
## Status: Aceito (2026-05-01)
## Contexto
Projeto precisa de: TypeScript nativo, execução rápida
de scripts, bundler integrado, compatibilidade Node.js.
## Opções consideradas
- Node.js + tsx: familiar, mas startup lento
- Deno: boa DX, mas ecossistema menor
- Bun: startup 3x mais rápido, bundler nativo, TS out-of-box
## Decisão
Usar Bun como runtime principal.
## Consequências
+ Scripts de build ~200ms (vs ~600ms com Node)
+ Sem configuração adicional de TypeScript
- Alguns pacotes npm com compatibilidade parcial
- Equipe precisa instalar Bun (curl ... | bash)Stacks com melhor suporte do Claude em 2026
TypeScript/Node/Bun, React/Next.js, Python/FastAPI, Go stdlib. Frameworks nichados ou muito novos recebem suporte mais fraco — prefira o mainstream quando a escolha for indiferente.
4 📝 Documentar decisões com ADRs
Architecture Decision Records (ADRs) são documentos curtos que registram: por que uma decisão foi tomada, quais opções foram consideradas e quais são as consequências esperadas.
Contexto
Por que essa decisão precisou ser tomada? Qual era o problema ou a oportunidade?
Opções
Quais alternativas foram avaliadas? Por que cada uma foi aceita ou rejeitada?
Consequências
O que muda após a decisão? Benefícios positivos e negativos esperados.
Cuidado com ADRs desatualizados
Um ADR que não reflete mais a realidade é pior que nenhum ADR. O Claude vai seguir instruções obsoletas. Revise ADRs sempre que a decisão mudar — mesmo que seja para marcar "Superseded by ADR-007".
5 🌱 Começar pequeno e crescer
Projetos com Claude evoluem rápido. A armadilha é planejar uma arquitetura complexa antes de validar o núcleo. Walking skeleton primeiro — detalhes depois.
Ciclo de crescimento saudável
Semana 1 — Núcleo funcional
Um arquivo que faz a coisa mais importante. Sem abstração prematura. Valida a hipótese principal.
Semana 2-4 — Separação
Extrair módulos conforme padrões emergem. Adicionar testes para o núcleo validado.
Mês 2+ — Escala
Adicionar features sobre base sólida. Arquitetura estabelecida organicamente — não projetada no vácuo.
YAGNI com o Claude
"You Aren't Gonna Need It" é duplamente importante com LLMs. O Claude pode gerar abstrações elaboradas rapidamente — mas abstrações antes do tempo criam dívida técnica invisível. Peça sempre a solução mais simples primeiro.
6 🔭 Visão de longo prazo
Projetos sobrevivem quando têm rituais de manutenção, não apenas features. O que você faz semanalmente importa mais do que a arquitetura inicial.
✓ Rituais saudáveis
- • Review semanal de TODOs/FIXMEs
- • CHANGELOG atualizado a cada versão
- • Dependências atualizadas mensalmente
- • CLAUDE.md revisado trimestralmente
- • Métricas de cobertura monitoradas
✗ Sinais de projeto doente
- • CHANGELOG abandonado na V0.1
- • Dependências com 2 anos de atraso
- • CLAUDE.md nunca foi atualizado
- • TODO acumulando sem cleanup
- • Ninguém sabe por que X existe
📋 Resumo do módulo
- • Estrutura de pastas com responsabilidade única
- • Separação de responsabilidades por módulo
- • Critérios para escolha de stack
- • ADRs como memória de decisões
- • Crescimento incremental com YAGNI
- • Rituais de manutenção saudável
- • Crie a estrutura de pastas do seu projeto
- • Escreva o primeiro ADR de stack
- • Defina as responsabilidades de cada módulo
- • Configure o CLAUDE.md com o mapa de pastas