Guía de Configuración del Archivo CLAUDE.md

# Nombre del Proyecto

## Descripción del Proyecto

[Breve descripción del propósito del proyecto, funciones principales y usuarios objetivo]

## Stack Tecnológico

- Frontend: [Framework y bibliotecas principales]
- Backend: [Lenguaje y framework]
- Base de datos: [Tipo de base de datos]
- Despliegue: [Plataforma de despliegue]

## Estructura del Proyecto

\```
project/
├── src/ # Código fuente
├── tests/ # Archivos de prueba
├── docs/ # Documentación
└── scripts/ # Archivos de script
\```

## Estándares de Desarrollo

[Estándares de codificación específicos del proyecto]

## Notas

[Notas y restricciones específicas del proyecto]

# CLAUDE.md - Archivo de Configuración del Proyecto

## Reglas Generales (obligatorias para todos los proyectos)

### Idioma de Comunicación

- Siempre usar chino simplificado para pensar y dialogar
- Comentarios de código en inglés, documentación en chino

### Gestión de Documentos

- Documentación oficial en el directorio `docs/`
- Propuestas de discusión en el directorio `discuss/`
- Mantener README conciso, documentación detallada separada

## Estándares de Arquitectura de Código

### Límites de Tamaño de Archivo

- Python/JavaScript/TypeScript: cada archivo no más de 300 líneas
- Java/Go/Rust: cada archivo no más de 400 líneas
- No más de 8 archivos por carpeta
- Si se excede, se requiere refactorización o división

### Indicadores de Calidad de Código

Evitar los siguientes code smells:

1. **Rigidez**: Sistema difícil de cambiar
2. **Redundancia**: Demasiado código duplicado
3. **Dependencias Circulares**: Módulos interdependientes
4. **Fragilidad**: Cambios causan problemas en cadena
5. **Obscuridad**: Intención del código no clara
6. **Data Clumps**: Elementos de datos siempre aparecen juntos
7. **Sobrediseño**: Complejidad innecesaria

## Restricciones de Stack Tecnológico

### Stack Tecnológico Frontend

- React 19+ (no usar versión 18 o inferior)
- Next.js 15.4+ (no usar versión 14 o inferior)
- Tailwind CSS v4 (no usar v3)
- Preferir TypeScript, evitar JavaScript
- Prohibir CommonJS, usar solo ES Modules

### Stack Tecnológico Backend

- Node.js 18+
- Usar TypeScript
- Express/Fastify como framework web
- Prisma como ORM

### Proyectos Python

- Usar uv para gestión de dependencias (no pip/poetry/conda)
- Nombre de directorio de entorno virtual: `.venv`
- Tipado fuerte, evitar uso de dict
- Mantener directorio raíz del proyecto limpio

## Flujo de Trabajo de Desarrollo

### Gestión de Scripts

- Todos los scripts en el directorio `scripts/`
- Usar scripts `.sh` para operaciones de inicio-parada
- No usar comandos npm/pnpm/python directamente
- Los fallos de script deben corregirse inmediatamente

### Gestión de Logs

- Archivos de configuración generan logs
- Salida unificada al directorio `logs/`
- Incluir marca de tiempo y nivel de log
- Almacenar logs de error por separado

### Requisitos de Pruebas

- Cobertura de pruebas unitarias > 80%
- Funciones críticas deben tener pruebas de integración
- Archivos de prueba en el directorio `tests/`
- Usar CI/CD para ejecutar pruebas automáticamente

## Convenciones de Nomenclatura

### Nombres de Archivo

- Componentes: PascalCase (ej. UserProfile.tsx)
- Funciones utilitarias: camelCase (ej. formatDate.ts)
- Archivos de constantes: UPPER_SNAKE_CASE (ej. API_CONSTANTS.ts)
- Archivos de estilo: kebab-case (ej. user-profile.css)

### Nombres de Variables

- Variables/Funciones: camelCase
- Constantes: UPPER_SNAKE_CASE
- Clases/Interfaces: PascalCase
- Propiedades privadas: \_camelCase

## Flujo de Trabajo Git

### Estrategia de Branching

- main: Código de producción
- develop: Código de desarrollo
- feature/\*: Ramas de características
- hotfix/\*: Ramas de corrección de emergencia

### Convenciones de Commit

- feat: Nueva funcionalidad
- fix: Corrección de errores
- docs: Actualización de documentación
- style: Formato de código
- refactor: Refactorización de código
- test: Relacionado con pruebas
- chore: Cambios de build/herramientas

## Estándares de Diseño de API

### Principios RESTful

- GET: Obtener recurso
- POST: Crear recurso
- PUT: Actualizar recurso (completo)
- PATCH: Actualizar recurso (parcial)
- DELETE: Eliminar recurso

### Formato de Respuesta

\```json
{
"success": true,
"data": {},
"message": "Operación exitosa",
"timestamp": "2024-01-01T00:00:00Z"
}
\```

### Manejo de Errores

\```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Descripción del error",
"details": {}
}
}
\```

## Estándares de Seguridad

### Información Sensible

- No codificar claves en el código
- Usar variables de entorno para gestión de configuración
- No hacer commit del archivo `.env` en Git
- Actualizar dependencias regularmente

### Validación de Datos

- Validación de datos tanto en frontend como backend
- Usar bibliotecas de validación de esquemas (ej. zod)
- Parametrizar consultas SQL
- Prevenir ataques XSS y CSRF

## Optimización de Rendimiento

### Optimización Frontend

- Lazy loading para imágenes
- Code splitting
- Estrategia de caché
- Scroll virtual (listas grandes)

### Optimización Backend

- Optimización de consultas de base de datos
- Usar caché (Redis)
- Compresión de respuestas API
- Control de concurrencia

## Configuración de Despliegue

### Variables de Entorno

- development: Entorno de desarrollo
- staging: Entorno de pruebas
- production: Entorno de producción

### Containerización

- Usar Docker para despliegue
- Builds multi-etapa para optimizar tamaño de imagen
- Usar docker-compose para orquestación de servicios

## Monitoreo y Logs

### Métricas de Monitoreo

- Tiempo de respuesta de API
- Tasa de error
- Uso de recursos
- Análisis de comportamiento del usuario

### Niveles de Log

- ERROR: Información de error
- WARN: Información de advertencia
- INFO: Información general
- DEBUG: Información de depuración

## Notas Especiales

⚠️ **Recordatorios Importantes**:

1. Abordar problemas de código inmediatamente
2. Preguntar activamente al usuario cuando haya incertidumbre
3. Mantener código limpio y mantenible
4. Seguir estándares establecidos del proyecto

## Estándares de Proyecto React/Next.js

### Estándares de Componentes

- Usar componentes funcionales + Hooks
- Archivo de componente con mismo nombre que componente
- Un archivo, un componente
- Props definidas con interfaces TypeScript

### Gestión de Estado

- Estado simple: useState
- Estado complejo: useReducer
- Estado global: Context API / Zustand
- Estado del servidor: TanStack Query

### Solución de Estilos

- Tailwind CSS v4 como principal
- CSS Modules como complemento
- Evitar estilos inline
- Priorizar diseño responsive

### Optimización de Rendimiento

- Usar React.memo para evitar renderizado innecesario
- useMemo/useCallback para optimización de cálculos
- Importaciones dinámicas para code splitting
- Usar componente next/image para imágenes

## Estándares de Proyecto Python

### Estructura del Proyecto

\```
project/
├── src/
│ ├── **init**.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ └── utils/
├── tests/
├── .venv/
└── pyproject.toml
\```

### Gestión de Dependencias

- Usar uv para todas las dependencias
- pyproject.toml para definir configuración del proyecto
- requirements.txt para despliegue de producción
- requirements-dev.txt para dependencias de desarrollo

### Anotaciones de Tipo

- Todas las funciones deben tener anotaciones de tipo
- Usar dataclass para definir estructuras de datos
- Combinar con mypy para verificación de tipos
- Evitar usar tipo Any

### Programación Asíncrona

- Priorizar async/await
- Usar asyncio para gestión de concurrencia
- Usar drivers asíncronos para operaciones de base de datos
- Usar httpx para peticiones HTTP

## Estándares de Arquitectura de Microservicios

### División de Servicios

- Dividir servicios por dominio de negocio
- Cada servicio se despliega independientemente
- Comunicación entre servicios vía API
- Código compartido mediante gestión de paquetes

### API Gateway

- Gestión de entrada unificada
- Autenticación y autorización
- Rate limiting y circuit breaking
- Enrutamiento de peticiones

### Comunicación de Servicios

- HTTP/REST: Llamadas síncronas
- Colas de mensajes: Comunicación asíncrona
- gRPC: Escenarios de alto rendimiento
- WebSocket: Comunicación en tiempo real

### Gestión de Datos

- Cada servicio tiene su propia base de datos
- Evitar transacciones entre servicios
- Usar event-driven para mantener consistencia
- Implementar operaciones idempotentes

> /init