Sua IA Não Sabe Onde Fica a Pasta Models. E Isso Custa Caro.
Você abre o Claude Code, pede “crie uma nova página CRUD de Clientes” e ele coloca o Controller numa pasta aleatória, ignora seus namespaces, esquece o padrão MVC e cria um Model que não segue nenhuma das suas convenções. Resultado: você gasta mais tempo corrigindo a IA do que teria gasto codando sozinho.
O problema não é a IA. É que ninguém contou para ela como seu projeto funciona.
O vídeo “Cloud.md: A Arquitetura MVC e o Padrão do Projeto” do canal Software House Exponencial mostra exatamente isso: como o arquivo CLAUDE.md se torna a constituição arquitetural que todo agente de IA precisa respeitar — especialmente em projetos .NET com MVC.
O Que É o CLAUDE.md (E Por Que Ele Muda Tudo)
O CLAUDE.md é um arquivo markdown na raiz do seu projeto que o Claude Code lê automaticamente no início de cada sessão. Pense nele como o onboarding que você faria com um desenvolvedor novo, mas que nunca precisa ser repetido — a IA absorve toda vez que inicia.
Segundo a HumanLayer, um bom CLAUDE.md responde três perguntas fundamentais:
- WHAT (O quê): Stack, estrutura de pastas, tecnologias
- WHY (Por quê): Propósito do projeto, decisões arquiteturais
- HOW (Como): Comandos de build, test, lint, workflow de desenvolvimento
O resultado? A IA para de adivinhar e começa a seguir suas regras.
Arquitetura MVC No CLAUDE.md: O Mapa Que a IA Precisa
Para projetos .NET com MVC, o CLAUDE.md precisa ser cirúrgico. De acordo com o guia de codewithmukesh, a estrutura mínima deve incluir:
1. Estrutura de Pastas Com Propósito
# Estrutura do Projeto
src/
Api/ → Endpoints, middleware, DI configuration
Application/ → Commands, queries, handlers, validators
Domain/ → Entities, value objects, enums
Infrastructure/ → EF Core, external services
tests/ → Unit and integration testsCada pasta tem uma responsabilidade clara. A IA não precisa inferir — ela lê e segue.
2. Convenções de Namespace
Definir namespaces no CLAUDE.md elimina a adivinhação:
# Namespaces
- Controllers: MeuProjeto.Api.Controllers
- Models: MeuProjeto.Domain.Entities
- Services: MeuProjeto.Application.Services
- Repositories: MeuProjeto.Infrastructure.DataQuando a IA sabe que Controllers vivem em MeuProjeto.Api.Controllers, ela nunca mais vai criar um controller solto na raiz.
3. Padrões de Nomenclatura CRUD
O vídeo enfatiza como o arquivo define as diretrizes para novas páginas CRUD:
# Padrão CRUD
- Commands: Create[Entity]Command, Update[Entity]Command, Delete[Entity]Command
- Queries: Get[Entity]Query, List[Entities]Query
- Handlers: [Command/Query]Handler
- DTOs: [Entity]Dto, Create[Entity]Request, Update[Entity]Request
- Controllers: [Entity]Controller (herda de BaseApiController)Com esse padrão definido, toda nova entidade segue o mesmo blueprint — consistência garantida por design, não por revisão manual.
Os 5 Erros Que Software Houses Cometem Com o CLAUDE.md
Erro 1: Arquivo Gigante Com Tudo Dentro
A Anthropic recomenda menos de 300 linhas no arquivo raiz. A HumanLayer vai além: seu CLAUDE.md tem menos de 60 linhas. Use a sintaxe @path/to/file.md para importar detalhes de arquivos separados.
Erro 2: Colocar Regras de Linting no CLAUDE.md
“Nunca mande um LLM fazer trabalho de linter”, diz a HumanLayer. Regras de formatação devem ficar no .editorconfig ou no Biome — não no CLAUDE.md. É caro, lento e impreciso.
Erro 3: Não Incluir Comandos Exatos
Segundo as Best Practices oficiais da Anthropic, use comandos literais: dotnet build src/Api, dotnet test tests/Unit. A IA executa verbatim.
Erro 4: Esquecer o “WHY” (Por Quê)
Documentar decisões arquiteturais é tão importante quanto documentar a estrutura. “Usamos CQRS porque…” permite que a IA tome decisões alinhadas quando encontra cenários não previstos.
Erro 5: Gerar Automaticamente Com /init e Nunca Revisar
O comando /init gera um ponto de partida, mas CLAUDE.md é um documento vivo que precisa de curadoria manual. Cada linha afeta toda interação subsequente.
Na Prática: O Antes e Depois
Sem CLAUDE.md
- IA cria arquivos em locais aleatórios
- Namespaces inconsistentes entre features
- Padrões CRUD diferentes a cada geração
- Dev gasta 40% do tempo corrigindo output da IA
Com CLAUDE.md Bem Configurado
- Toda entidade segue o mesmo blueprint MVC
- Namespaces corretos desde a primeira geração
- Comandos de build/test executados corretamente
- Dev revisa output em vez de reescrever
A diferença não é incremental — é estrutural. É a diferença entre um estagiário que pergunta tudo e um dev sênior que leu a documentação antes de commitar.
Como Implementar Hoje
- Rode
/initno Claude Code para gerar o esqueleto - Adicione a estrutura MVC com caminhos de pastas e seus propósitos
- Defina namespaces explicitamente (a IA não adivinha bem)
- Documente padrões CRUD — nomes de Commands, Queries, DTOs
- Inclua comandos exatos de build, test e lint
- Mantenha abaixo de 300 linhas — use imports para detalhes
- Revise mensalmente — o projeto evolui, o CLAUDE.md também
Conclusão: 300 Linhas Que Valem Mais Que 3000 de Documentação
O CLAUDE.md não é um README. Não é documentação para humanos. É um contrato entre seu projeto e a IA. Quando esse contrato define arquitetura MVC, namespaces, convenções CRUD e comandos de build, a IA deixa de ser um assistente genérico e vira um membro do time que conhece seu código.
Como mostrou o vídeo do Software House Exponencial: o arquivo que define o projeto é o arquivo que define a qualidade do output. Invista 30 minutos configurando seu CLAUDE.md e economize horas toda semana.
