Primer commit - Sprint 1
This commit is contained in:
markosbenitez
126
GUIA_PRIMEROS_PASOS.md
Normal file
126
GUIA_PRIMEROS_PASOS.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user