Claude Code : Estrutura do projeto

Neste artigo veremos como definir a estrutura do projeto no Claude Code usando os principais recursos do Claude.

Ao trabalhar com o Claude Code, organizar bem os projetos faz toda a diferença. O Claude funciona melhor quando possui um contexto claro, uma estrutura consistente e instruções explícitas.

A seguir veremos 7 princípios essenciais que você deve seguir para criar uma excelente estrutura de projeto.

1- Entenda a hierarquia completa de memória

Antes de criar qualquer arquivo, é fundamental compreender que o Claude Code não possui um único CLAUDE.md — ele lê uma hierarquia de quatro níveis, e todos se combinam (não se substituem).

Dica:
Os arquivos do diretório raiz e acima são carregados na inicialização. Arquivos em subdiretórios são carregados sob demanda quando o Claude acessa arquivos naqueles diretórios. O CLAUDE.local.md é ideal para configurações pessoais como URLs de sandbox ou preferências individuais que não devem afetar o restante da equipe.

O arquivo de projeto: ./CLAUDE.md ou ./.claude/CLAUDE.md

O arquivo de projeto é o núcleo. Pode ser colocado na raiz do repositório (./CLAUDE.md) ou dentro da pasta .claude/ (./.claude/CLAUDE.md). A segunda opção é preferível em projetos grandes para manter a raiz limpa.

Aqui está um exemplo completo para um projeto .NET com Clean Architecture:

# CLAUDE.md — Contexto do Projeto

# Visão Geral
API de gestão de pedidos. Clean Architecture com CQRS.

# Arquitetura
Para arquitetura detalhada, consulte @docs/architecture.md
Para convenções de código, consulte @.claude/rules/coding.md
Para padrões de testes, consulte @.claude/rules/testing.md

# Stack
- .NET 10 / C# 14
- ASP.NET Core (Minimal APIs)
- Entity Framework Core 10 com PostgreSQL
- CQRS com MediatR
- Redis para cache
- Scalar para documentação OpenAPI
- xUnit mais FluentAssertions

# Comandos Essenciais
- Build: `dotnet build`
- Testes: `dotnet test`
- API: `dotnet run --project src/Api`
- Migração: `dotnet ef migrations add <Nome> -p src/Infrastructure -s src/Api`
- Atualizar BD: `dotnet ef database update -p src/Infrastructure -s src/Api`
- Formatar: `dotnet format`

# Regras Inegociáveis
- Domínio SEM dependências externas
- Construtores primários para DI
- Records para DTOs e Commands
- Namespaces com escopo de arquivo
- Sempre passar CancellationToken em métodos assíncronos
- Toda validação via FluentValidation (nunca inline)

Comando rápido
Se você já possui um codebase, não comece do zero. Execute /init no Claude Code para gerar automaticamente um rascunho do CLAUDE.md baseado no seu projeto existen

Nota: O arquivo CLAUDE.md também pode existir em subdiretórioes e é carregado sob demanda.

2. Divida instruções grandes com @imports e .claude/rules/

O CLAUDE.md pode crescer rapidamente. Como ele é carregado no contexto a cada sessão, arquivos grandes degradam a aderência às instruções. Arquivos com mais de 200 linhas devem ser divididos.

O Claude Code oferece duas formas complementares de organizar instruções detalhadas:

Opção A — Importações com @path

Referencie arquivos externos diretamente no CLAUDE.md:

# CLAUDE.md

# Arquitetura
Para arquitetura detalhada: @docs/architecture.md

# Regras de Código
Convenções C# e padrões: @.claude/rules/coding.md
Padrões de testes: @.claude/rules/testing.md
Diretrizes de API: @.claude/rules/api-design.md

Opção B — Pasta .claude/rules/ (caminho por escopo)

A pasta .claude/rules/ é o mecanismo oficial para instruções escopadas(que só valem) por arquivo ou diretório — por exemplo, regras específicas para src/Domain/ que não se aplicam à camada de infraestrutura:

.claude/
  rules/
    domain-rules.md        # aplica a src/Domain/**
    api-conventions.md     # aplica a src/Api/**
    test-patterns.md       # aplica a tests/**
    coding.md              # regras globais de C# 

3.Use Slash Commands(/) para fluxos de trabalho repetíveis

A abordagem de criar uma pasta genérica /workflows funciona, mas existe um mecanismo oficial e mais poderoso: Slash Commands customizados e Skills , armazenados em .claude/commands/ e .claude/skills/. Esses recursos se integram nativamente à interface do Claude Code e ficam disponíveis com /.

Crie arquivos Markdown em .claude/commands/ para empacotar fluxos de trabalho da equipe. O nome do arquivo vira o comando:

.claude/
  commands/
    new-endpoint.md        # invocado como /new-endpoint
    add-migration.md       # invocado como /add-migration
    review-pr.md           # invocado como /review-pr
    run-tests.md           # invocado como /run-tests 

Exemplo: .claude/commands/new-endpoint.md

---
description: Cria um endpoint CRUD completo com Clean Architecture
allowed-tools: Read, Write, Bash
---

Quando solicitado a criar um novo endpoint para $ARGUMENTS:

