Pular para o conteúdo principal

Convenções do CLAUDE.md

O arquivo CLAUDE.md é o arquivo de instruções que o Claude Code lê automaticamente ao iniciar uma sessão no seu projeto. Ele funciona como um manual de onboarding para a IA: indica qual stack você usa, como o código está organizado, quais convenções seguir e como se conectar a ferramentas externas como o Almirant.

Um CLAUDE.md bem configurado faz a diferença entre uma IA que gera código genérico e outra que respeita a arquitetura, os padrões e as convenções da sua equipe.

Onde colocar o arquivo​

Coloque CLAUDE.md na raiz do seu repositório:

tu-proyecto/
  CLAUDE.md          # <-- aqui
  .claude/
    skills/
    settings.json
  src/
  package.json

O Claude Code procura esse arquivo automaticamente ao abrir o projeto. Você não precisa de configuração adicional.

Nota

Se você trabalha com um monorepo, pode ter um CLAUDE.md na raiz e outros adicionais em subdiretórios. O Claude Code combina todos eles.

O que incluir ao usar o Almirant​

1. Configuração MCP​

O mais importante é que o Claude Code saiba como se conectar ao Almirant. Inclua a configuração do servidor MCP com a URL e a chave de API.

## MCP - Almirant

Este projeto está conectado ao Almirant para gestão de tarefas.

Configuração em `.claude/settings.json` ou `.mcp.json`:

