🌿 Salud Natura

Taller: Página Web Dinámica con Claude Code

Bienvenidos al Taller

En este taller van a aprender a colaborar en un proyecto real usando GitHub. Van a hacer un fork del repositorio, clonar el código, hacer cambios y crear un Pull Request. No es imprescindible tener Claude Code — podés consultar con cualquier IA para que te ayude en el proceso.

Repositorio del proyecto:

https://github.com/centrograduadosFIUBA/salud_natura

Conceptos básicos

No hace falta ser programador para colaborar en este proyecto. Sí es útil entender de qué se habla cuando se mencionan estos términos.

🖥️

Frontend vs Backend

Una aplicación web tiene dos mitades. El frontend es todo lo que el usuario ve y toca: el diseño, los botones, los textos en pantalla. El backend es la parte invisible que corre en un servidor: procesa los datos, consulta la base de datos y devuelve respuestas. Cuando abrís el grimorio, el frontend dibuja el libro; el backend le responde con la lista de plantas. Ambas partes se comunican por la red usando una API.

⚡

Páginas web dinámicas

Una página estática siempre muestra lo mismo: está escrita en HTML fijo y cualquier cambio requiere editar el archivo. Una página dinámica genera su contenido en el momento en que se la visita: consulta una base de datos, aplica lógica y arma el HTML resultante. Salud Natura es dinámica: cuando alguien agrega una planta desde el admin, aparece automáticamente en el grimorio sin tocar ningún archivo.

🏗️

HTML · CSS · JavaScript

Son los tres lenguajes del frontend. HTML define la estructura: qué elementos hay en la página (títulos, párrafos, botones, imágenes). CSS define el estilo: colores, tipografías, tamaños y posiciones. JavaScript agrega comportamiento: reacciona a los clics del usuario, llama a la API para pedir datos y actualiza la pantalla sin recargar la página. En este proyecto, podés cambiar visualmente el sitio tocando solo HTML y CSS, sin necesidad de entender JavaScript.

🗄️

Base de datos relacional

Una base de datos relacional organiza la información en tablas, igual que una planilla de cálculo. Cada tabla tiene filas (registros) y columnas (campos). Lo que la hace "relacional" es que las tablas se pueden relacionar entre sí: la tabla de jugos tiene una columna id_remedio que apunta a la tabla de remedios, evitando duplicar información. Este proyecto usa SQLite, una base de datos relacional que se guarda en un único archivo, ideal para proyectos pequeños y medianos.

🔍

SQL

SQL (Structured Query Language) es el lenguaje para hablarle a una base de datos relacional. Con SQL podés consultar datos (SELECT), insertar registros nuevos (INSERT), modificar existentes (UPDATE) y eliminarlos (DELETE). Por ejemplo, SELECT * FROM jugos WHERE id_remedio = 9 devuelve todos los jugos relacionados con la manzanilla. No hace falta memorizarlo: podés pedirle a una IA que escriba la consulta que necesitás describiendo lo que querés obtener.

📦

JSON

JSON (JavaScript Object Notation) es el formato estándar en que los datos viajan entre el frontend y el backend. Se parece a un diccionario: claves entre comillas, valores separados por comas, todo entre llaves. Por ejemplo: {"nombre": "Manzanilla", "propiedades": "digestiva, calmante"}. Cuando el grimorio le pide a la API la lista de plantas, el servidor responde con un JSON. El navegador lo recibe, lo lee y dibuja las tarjetas en pantalla. Es liviano, legible y compatible con todos los lenguajes de programación.

🔌

Endpoint / API

Un endpoint es una URL del servidor que está esperando recibir pedidos y devuelve datos. Una API (Application Programming Interface) es el conjunto de todos esos endpoints. Por ejemplo, GET /api/plantas es un endpoint que devuelve la lista de plantas en formato JSON. POST /api/registro es otro endpoint que recibe los datos de un nuevo usuario y los guarda en la base de datos. Las APIs permiten que el frontend y el backend hablen entre sí, y también que otras aplicaciones usen los datos del sistema.