1. Crie a Entidade em `src/Domain/Entities/`
2. Crie Command/Query em `src/Application/` com MediatR
3. Implemente o Handler com CancellationToken
4. Adicione FluentValidation para o Command
5. Registre o Endpoint em `src/Api/Endpoints/`
6. Escreva testes unitários seguindo @.claude/rules/testing.md
7. Crie a migration: `dotnet ef migrations add Add{Entidade}` 

Use o comando diretamente no terminal:

# No Claude Code:
/new-endpoint Produto
/add-migration AddTabelaProdutos

Skills avançadas

A pasta .claude/skills/ funciona como uma evolução dos commands, suportando frontmatter YAML com metadados como allowed-tools, model, e description para o Claude decidir automaticamente quando invocar o skill, sem que você precise chamar explicitamente.

4. Configure Hooks para automação pós-edição

Os Hooks permitem executar comandos shell automaticamente antes ou depois de qualquer ação do Claude Code — por exemplo, rodar dotnet format após cada edição de arquivo .cs, ou executar testes antes de um commit.

Configure hooks no arquivo .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "dotnet format --include $FILE"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "dotnet test --no-build"
          }
        ]
      }
    ]
  }
}

5 - Configure o settings.json corretamente

O settings.json é o mecanismo oficial para configurar permissões, ferramentas, variáveis de ambiente e hooks no Claude Code. Complementa o CLAUDE.md com configurações estruturadas.

O Claude Code usa a seguinte hierarquia de configuração (prioridade do maior para o menor):

1 - Políticas corporativas gerenciadas (managed-settings.json ) — não podem ser sobrescritas
2 - Argumentos de linha de comando — overrides temporários
3 - Configurações locais do projeto (.claude/settings.local.json) — pessoais, não versionadas
4 - Configurações do projeto (.claude/settings.json ) — compartilhadas no Git
5 - Configurações globais do usuário (~/.claude/settings.json)

// .claude/settings.json — versionado no Git
{
  "permissions": {
    "allow": [
      "Bash(dotnet*)",
      "Bash(git*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

6- Aproveite o Auto Memory

O Auto Memory permite que o Claude acumule conhecimento entre sessões automaticamente, sem que você precise escrever nada. Requer Claude Code v2.1.59 ou posterior.

O Claude Code possui dois sistemas de memória complementares, carregados no início de cada conversa:

O Auto Memory é ativado por padrão. Para gerenciá-lo, use /memory dentro de uma sessão do Claude Code para visualizar, editar ou deletar o que foi salvo — tudo em arquivos Markdown simples que você pode inspecionar a qualquer momento.

⚠Atenção
O Auto Memory tem um índice limitado a 200 linhas (MEMORY.md). Arquivos de memória muito grandes consomem contexto e podem reduzir a aderência às instruções. Use /memory periodicamente para revisar e limpar memórias obsoletas.

7. Organize a pasta /docs e /tools

A lógica de ter uma pasta /docs para contexto adicional e uma pasta /tools para utilitários permanece válida. Refine apenas a estrutura da pasta /tools: em vez de instruir o Claude a gerar scripts arbitrariamente, defina explicitamente no CLAUDE.md ou nos commands quais artefatos devem ser gerados nessa pasta.

docs/
  architecture.md        # C4 ou ADR (Architecture Decision Records)
  api.md                 # contratos de API, exemplos de uso
  domain-glossary.md     # glossário do domínio de negócio

tools/
  MigrateDb/             # Console App para migrações de BD
  SeedData/              # scripts de seed para desenvolvimento
  ExportData/   

ADRs no /docs

As Architecture Decision Records (ADRs) são especialmente úteis na pasta /docs. Documente por que escolheu MediatR, por que PostgreSQL, por que Clean Architecture. Quando o Claude entender os motivos das suas decisões, vai respeitar as restrições arquiteturais muito mais consistentemente.

Estrutura recomendada do repositório

Conclusão

Adotar uma estrutura completa com a hierarquia de memória, .claude/commands/, settings.json, Hooks e Auto Memory transforma o Claude Code de um simples assistente em um membro sênior da sua equipe. Em vez de repetir instruções a cada nova sessão, você constrói uma memória institucional persistente e compartilhada para o projeto.

Ao manter essas definições atualizadas, você garante que a IA respeite sua arquitetura, que o código seja consistente com os padrões do time e que tarefas complexas — como criar um endpoint completo ou migrar o banco de dados — sejam executadas com precisão a partir de um único comando. Com isso:

A IA respeita sua arquitetura: Chega de sugerir lógica de banco de dados dentro da camada de Domínio.

O código se mantém consistente: O uso de Primary Constructors, C# 13+ e padrões de testes AAA torna-se o padrão automático, não a exceção.

A produtividade escala: Com fluxos de trabalho prontos, tarefas complexas como criar um novo endpoint ou migrar o banco de dados passam a ser executadas com precisão cirúrgica em segundos.

Agora é com você. Crie sua pasta claude/, rode um /init e comece a moldar o comportamento da IA para que ela escreva código exatamente como você faria. Um bom desenvolvimento!

E estamos conversados...  

'Porque éreis como ovelhas desgarradas; mas agora tendes voltado ao Pastor e Bispo das vossas almas.'
1 Pedro 2:25