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

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

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.
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:

{
  "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):

¿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.
¿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?
¿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.

6.1 KiB Raw Permalink Blame History