# 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 -- `), 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).