ATLAS · Mundiales

Credenciales: https://send.bitwarden.com/#P0uODQXjpEWy4bRgAM16-g/dpX_SzrXJWMZxOxf7W_qTQ

Como arrancar

pnpm install
cp .env.example .env      # editá .env y pegá las credenciales que te pasamos
pnpm dev                  # http://localhost:3000

.env:

DATABASE_URL=postgresql://readonly:...-pooler...neon.tech/neondb?sslmode=require
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1-mini

Vas a ver el dashboard. Los paneles cuyo endpoint todavía no está implementado muestran "no implementado"; a medida que los implementás, se encienden solos. Ese es tu verificador.

Parte 0 — Construí tu contexto (empezá por acá)

Este taller es de AI coding: el objetivo es que aprendas a hacer que la IA codee bien, no a tipear vos. Y una de las herramientas más importantes para eso es el contexto que le das.

La primera tarea, antes de implementar nada, es crear un archivo AGENTS.md en la raíz del proyecto (Copilot lo lee automáticamente) y llenarlo, explorando el repo con la IA, con lo que la IA necesita saber para codear bien en ESTE proyecto. Un buen AGENTS.md acá debería responder, como mínimo:

• Stack y versiones. ¿Qué framework/SDK y en qué versión? ¿Hay algo no obvio que rompa en silencio?
• La convención de un endpoint. ¿Dónde vive la SQL? ¿Dónde el tipo de respuesta? ¿Qué hace (y qué NO) el route?
• Cómo se verifica. ¿Cómo sabés que un endpoint quedó bien sin leer todo el código generado? (Pista: el panel que se enciende.)
• El esquema de la base y sus trampas. Explorá las tablas. ¿Hay nombres o flags que confundan a la hora de contar?
• Reglas inviolables. Arrancá por una: la base es read-only.

El loop del taller: implementá UN endpoint, fijate si la IA respetó tus convenciones; si no, mejorá tu AGENTS.md y seguí. Cuanto mejor sea tu contexto, mejor (y más rápido) codea la IA.

Y no te quedes solo en el AGENTS.md. Durante el proceso vas a notar tareas que se repiten (implementar un endpoint tras otro, consultar el esquema, validar en el navegador). Esa repetición es la señal: la idea es ir identificando qué skills convendría crear (instrucciones reutilizables que la IA aplica sola, sin que se las recuerdes cada vez) y armarlos cuando los veas. Darte cuenta de cuáles valen la pena es parte del ejercicio.

Qué construir

1. M1 — endpoints. Implementá los endpoints cuyos paneles están en "no implementado" y miralos encender. (stats/overview ya viene hecho, como ejemplo.)
2. M2 — el agente. Implementá POST /api/agent con el Vercel AI SDK: exponé tus query functions como tools y dejá que el modelo decida cuáles usar.
3. M3 — run_query. Sumale al agente una tool que corre SQL arbitrario (read-only) contra la base. Así responde la cola larga que las tools tipadas no cubren.

Comandos

comando	qué hace
pnpm dev	servidor de desarrollo en localhost:3000
pnpm test	corre vitest (unit + integración contra Neon)

Dónde trabajás

src/lib/queries/    # las query functions
src/lib/contracts/  # tipos de respuesta
src/app/api/        # los route handlers (501 → implementalos)
src/components/     # el front: <Panel>, paneles, chat del agente (ya hechos)

Datos: Fjelstul World Cup Database (CC-BY-SA 4.0).