🌿

Git y control de versiones

Git es un sistema que registra cada cambio en el código a lo largo del tiempo, como un historial con "deshacer" ilimitado. Cada commit es una foto del estado del proyecto en un momento dado, con un mensaje que explica qué cambió. Un repositorio contiene todo el historial. Una rama (branch) es una línea de trabajo paralela: podés experimentar sin tocar el código principal. GitHub es la plataforma donde se alojan los repositorios y donde los equipos colaboran enviando Pull Requests — propuestas de cambio que otros pueden revisar antes de aceptar.

Recomendaciones para el desarrollo

Buenas prácticas que evitan la mayoría de los problemas al colaborar en un proyecto real.

📐

Definí los datos antes de escribir código

Antes de tocar un archivo, pensá qué información necesitás guardar: ¿qué tabla? ¿qué campos? ¿hay relaciones con otras tablas? Por ejemplo, si querés agregar "recetas", preguntate: ¿una receta puede tener varias plantas o solo una? ¿tiene pasos o es texto libre? ¿necesita una foto? Esas decisiones definen la estructura de la base de datos, y cambiarla después de tener datos cuesta mucho más que pensarla bien desde el principio.

🪜

Hacé cambios pequeños y revisá seguido

No intentes hacer todo de una vez. Agregá un campo → verificá que se guarda → agregá el formulario → verificá que aparece en pantalla → commit. Cada paso chico es fácil de deshacer si algo falla. Un cambio grande que rompió algo en el medio es difícil de diagnosticar. El historial de Git es tu red de seguridad: un commit por cada cosa que funciona.

🗂️

Entendé qué archivos se generan y mirales adentro

Este proyecto genera archivos que no están en el repositorio: la base de datos (data/salud_natura.db), el entorno virtual (.venv/), los archivos de caché de Python (__pycache__/). Entender qué es cada cosa te ayuda a no confundirte: si borrás el .venv tenés que reinstalar dependencias; si borrás el .db perdés todos los datos. Podés explorar la base de datos con DB Browser for SQLite para ver las tablas y los registros directamente.

🚫

No hardcodees datos en el código

Hardcodear significa poner un dato directamente en el código en lugar de guardarlo en la base de datos o en la configuración. Si ponés los nombres de las plantas en el HTML, cada vez que cambia una planta tenés que editar el archivo. Si están en la base de datos, las cambiás desde el admin sin tocar código. Como regla: los datos que el negocio puede querer editar van a la BD; la configuración del sistema (claves, rutas, nombre de la app) va a un archivo de settings; solo la lógica va en el código.

🚀

Cómo arrancar tu propio proyecto desde este prototipo

Este proyecto es una plantilla funcional completa: tiene base de datos, API, panel de administración, frontend y deploy automático. No hace falta empezar de cero. La estrategia es adaptar este código a tu dominio antes de escribir una sola línea nueva.

Paso 1 — Definí tu dominio antes de abrir el editor

Antes de tocar código, respondé estas preguntas en papel: ¿Qué entidades principales tiene tu sistema? ¿Qué datos guarda cada una? ¿Cómo se relacionan entre sí? Por ejemplo, si tu proyecto es una biblioteca: entidades = libros, autores, préstamos. Un libro tiene título, año, ISBN, id_autor. Un préstamo tiene id_libro, id_usuario, fecha. Ese diseño define tus tablas — y cambiar tablas después de tener datos es costoso.

Paso 2 — Pedile al LLM que adapte las configuraciones iniciales

Una vez que tenés el diseño en papel, hacé un fork de este repositorio y abrilo con tu asistente de IA. Describile tu proyecto y pedile que adapte los archivos clave uno por uno, en este orden:

  1. settings.py — nombre de la app, versión, configuración general
  2. database.py — reemplazar las tablas existentes por las tuyas
  3. models.py — los modelos Pydantic que validan los datos que entran por la API
  4. main.py — los endpoints GET y POST para cada tabla
  5. Los templates de admin — un ABM (Alta-Baja-Modificación) por tabla

