Saltar al contenido principal

Convenciones CLAUDE.md

El archivo CLAUDE.md es el fichero de instrucciones que Claude Code lee automaticamente al iniciar una sesion en tu proyecto. Funciona como un manual de onboarding para la IA: le indica que stack usas, como esta organizado el codigo, que convenciones seguir y como conectarse a herramientas externas como Almirant.

Un CLAUDE.md bien configurado marca la diferencia entre una IA que genera codigo generico y una que respeta la arquitectura, patrones y convenciones de tu equipo.

Donde colocar el archivo​

Coloca CLAUDE.md en la raiz de tu repositorio:

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

Claude Code busca este archivo automaticamente al abrir el proyecto. No necesitas configuracion adicional.

Nota

Si trabajas con un monorepo, puedes tener un CLAUDE.md en la raiz y otros adicionales en subdirectorios. Claude Code los combina todos.

Que incluir cuando usas Almirant​

1. Configuracion MCP​

Lo mas importante es que Claude Code sepa como conectarse a Almirant. Incluye la configuracion del servidor MCP con la URL y la API key.

## MCP - Almirant

Este proyecto esta conectado a Almirant para gestion de tareas.

Configuracion en `.claude/settings.json` o `.mcp.json`:

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

Usa las herramientas MCP para leer y actualizar work items, boards y sprints.
Consejo

Referencia la ubicacion de la configuracion MCP, pero nunca incluyas la API key directamente en CLAUDE.md. Usa .claude/settings.json (que debe estar en .gitignore) o variables de entorno.

2. Descripcion del proyecto​

Da contexto general sobre que es el proyecto y que tecnologias usa.

## Descripcion del proyecto

Aplicacion web de e-commerce B2B construida con:
- **Frontend**: Next.js 15 + React 19 + TypeScript + Tailwind CSS
- **Backend**: Bun + Elysia + Drizzle ORM
- **Base de datos**: PostgreSQL 16
- **Auth**: Better-Auth con Google OAuth
- **Testing**: Vitest + Playwright

3. Estructura del repositorio​

Explica como esta organizado el codigo para que la IA navegue eficientemente.

## Estructura

\```
src/
  domains/           # Modulos por dominio (DDD)
    users/
      domain/        # Tipos e interfaces
      application/   # Hooks y casos de uso
      presentation/  # Componentes y containers
    orders/
    products/
  components/ui/     # Componentes compartidos (shadcn/ui)
  lib/               # Utilidades, API client, auth
\```

4. Convenciones de codigo​

Define las reglas que Claude Code debe seguir al generar codigo.

## Convenciones

- **Archivos**: kebab-case (`user-service.ts`, `order-form.tsx`)
- **Componentes**: PascalCase (`UserProfile`, `OrderList`)
- **Hooks**: camelCase con prefijo `use` (`useUserProfile`, `useOrderList`)
- **No clases**: Usar functional programming. Funciones puras, custom hooks, objetos funcionales
- **Tipos**: En `domain/types.ts`, no dentro de componentes .tsx
- **Componentes .tsx**: Solo presentacionales. Sin useState, useEffect ni logica de negocio
- **Logica**: En custom hooks dentro de `application/hooks/`

5. Comandos del proyecto​

Incluye los comandos que Claude Code puede necesitar ejecutar.

## Comandos

\```bash
bun run dev          # Servidor de desarrollo
bun run build        # Build de produccion
bun run lint         # Linter
bun run test         # Tests
bun run type-check   # Verificacion de tipos
bun run db:generate  # Generar migracion
bun run db:migrate   # Aplicar migraciones
\```

6. Patrones de codigo​

Documenta patrones especificos que quieres que la IA replique.

## Patrones

### API calls con React Query

Todas las llamadas a API usan React Query con query keys estructuradas:

\```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 con invalidacion

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

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

7. Reglas especificas del proyecto​

Incluye restricciones o reglas de negocio que la IA debe respetar.

## Reglas

- **NUNCA** ejecutar SQL directamente. Usar Drizzle ORM + migraciones
- **NUNCA** commitear archivos .env o credenciales
- **NUNCA** modificar archivos en `migrations/meta/`
- Los work items NO tienen columna `status` -- el estado se deriva de la columna del board
- Los work items usan `archived_at` (timestamp) en lugar de booleano para archivar
- La autenticacion usa cookies `better-auth.session_token`

Ejemplo completo​

# CLAUDE.md

## Proyecto

E-commerce B2B para distribucion de productos industriales.

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

## MCP - Almirant

Gestion de tareas via MCP. Configuracion en `.mcp.json`.
Usar herramientas MCP para leer work items antes de implementar y
actualizar estado al terminar.

## Estructura

\```
src/
  domains/           # Modulos DDD
    catalog/         # Productos y categorias
    orders/          # Pedidos y facturacion
    customers/       # Clientes B2B
  components/ui/     # shadcn/ui
  lib/               # API client, auth, utils
\```

## Convenciones

- Archivos en kebab-case
- Componentes: solo presentacionales (sin hooks en .tsx)
- Logica: custom hooks en application/hooks/
- Tipos: en domain/types.ts
- No clases: solo funciones, hooks, interfaces

## Comandos

\```bash
bun run dev           # Dev server (port 3000)
bun run build         # Production build
bun run lint          # ESLint
bun run test          # Vitest
bun run db:generate   # Generar migracion
bun run db:migrate    # Aplicar migraciones
\```

## Patrones

### React Query

Query keys estructuradas por dominio.
Mutations invalidan queries relacionadas en onSuccess.

### API Client

Modulos en lib/api/client.ts:
- catalogApi.getProducts(filters)
- ordersApi.create(data)
- customersApi.getById(id)

## Reglas

- NUNCA SQL directo, siempre Drizzle + migraciones
- NUNCA commitear .env
- Los pedidos requieren validacion de stock antes de confirmar
- Precios calculados server-side, nunca confiar en el frontend

Consejos avanzados​

Segmentar por audiencia​

Si en tu equipo trabajan perfiles diferentes (frontend, backend, devops), puedes usar secciones con encabezados claros para que cada skill o flujo sepa donde buscar informacion relevante.

Mantener actualizado​

Trata CLAUDE.md como documentacion viva. Cuando cambies un patron, una convencion o la estructura del proyecto, actualiza el archivo. Una instruccion desactualizada puede hacer que la IA genere codigo inconsistente.

No duplicar lo obvio​

No hace falta documentar como funciona React o TypeScript. Enfocate en lo especifico de tu proyecto: convenciones internas, patrones propios, restricciones de negocio.

Validar con el equipo​

Al igual que las skills, el CLAUDE.md se versiona con Git. Revisalo en code review cuando haya cambios significativos para asegurar que todo el equipo esta alineado.

Seguridad

Nunca incluyas credenciales, API keys, tokens o URLs de produccion directamente en CLAUDE.md. Este archivo se versiona con Git y es visible para todo el equipo. Usa variables de entorno o archivos de configuracion en .gitignore.