web-vaccine-tracker: Instructions file for Claude Code

CLAUDE.md — web-vaccine-tracker

Panel histórico de vacunación COVID-19. El dominio está cerrado (la pandemia terminó): no hay API en vivo, el dataset es el histórico completo de Our World in Data horneado a build-time en src/data/ (formato columnar {fields, rows}, ver ese directorio cuando exista). Arquetipo: app de dataviz, no librería — no aplican reglas de exports map / tree-shaking / publicación npm.

Barra de calidad

Stack: Vite + React + TypeScript. Todo código nuevo se escribe CONTRA esta barra, no se audita después. Las prácticas de stack se apoyan en proyectos open source públicos, citados con su URL donde aplican.

Piso de craft (regla de intención clara)

• a. Nombres de dominio, no de mecanismo — daily_vaccinations, no data/item.
• b. Comentarios explican el PORQUÉ, nunca el QUÉ.
• c. La firma pública se entiende sin leer el cuerpo.
• d/e. Un cambio de regla se edita en UN lugar. Ya nos mordió una vez (ver git log — SelectCountry duplicado en dos carpetas del repo viejo, un fix aplicado a una copia y no a la otra). Si aparece una segunda variante de un componente, extraer un shared/ parametrizable antes de que diverjan.
• f/g. Estado inmutable, consistente ante excepción. El dataset es estático e inmutable en runtime — cualquier useState/derivado debe tratarlo como read-only; nada de mutar los JSON importados.
• h. Fallos de carga de datos se loguean, nunca se tragan. Un país sin archivo (import() que rechaza) es un boundary — no un .catch(() => []) silencioso sin traza. El bug de pantalla-en-blanco del repo anterior (home rota por Promise.all sin .catch) fue exactamente esto.
• i. Toda carga async tiene manejo de fallo explícito — usar Promise.allSettled cuando un país faltante no debe tumbar el batch completo.
• j. N/A (no hay auth/permisos en este repo — dataset público estático).

Piso de legibilidad en frío (k–m)

• k. El README lidera con una captura/GIF real del panel, no solo texto — es un artefacto visual, la descripción sola no cuenta como prueba.
• l. N/A por ahora — no hay claim de perf/robustez que probar hasta que exista el pipeline de datos real; cuando se agregue el fetch/build de OWID, documentar con qué se validó (conteo de filas, rango de fechas, países cubiertos).
• m. Framing honesto: el README debe decir explícitamente que los datos son históricos y fijos (no un tracker en vivo) — no reusar lenguaje de "en tiempo real" heredado de la versión COVID-era.