Primer commit - Sprint 1
This commit is contained in:
markosbenitez
117
CLAUDE.md
Normal file
117
CLAUDE.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# CLAUDE.md — Reglas del proyecto
|
||||
|
||||
> Este archivo lo carga el agente (Claude Code) por defecto. Contiene lo que aplica a **TODO** el
|
||||
> proyecto: reglas no negociables, decisiones ya tomadas, política de iniciativa y verificaciones
|
||||
> pre-entrega. El agente NO puede re-decidir lo que está acá. (Patrón B.4.)
|
||||
|
||||
---
|
||||
|
||||
## Identidad del proyecto
|
||||
|
||||
Plataforma de encuestas con soberanía de datos. Caso fundacional: mapeo de cuidadores en empresas.
|
||||
Objetivo macro: "economía de la discapacidad" en Paraguay. Trata **datos sensibles** (salud/
|
||||
discapacidad) → la privacidad no es una feature, es una restricción de diseño.
|
||||
|
||||
---
|
||||
|
||||
## Reglas no negociables (datos y privacidad)
|
||||
|
||||
1. **Anonimato es por-encuesta**, no global. Cada encuesta declara su modo; el esquema y la lógica
|
||||
de guardado lo respetan. Nunca asumir anonimato por defecto ni quitarlo por conveniencia.
|
||||
2. **En encuestas anónimas, NUNCA escribir una clave de individuo** (`respondent_id`) ni cookie de
|
||||
sesión linkeable. La deduplicación se hace con `ip_hash` (hash unidireccional + salt), nunca con
|
||||
identidad.
|
||||
3. **El umbral de k-anonimato es mandatorio en toda visualización compartida.** Ninguna celda,
|
||||
gráfico o tabla expuesta a una empresa puede mostrar un segmento con **n < UMBRAL_K** (config del
|
||||
proyecto, default 5). Esto aplica AUNQUE la encuesta sea anónima.
|
||||
4. **El texto libre NO entra al store analítico crudo.** Se excluye o se categoriza antes (es un
|
||||
vector de re-identificación). El gráfico/reporte trabaja sobre categorías, no sobre texto crudo.
|
||||
5. **El consentimiento es evidencia, no UI.** Cada respuesta guarda un registro de consentimiento
|
||||
versionado, con timestamp, inmutable, contra la versión del texto vigente al momento. Cambiar el
|
||||
wording del consentimiento NO altera registros viejos. (Ver ADR-003.)
|
||||
6. **La elección granular del titular (el respondente) siempre gana** sobre cualquier documento
|
||||
firmado por la empresa. La empresa autoriza el despliegue; el individuo consiente el tratamiento
|
||||
de su propio dato.
|
||||
7. **Modo de responsable (`controller_role`) define el flujo de datos:**
|
||||
- **Modo A** (nosotros = responsable): el dato puede alimentar el macro a todos los niveles que el
|
||||
titular consintió.
|
||||
- **Modo B** (empresa = responsable, nosotros = encargado): el dato **solo** puede alimentar el
|
||||
macro vía **Nivel 1 anonimizado irreversible**. Nunca Nivel 2/3.
|
||||
- **v1 corre solo Modo A.** El campo existe pero la lógica dual no se construye todavía.
|
||||
8. **La empresa nunca accede a dato individual crudo.** Solo recibe agregados/dashboards autorizados
|
||||
por encima del umbral. (Coherente con Modo A + k-anonimato.)
|
||||
|
||||
---
|
||||
|
||||
## Distinción que NO se puede volver a confundir: anónimo vs pseudónimo
|
||||
|
||||
- **Comparar segmentos** ("alguien de 25, sector X, zona A" vs "alguien de 25, sector X, zona B") se
|
||||
hace con los **cuasi-identificadores guardados en cada fila**. NO requiere `respondent_id`. Vive en
|
||||
datos 100% anónimos.
|
||||
- **`respondent_id`** (clave pseudónima) sirve para vincular varias respuestas a la **misma persona
|
||||
desconocida** (longitudinal individual, re-contacto, dedup avanzado). **Nada de eso es caso de v1.**
|
||||
- Por lo tanto: anónimo a nivel respondente **alcanza** para la comparación que el producto necesita.
|
||||
La comparación individuo-vs-individuo (n=1) está **prohibida** en dashboards compartidos.
|
||||
|
||||
---
|
||||
|
||||
## Política de iniciativa proactiva (clasificar antes de actuar)
|
||||
|
||||
Ante una mejora fuera del scope, el agente clasifica el impacto y actúa según el nivel. Evaluar en
|
||||
este orden; el primero que aplique decide:
|
||||
|
||||
1. ¿Resuelve un ítem de `TECH_DEBT.md` / `BACKLOG.md` / planificación? → **Nivel 3**.
|
||||
2. ¿Choca con restricción explícita del prompt ("NO entra", "NO tocar", "agendado para etapa Z")? → **Nivel 3**.
|
||||
3. ¿Toca privacidad, anonimato, consentimiento, clasificación de datos o RLS? → **Nivel 3 SIEMPRE**.
|
||||
4. ¿Modifica paginación, layout, cantidad de archivos o estructura de salida? → **Nivel 2 mínimo**.
|
||||
5. ¿Es visible al usuario final (texto, color, posición, contenido)? → **Nivel 2 mínimo**.
|
||||
6. ¿Afecta marca, identidad, dependencias o configuración? → **Nivel 3**.
|
||||
7. Si nada aplica → **Nivel 1**.
|
||||
|
||||
- **Nivel 1** (interno, invisible, reversible): ejecutar; mencionar al final si fueron varios.
|
||||
- **Nivel 2** (visible reversible): ejecutar **y reportar** como "decisión proactiva — validar/revertir".
|
||||
- **Nivel 3** (marca/arquitectura/datos/privacidad): **NO ejecutar. Consultar antes** con el formato:
|
||||
```
|
||||
PROPUESTA DE CAMBIO NIVEL 3 — requiere aprobación
|
||||
Cambio sugerido: [descripción] Justificación: [por qué] Impacto: [qué afecta] Alternativa si se rechaza: [qué hacer]
|
||||
```
|
||||
|
||||
Argumentos que NO bajan de nivel: "es legibilidad", "es consistencia", "es trivial de revertir",
|
||||
"es un bug menor", "el usuario lo va a agradecer". Si está en TECH_DEBT/BACKLOG, es Nivel 3 sin
|
||||
importar el tamaño técnico.
|
||||
|
||||
---
|
||||
|
||||
## Verificaciones obligatorias antes de entregar (toda etapa)
|
||||
|
||||
1. `git diff --name-only HEAD` → solo archivos autorizados por el prompt. Si aparece uno no
|
||||
autorizado: revertir (`git checkout HEAD -- <archivo>`), listar bajo "Conflictos de scope", no incluirlo.
|
||||
2. Si una restricción del prompt (`NO tocar X`) colisiona con otro requisito (build limpio):
|
||||
**DETENERSE y reportar el conflicto**, no resolver unilateralmente.
|
||||
3. Reporte con **datos concretos**, no descripciones ("PDF: 78 KB, 4 págs, tabla 11 filas",
|
||||
no "PDF generado correctamente").
|
||||
4. Separar explícitamente **Verificado** vs **Asumido** vs **Hallazgos no esperados**.
|
||||
5. Tests verdes **NO** es etapa terminada. Si hay artefacto visible, el humano lo abre (validación
|
||||
visual la hace el director, no el agente).
|
||||
|
||||
---
|
||||
|
||||
## Decisiones ya tomadas (no consultar de nuevo)
|
||||
|
||||
- Etapa 1 = una encuesta fija (mapeo cuidadores) multi-empresa. **NO** builder visual.
|
||||
- Las 4 encuestas de v1: anónimas a nivel respondente + confidenciales (seguridad).
|
||||
- Se conservan `company_id` + cuasi-identificadores. NO se usa `respondent_id`.
|
||||
- Modo A (nosotros responsables). Sin Nivel 3 atribuible en esta etapa.
|
||||
- Empresas actúan sobre agregados, nunca sobre individuos nombrados.
|
||||
- Dedup por `ip_hash`. Consentimiento granular versionado e inmutable.
|
||||
- Umbral de k-anonimato default = 5 (parametrizable por proyecto).
|
||||
- Separador de miles y formato de cifras: **definir en `CONVENTIONS.md`** (ver Decisiones abiertas).
|
||||
|
||||
---
|
||||
|
||||
## Decisiones abiertas (requieren al director, no las cierra el agente)
|
||||
|
||||
- **Nombre/marca del producto** (Nivel 3).
|
||||
- **Residencia de datos**: Supabase Cloud vs self-host (ADR-002).
|
||||
- **`CONVENTIONS.md`**: formato de cifras, idioma de la UI, tono de los mensajes. Apenas una
|
||||
convención se pregunte 2 veces, documentarla acá (anti-patrón AP.4).
|
||||
Reference in New Issue
Block a user