\```json
{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "http://localhost:3001/mcp?projectId=<tu-project-uuid>",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}
\```

Use as ferramentas MCP para ler e atualizar work items, boards e sprints.
Dica

Faça referência à localização da configuração MCP, mas nunca inclua a chave de API diretamente em CLAUDE.md. Use .claude/settings.json (que deve estar em .gitignore) ou variáveis de ambiente.

2. Descrição do projeto​

Forneça contexto geral sobre o projeto e as tecnologias usadas.

## Descrição do projeto

Aplicação web de e-commerce B2B construída com:
- **Frontend**: Next.js 15 + React 19 + TypeScript + Tailwind CSS
- **Backend**: Bun + Elysia + Drizzle ORM
- **Banco de dados**: PostgreSQL 16
- **Auth**: Better-Auth com Google OAuth
- **Testes**: Vitest + Playwright

3. Estrutura do repositório​

Explique como o código está organizado para que a IA navegue com eficiência.

## Estrutura

\```
src/
  domains/           # Módulos por domínio (DDD)
    users/
      domain/        # Tipos e interfaces
      application/   # Hooks e casos de uso
      presentation/  # Componentes e containers
    orders/
    products/
  components/ui/     # Componentes compartilhados (shadcn/ui)
  lib/               # Utilitários, cliente de API, auth
\```

4. Convenções de código​

Defina as regras que o Claude Code deve seguir ao gerar código.

## Convenções

- **Arquivos**: kebab-case (`user-service.ts`, `order-form.tsx`)
- **Componentes**: PascalCase (`UserProfile`, `OrderList`)
- **Hooks**: camelCase com o prefixo `use` (`useUserProfile`, `useOrderList`)
- **Sem classes**: Usar programação funcional. Funções puras, custom hooks, objetos funcionais
- **Tipos**: Em `domain/types.ts`, não dentro de componentes .tsx
- **Componentes .tsx**: Apenas de apresentação. Sem useState, useEffect nem lógica de negócio
- **Lógica**: Em custom hooks dentro de `application/hooks/`

5. Comandos do projeto​

Inclua os comandos que o Claude Code pode precisar executar.

## Comandos

\```bash
bun run dev          # Servidor de desenvolvimento
bun run build        # Build de produção
bun run lint         # Linter
bun run test         # Testes
bun run type-check   # Verificação de tipos
bun run db:generate  # Gerar migração
bun run db:migrate   # Aplicar migrações
\```

6. Padrões de código​

Documente padrões específicos que você quer que a IA replique.

## Padrões

### Chamadas de API com React Query

Todas as chamadas de API usam React Query com query keys estruturadas:

\```typescript
export const userKeys = {
  all: ['users'] as const,
  list: (filters: UserFilters) => [...userKeys.all, 'list', filters] as const,
  detail: (id: string) => [...userKeys.all, 'detail', id] as const,
};

export const useUsers = (filters: UserFilters) => {
  return useQuery({
    queryKey: userKeys.list(filters),
    queryFn: () => usersApi.getAll(filters),
  });
};
\```

### Mutations com invalidação

\```typescript
export const useCreateUser = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: usersApi.create,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: userKeys.all });
    },
  });
};
\```

7. Regras específicas do projeto​

Inclua restrições ou regras de negócio que a IA deve respeitar.

## Regras

- **NUNCA** executar SQL diretamente. Usar Drizzle ORM + migrações
- **NUNCA** commitar arquivos .env ou credenciais
- **NUNCA** modificar arquivos em `migrations/meta/`
- Os work items NÃO têm uma coluna `status` -- o estado é derivado da coluna do board
- Os work items usam `archived_at` (timestamp) em vez de um booleano para arquivar
- A autenticação usa cookies `better-auth.session_token`

Exemplo completo​

# CLAUDE.md

## Projeto

E-commerce B2B para distribuição de produtos industriais.

**Stack**: Next.js 15 + React 19 + TypeScript + Tailwind CSS 4 + Elysia + Drizzle ORM + PostgreSQL 16

## MCP - Almirant

Gestão de tarefas via MCP. Configuração em `.mcp.json`.
Use ferramentas MCP para ler work items antes de implementar e
atualizar o estado ao terminar.

## Estrutura

\```
src/
  domains/           # Módulos DDD
    catalog/         # Produtos e categorias
    orders/          # Pedidos e faturamento
    customers/       # Clientes B2B
  components/ui/     # shadcn/ui
  lib/               # Cliente de API, auth, utils
\```

## Convenções

- Arquivos em kebab-case
- Componentes: apenas de apresentação (sem hooks em .tsx)
- Lógica: custom hooks em application/hooks/
- Tipos: em domain/types.ts
- Sem classes: apenas funções, hooks, interfaces

## Comandos

\```bash
bun run dev           # Servidor de desenvolvimento (porta 3000)
bun run build         # Build de produção
bun run lint          # ESLint
bun run test          # Vitest
bun run db:generate   # Gerar migração
bun run db:migrate    # Aplicar migrações
\```

## Padrões

### React Query

Query keys estruturadas por domínio.
Mutations invalidam queries relacionadas em onSuccess.

### Cliente de API

Módulos em lib/api/client.ts:
- catalogApi.getProducts(filters)
- ordersApi.create(data)
- customersApi.getById(id)

## Regras

- NUNCA SQL direto, sempre Drizzle + migrações
- NUNCA commitar .env
- Os pedidos exigem validação de estoque antes da confirmação
- Preços calculados server-side, nunca confiar no frontend

Dicas avançadas​

Segmentar por público​

Se sua equipe tiver perfis diferentes (frontend, backend, devops), você pode usar seções com cabeçalhos claros para que cada skill ou fluxo saiba onde buscar informações relevantes.

Manter atualizado​

Trate CLAUDE.md como documentação viva. Quando você alterar um padrão, uma convenção ou a estrutura do projeto, atualize o arquivo. Uma instrução desatualizada pode fazer a IA gerar código inconsistente.

Não duplicar o óbvio​

Não é necessário documentar como React ou TypeScript funcionam. Concentre-se no que é específico do seu projeto: convenções internas, padrões próprios e restrições de negócio.

Validar com a equipe​

Assim como as skills, o CLAUDE.md é versionado com Git. Revise-o no code review quando houver alterações significativas para garantir que toda a equipe esteja alinhada.

Segurança

Nunca inclua credenciais, chaves de API, tokens ou URLs de produção diretamente em CLAUDE.md. Esse arquivo é versionado com Git e fica visível para toda a equipe. Use variáveis de ambiente ou arquivos de configuração em .gitignore.