No le pidas todo a la vez. Pedí un archivo, revisalo, probalo, y recién entonces pedí el siguiente.

Paso 3 — El ciclo de desarrollo: pensar → pedir → revisar → commitear

Cada funcionalidad nueva sigue el mismo ciclo: pensás qué querés lograr y lo describís en lenguaje natural → le pedís al LLM que lo implemente → revisás el código que generó (aunque no lo entiendas todo, fijate que tenga sentido) → lo probás en el navegador → commiteás si funciona. Nunca acumules varios cambios sin commitear: si algo se rompe, no vas a saber qué lo causó.

Paso 4 — Empezá por los datos, no por el diseño

El error más común es arrancar cambiando colores y tipografías antes de tener los datos funcionando. El diseño visual es lo más fácil de cambiar al final. Lo difícil de cambiar después es la estructura de la base de datos y la lógica del backend. Prioridad: primero que los datos entren y salgan correctamente; después que se vean bien.

Paso 5 — Levantá el servidor local y dejalo corriendo mientras desarrollás

Con uvicorn app.main:app --reload el servidor se reinicia automáticamente cada vez que guardás un archivo Python. Así podés probar cada cambio de inmediato sin reiniciar nada manualmente. Abrí el navegador en localhost:8000 y dejalo al lado del editor. Si algo se rompe, el error aparece en la terminal — copialo y pegáselo al LLM con contexto de qué estabas haciendo.

El LLM es un colaborador, no un diseñador

El LLM puede escribir código muy bueno, pero no conoce tu negocio ni tus datos. Cuanto más específico seas al pedirle — nombres de tablas, campos, tipos de datos, relaciones, qué hace cada pantalla — mejor va a ser el resultado. Si le decís "hacé un proyecto de biblioteca" vas a obtener algo genérico que después vas a tener que corregir mucho. Si le decís "necesito una tabla libros con campos título, año, ISBN y un campo id_autor que referencia a la tabla autores" vas a obtener exactamente lo que necesitás. La precisión en el pedido es la habilidad más importante para trabajar bien con IA.

Resistí la tentación de "tirarle" un PDF a Claude Code y que se arregle

Es una de las primeras tentaciones cuando empezamos a trabajar con Claude Code. Tenemos un folleto, un documento de Word, un PDF de una empresa o un manual de productos y pensamos: "Se lo paso a Claude Code y que haga la página."

A veces funciona sorprendentemente bien. Otras veces... el resultado termina siendo un verdadero dolor de cabeza.

El problema no es Claude Code. El problema es que un PDF no es una especificación técnica.

Un PDF suele mezclar muchas cosas al mismo tiempo: información importante, textos comerciales, ejemplos, imágenes, comentarios, datos históricos, información repetida, detalles que no corresponden a una página web.

Cuando Claude Code recibe ese documento, tiene que interpretar qué es importante y qué no. Como cualquier desarrollador al que le entregan un documento ambiguo, completa los espacios vacíos tomando decisiones por su cuenta.

Y ahí aparecen problemas muy comunes:

Un flujo mucho más profesional

En lugar de hacer esto:

PDF → Claude Code

Conviene trabajar así:

PDF → LLM Analista → Especificación → Claude Code

Paso 1 — Conversá con un LLM

Podés usar ChatGPT, Claude en modo conversación, Gemini o cualquier otro modelo. Su trabajo no es programar: su trabajo es comprender el documento. Durante esta etapa conviene hacer preguntas como:

En otras palabras, el LLM actúa como un analista funcional.

Paso 2 — Construí una especificación

Una buena especificación debería indicar:

Cuanto más clara sea esta especificación, menos tendrá que "imaginar" Claude Code.

Paso 3 — Recién ahí empezá a programar

