# GUÍA — Primeros pasos con Claude Code

> Cómo arrancar la Etapa 1 con Claude Code siguiendo el método. Tu rol acá es **director**: decidís
> qué se hace, validás el output, no traducís entre el agente y el código.

---

## 0. Antes de tocar Claude Code

1. Creá el repo y copiá estos archivos respetando la estructura:
   ```
   encuestas-soberanas/
   ├── CLAUDE.md
   ├── ARCHITECTURE.md
   ├── DATA_MODEL.md
   ├── .claude/
   │   ├── settings.json          ← este (commiteable: deny compartido)
   │   └── settings.local.json    ← lo creás vos (gitignored: tus allow personales)
   ├── docs/adr/
   │   ├── ADR-001-privacidad-y-gobierno-de-datos.md
   │   ├── ADR-002-stack-tecnologico.md
   │   └── ADR-003-consentimiento-versionado.md
   └── sprints/sprint-1/
       ├── BRIEF.md
       └── ETAPA_1_PROMPT.md
   ```
2. `git init`, primer commit con estos archivos **antes** de generar código. Así cada cambio del
   agente es auditable contra un punto de partida limpio.
3. Agregá un `.gitignore` con `.env`, `.env.*`, `.claude/settings.local.json`. **El `.gitignore` es la
   protección real de los secretos**; las reglas `Read(...)` de `settings.json` son defensa adicional
   pero han tenido fallas conocidas — no dependas solo de ellas.

## 1. Instalar Claude Code

Se distribuye como paquete npm: `@anthropic-ai/claude-code`. La forma recomendada de instalar cambia
seguido (npm global, instalador nativo, etc.), así que seguí la oficial actual:
**https://docs.claude.com/en/docs/claude-code/overview**. Necesita Node.js; verificá la versión
mínima en esa misma página. Lo abrís desde la carpeta del repo para que cargue tu `.claude/`.

## 2. Entender los permisos versionados (`.claude/settings.json`)

El método separa **protecciones (deny, compartidas)** de **preferencias (allow, personales)**:

- `settings.json` (commiteable) → reglas **deny** críticas que hereda todo el equipo: bloquea
  `rm -rf` peligrosos, `git push --force`, `git reset --hard`, y lectura de secretos. Incluye
  `"disableBypassPermissionsMode": "disable"`, que impide usar `--dangerously-skip-permissions` — es
  la barrera de equipo contra el anti-patrón AP.7.
- `settings.local.json` (gitignored) → tus **allow** personales para que los comandos rutinarios
  (`npm run`, `supabase migration`, etc.) no te pidan aprobación a cada paso. Ejemplo:
  ```json
  {
    "permissions": {
      "allow": [
        "Bash(npm run:*)",
        "Bash(npm install)",
        "Bash(supabase migration new:*)",
        "Bash(supabase db reset)",
        "Bash(git add:*)",
        "Bash(git commit:*)"
      ]
    }
  }
  ```
- Las reglas se evalúan **deny → ask → allow**; deny siempre gana. Aceptá la fricción ocasional de un
  `ask` como precio de la gobernanza; no skipees permisos de rutina.

## 3. Arrancar la Etapa 1 — mensaje inicial corto

No pegues el prompt entero en el chat (anti-patrón AP.6). El prompt ya vive en el repo. Tu mensaje
inicial es corto y referencia paths (Patrón B.2). Algo así:

```
Vamos con la Etapa 1 del Sprint 1.

Leé en este orden antes de tocar nada:
1. CLAUDE.md (reglas no negociables — especialmente privacidad y la política de niveles)
2. ARCHITECTURE.md y docs/adr/ADR-001-privacidad-y-gobierno-de-datos.md
3. DATA_MODEL.md (el contrato de esquema que vas a implementar)
4. sprints/sprint-1/BRIEF.md y sprints/sprint-1/ETAPA_1_PROMPT.md

Ejecutá la Etapa 1 según ETAPA_1_PROMPT.md. Respetá el alcance: solo esquema + RLS +
constraints + función de k-anonimato + tablas de consentimiento + seed. Nada de frontend.

Cuando termines, reportá en el formato de la sección 7 del prompt, con la salida de
git diff --name-only HEAD. No declares la etapa lista solo por tests verdes.
```

## 4. Tu loop de validación (cuando el agente reporta)

No confíes en "todo OK". Aplicá las 3 preguntas (auditoría adversarial, Principio 3):

1. **¿Los números cuadran?** Pedí la salida concreta de `agg_segment` para n=3 y n=5, el conteo de
   preguntas del seed, el nº de tablas. Si el reporte describe en vez de mostrar, pedí los datos.
2. **¿Es el artefacto que pedí?** Abrí el esquema generado (Supabase Studio o el SQL de las
   migraciones) **con tus ojos**. ¿Están las 7 tablas? ¿`responses.respondent_id` es nullable y va
   NULL? ¿Existe el constraint anti-`respondent_id`?
3. **¿Qué NO menciona el reporte?** Si el reporte está más limpio de lo esperado, sospechá. Revisá
   `git diff --name-only HEAD`: ¿tocó algún archivo fuera de scope?

Checklist mínima específica de esta etapa:
- [ ] Probá vos mismo: como rol de organización, ¿podés leer una fila cruda? (debe dar 0)
- [ ] Probá: `INSERT` con `respondent_id` en encuesta anónima → debe fallar.
- [ ] Probá: `UPDATE` sobre `consent_records` → debe fallar.
- [ ] Mirá el seed: ¿B1/C1/D1 despliegan sus sub-preguntas según las reglas condicionales?

## 5. Qué NO hacer (anti-patrones)

- **No** declares la etapa lista por "tests verdes" sin abrir el esquema (AP.1).
- **No** pegues briefs gigantes en el chat; viven en el repo (AP.6).
- **No** uses `--dangerously-skip-permissions` de rutina (AP.7) — ya está bloqueado en settings.json.
- **No** dejes que el agente "arregle de paso" algo de privacidad/consentimiento: es Nivel 3, consulta antes (AP.8).
- Si una convención (formato de cifras, idioma) aparece 2 veces como pregunta → documentala en
  `CONVENTIONS.md` (AP.4).

## 6. Antes de cargar datos reales (no en v1 interno)

- Resolver la **residencia de datos** (ADR-002 abierto): self-host vs Cloud.
- Validar el flujo de consentimiento y el lenguaje legal con un **asesor paraguayo** (Ley 7593/2025).
- Hasta entonces, v1 corre con **datos de prueba/simulados**, no con respuestas reales de ciudadanos.

---

### Qué sigue después de la Etapa 1
Validada la fundación de datos, las próximas etapas (a especificar en sus prompts) son: el formulario
funcional sobre este esquema, y luego el dashboard con los reportes cruzados. El wizard de creación
de encuestas viene después de validar el caso fijo. Cada una arranca con su prompt versionado.