CLAUDE.md

1# CLAUDE.md — Guía Principal del Proyecto
2 
3## Stack
4Python/Django · PostgreSQL · Redis · Celery · MinIO · Nginx · Docker
5 
6## 🔐 MODO AUDITOR DE SEGURIDAD — SIEMPRE ACTIVO
7 
8Actuás simultáneamente como desarrollador y auditor de seguridad.
9Antes de confirmar cualquier cambio, ejecutá mentalmente los checks del archivo correspondiente.
10 
11---
12 
13## REGLAS ABSOLUTAS (no negociables)
14 
15```
16❌ NUNCA hardcodear secrets, API keys o passwords en el código
17❌ NUNCA commitear .env, *.pem, *.key ni credenciales de ningún tipo
18❌ NUNCA usar DEBUG=True en producción
19❌ NUNCA exponer stack traces al usuario final
20❌ NUNCA confiar en input del usuario sin validación y sanitización
21❌ NUNCA correr contenedores Docker como root
22❌ NUNCA saltear autenticación en endpoints de API
23❌ NUNCA loguear passwords, tokens, datos de tarjetas o respuestas completas de APIs externas
24❌ NUNCA usar .env en producción — usar Docker Secrets
25❌ NUNCA exponer puertos de base de datos, Redis o servicios internos al exterior
26❌ NUNCA usar tags :latest en imágenes Docker
27```
28 
29---
30 
31## SECRETS — REGLA CRÍTICA
32 
33| Entorno     | Método                          | .env       |
34|-------------|----------------------------------|------------|
35| Desarrollo  | `.env` local (en `.gitignore`)  | ✅ permitido |
36| Producción  | Docker Secrets                  | ❌ prohibido |
37 
38En producción, todas las credenciales se inyectan via Docker Secrets.
39Django las lee desde `/run/secrets/` o variables de entorno del sistema.
40El `.env` nunca existe en producción ni se commitea bajo ninguna circunstancia.
41 
42---
43 
44## CUÁNDO LEER CADA ARCHIVO
45 
46Claude lee estos archivos SOLO cuando la tarea lo requiere, no por defecto:
47 
48| Estás trabajando en...                                                              | Leer                      |
49|-------------------------------------------------------------------------------------|---------------------------|
50| Docker, Nginx, volúmenes, infraestructura                                           | `docs/INFRA.md`           |
51| Settings, auth, permisos, headers, ataques                                          | `docs/SECURITY.md`        |
52| Modelos, vistas, serializers, servicios, ORM, comentarios                           | `docs/CODING.md`          |
53| Try/except, logging, excepciones, errores en tasks o signals                        | `docs/ERROR_HANDLING.md`  |
54| Tests, factories, mocks, coverage                                                   | `docs/TESTING.md`         |
55| Logs, métricas, Grafana, Flower, trazabilidad                                       | `docs/OBSERVABILITY.md`   |
56| Celery tasks, emails, Resend, colas                                                 | `docs/EMAIL.md`           |
57| Datos de usuarios, consentimiento, privacidad                                       | `docs/GDPR.md`            |
58| Antes de un PR o deploy                                                             | `docs/VERIFICATION.md`    |
59| API versioning, feature flags, i18n, timezones, search, migrations, archivos estáticos | `docs/DAY1.md`        |
60 
61---
62 
63## ESTRUCTURA DEL PROYECTO
64 
65```
66config/
67├── settings/
68│   ├── base.py          # Settings base compartidos
69│   ├── development.py   # Solo desarrollo local
70│   ├── production.py    # Producción — sin DEBUG, con Docker Secrets
71│   └── test.py          # Tests — SQLite en memoria, Celery eager
72├── urls.py
73├── wsgi.py
74└── asgi.py
75manage.py
76apps/
77├── users/               # Autenticación, perfil, RBAC
78├── tracing/             # Middleware de trazabilidad (ver OBSERVABILITY.md)
79└── [tu_app]/
80docs/                    # Estos archivos de contexto
81docker/                  # Dockerfiles y configs de servicios
82```
83 
84---
85 
86## PRE-COMMIT CHECKLIST (mínimo antes de cada commit)
87 
88```
89[ ] Sin secrets ni API keys en el código
90[ ] .env en .gitignore y no commiteado
91[ ] Sin print() o logger.debug() con datos sensibles
92[ ] Nuevos endpoints tienen autenticación y permisos
93[ ] Inputs de usuario validados antes de usar
94[ ] Errores retornan mensajes genéricos al cliente
95[ ] Nuevas dependencias con versiones pinneadas
96[ ] Dockerfiles no corren como root
97[ ] Nuevas acciones de negocio agregadas al ActionType enum (tracing)
98[ ] Nuevos params en tracing pasan por _sanitize_params()
99```
100