Claude Code funciona mucho mejor cuando recibe instrucciones precisas. En lugar de interpretar un PDF completo, recibe una descripción clara de lo que debe construir. Eso reduce enormemente los errores y hace que el proyecto sea mucho más fácil de mantener y continuar.

Pensá como un equipo de desarrollo

En un proyecto profesional normalmente no sucede Cliente → Programador. Sucede Cliente → Analista → Especificación → Programador. Cuando trabajamos con IA ocurre exactamente lo mismo: el LLM conversacional cumple el rol del analista; Claude Code cumple el rol del desarrollador. Cada uno hace aquello para lo que está mejor preparado.

No le pidas a Claude Code que descubra qué querías hacer. Explicáselo.

Invertir veinte minutos en conversar con un LLM para transformar un PDF en una especificación detallada suele ahorrar varias horas de correcciones y retrabajo.

Los mejores proyectos con IA no empiezan escribiendo código. Empiezan escribiendo una buena especificación.

1

Requisitos previos

Antes de empezar, asegurense de tener instalado:

⚠️ Importante: Instalá específicamente Python 3.11, no una versión más nueva (3.12, 3.13, 3.14). El servidor en producción usa Python 3.11 y algunas librerías del proyecto (como pydantic-core) todavía no son compatibles con versiones más recientes. Al instalar, marcá la opción "Add Python to PATH". Después podés verificar la versión con python --version.
2

Fork del repositorio

Un fork es una copia del repositorio en tu propia cuenta de GitHub. Esto te permite hacer cambios sin afectar el proyecto original.

  1. Entrá a github.com/centrograduadosFIUBA/salud_natura
  2. Hacé clic en el botón "Fork" (arriba a la derecha)
  3. Seleccioná tu cuenta personal como destino
  4. Esperá a que se cree la copia — vas a tener el repo en github.com/TU_USUARIO/salud_natura
💡 Tip: El fork mantiene una conexión con el repo original, lo que permite después enviar tus cambios como un Pull Request.
3

Clonar el repositorio

Ahora vas a descargar tu fork a tu computadora para poder trabajar localmente.

Abrí una terminal y ejecutá:

git clone https://github.com/TU_USUARIO/salud_natura.git

Reemplazá TU_USUARIO por tu nombre de usuario de GitHub.

Entrá a la carpeta del proyecto:

cd salud_natura
💡 Tip: También podés pedirle a Claude Code: "Cloná mi fork de salud_natura y abrilo"
4

Crear una rama de trabajo

Nunca trabajamos directo en main. Creamos una rama con nuestro nombre para los cambios:

git checkout -b feature/mi-nombre-cambio

Por ejemplo:

git checkout -b feature/jose-nuevo-remedio
5

Levantar el proyecto localmente

Para ver los cambios en tu navegador mientras trabajás:

# Crear entorno virtual python -m venv .venv # Activar (Windows) .venv\Scripts\activate # Activar (Mac/Linux) source .venv/bin/activate # Instalar dependencias pip install -r requirements.txt # Levantar el servidor uvicorn app.main:app --reload --port 8000

Abrí http://localhost:8000 en tu navegador.

💡 Tip: Pedile a Claude Code: "Instalá las dependencias y levantá el servidor"
6

Hacer un cambio

Ahora viene lo divertido. Elegí uno o varios cambios de la lista según tu nivel. Podés pedirle a cualquier IA que te ayude: describile lo que querés en lenguaje natural y te va a guiar.

🟢 Nivel principiante — sin tocar código

Ideal para arrancar. Usás el admin del sitio, no hace falta editar archivos.

  • Agregar un remedio nuevo desde el panel de administración (/admin/remedios) — inventá una hierba o buscá una real
  • Editar un remedio existente — corregí una propiedad, agregá una contraindicación
  • Agregar un usuario de prueba desde /admin/usuarios

🟡 Nivel intermedio — cambios visuales

Editás archivos de estilo o plantillas HTML. Cambios visibles de inmediato.

  • Cambiar un color — modificá el color del header, del fondo o de los botones en app/static/css/style.css
  • Cambiar un texto — modificá el título, el subtítulo o la cita en app/templates/index.html
  • Cambiar la tipografía — probá otra fuente de Google Fonts en el CSS
  • Agregar un enlace al menú de navegación — por ejemplo, un link a /taller o a /grimorio
  • Modificar el footer — agregá un texto, un link o cambiá el copyright

🟠 Nivel avanzado — cambios funcionales

Tocás el backend (Python) o agregás funcionalidad nueva.

  • Agregar un campo nuevo a la tabla de remedios — por ejemplo, "origen geográfico" o "método de preparación" en app/database.py y app/models.py
  • Crear un endpoint nuevo en la API — por ejemplo, /api/remedios/buscar?q=menta en app/main.py
  • Agregar un buscador de remedios en la página principal con JavaScript
  • Hacer que el formulario de contacto envíe un mail real usando smtplib
  • Agregar una página nueva — por ejemplo, /acerca con la historia de Salud Natura
  • Exportar los datos de la base a CSV — crear un endpoint /api/remedios/exportar que descargue los remedios como archivo CSV o Excel, para abrirlo en Google Sheets o LibreOffice

🔴 Nivel experto — desafíos

Para los que quieran ir más allá. Requieren pensar la arquitectura.

  • Agregar autenticación al admin — proteger /admin con usuario y contraseña
  • Implementar la tabla de productos afiliados (CATALOGO_PRODUCTOS_EXTERNAL) con su ABM
  • Agregar geolocalización — que el usuario pueda ver la franquicia más cercana con la fórmula de Haversine
  • Crear un sistema de favoritos — que un usuario pueda marcar remedios como favoritos
  • Integrar WhatsApp — botón que arme un mensaje pre-armado con el remedio seleccionado
💡 Tip: Pedile a tu IA asistente lo que quieras cambiar en lenguaje natural. Por ejemplo:
  • "Cambiá el color del header a azul oscuro"
  • "Agregá un buscador que filtre remedios por nombre"
  • "Creá una página /acerca con información del proyecto"
  • "Agregá un campo 'origen' a la tabla de remedios y mostralo en el grimorio"
7

Commitear los cambios

Una vez que hiciste tu cambio y verificaste que funciona:

# Ver qué archivos cambiaron git status # Agregar los archivos modificados git add -A # Crear el commit con un mensaje descriptivo git commit -m "feat: descripción corta de mi cambio"

Convención de mensajes:

  • feat: — nueva funcionalidad
  • fix: — corrección de bug
  • docs: — documentación
  • style: — cambios de estilo/CSS
💡 Tip: Pedile a Claude Code: "Hacé un commit con los cambios"
8

Pushear la rama

Subí tu rama a tu fork en GitHub:

git push -u origin feature/mi-nombre-cambio
9

Crear el Pull Request (PR)

El Pull Request es la forma de proponer tus cambios al proyecto original.

  1. Entrá a tu fork en GitHub (github.com/TU_USUARIO/salud_natura)
  2. GitHub te va a mostrar un banner amarillo: "Compare & pull request" — hacé clic
  3. Verificá que el PR vaya hacia:
    • Base repository: centrograduadosFIUBA/salud_natura
    • Base: main
    • Head repository: TU_USUARIO/salud_natura
    • Compare: tu rama
  4. Escribí un título descriptivo y una descripción de lo que cambiaste
  5. Hacé clic en "Create pull request"
💡 Tip: También podés crear el PR desde Claude Code: "Creá un Pull Request con mis cambios"
✓

¡Listo!

Tu Pull Request va a ser revisado por los tutores. Si está todo bien, se mergea al proyecto y tus cambios van a aparecer en saludnatura.graduadosfiuba.org.

¡Felicitaciones, acabás de colaborar en un proyecto real!

Recursos útiles