# Guía del Sandbox Toolkit de Humand

> **¿Qué es esto?** Un kit de herramientas que te permite crear mockups funcionales en el navegador — pantallas reales que se ven y se navegan como una app de verdad — sin necesidad de saber programar. Vos describís lo que querés, y Claude (tu asistente de IA) lo construye paso a paso.

---

## ¿Qué puedo hacer con este toolkit?

- **Explorar una idea de producto** antes de involucrar al equipo de desarrollo
- **Validar flujos de navegación** con pantallas que realmente se navegan
- **Crear prototipos funcionales** con tablas, formularios, filtros, menús y más
- **Conectar datos reales** de servicios externos (Google Sheets, Supabase, HubSpot, etc.)
- **Compartir el resultado** con un link para que otros lo vean en su navegador

Todo esto a través de una conversación en lenguaje natural con Claude.

---

## Antes de empezar

Necesitás tener instalado lo siguiente:

| Herramienta | ¿Para qué sirve? | ¿Cómo lo consigo? |
|---|---|---|
| **Claude Desktop** | Es la app donde vas a trabajar — tu asistente de IA | Descargalo desde [claude.ai/download](https://claude.ai/download) e instalalo como cualquier otra app |
| **Plugin humand-frontend-sandbox** | Le da a Claude las instrucciones para construir sandboxes de Humand | Tu equipo de desarrollo te lo configura (ver sección técnica abajo) |
| **Acceso a Notion** | Para documentar el plan del proyecto y seguir el progreso | Ya deberías tener acceso con tu cuenta de Humand |
| **Token de GitHub** | Permite descargar los componentes de diseño de Humand | Tu equipo de desarrollo te lo proporciona |

> **Tip:** Si no estás seguro de tener todo listo, abrí Claude Desktop y escribí `/setup-sandbox`. Claude va a revisar qué tenés y qué falta.

<details>
<summary><strong>Detalle técnico: ¿Qué instala /setup-sandbox?</strong></summary>

El comando `/setup-sandbox` revisa tu máquina y solo instala lo que falte. Estas son las herramientas que necesita:

- **nvm** — un administrador de versiones de Node.js
- **Node.js 24.11.1** — el motor que ejecuta el proyecto
- **bun** — un instalador rápido de paquetes
- **git** — control de versiones (para guardar tu progreso)
- **GitHub CLI (gh)** — para acceder a los paquetes privados de Humand

Todo lo que se instala queda registrado, y se puede desinstalar limpiamente con `/cleanup-sandbox` cuando ya no lo necesites.

Si alguna instalación falla por permisos, Claude te va a dar el mensaje exacto para enviarle a IT.

</details>

---

## El flujo completo, paso a paso

Este es el camino que vas a seguir desde la idea hasta el mockup funcionando:

```
  💡 Idea                    🗺️ Plan                     🔍 Detalle
   ↓                          ↓                            ↓
Describís tu idea  →  Claude arma el plan  →  Se detallan las pantallas
                       en Notion                una por una
                          ↓
                     Vos lo aprobás
                          ↓
                 🔨 Construcción (por pantalla)
                          ↓
              Claude construye → Vos revisás → Se guarda
                          ↓
                 Se repite por cada pantalla
                          ↓
                    ✅ Mockup listo
```

A continuación te explico cada paso con un ejemplo concreto.

---

## Ejemplo: Directorio del Equipo

Vamos a crear un mockup de un **directorio de empleados** — una pantalla donde se ve la lista del equipo con nombre, rol y área, y al hacer clic en alguien se abre un panel con más detalle.

### Paso 1 — Preparar el entorno (solo la primera vez)

Abrí Claude Desktop y escribí:

```
/setup-sandbox
```

Claude va a revisar tu máquina, instalar lo necesario, y pedirte el token de GitHub cuando lo necesite. Seguí las instrucciones que te vaya dando.

Cuando termine, vas a ver un mensaje como:

> ✅ Entorno listo. Ya podés crear tu primer proyecto.

**Esto se hace una sola vez.** No necesitás repetirlo para futuros proyectos.

---

### Paso 2 — Crear el proyecto

Escribí en Claude:

```
/bootstrap-react-project
```

Claude te va a preguntar:

> **¿Cómo querés llamar el proyecto?**

Respondé con un nombre corto, en minúsculas y sin espacios. Por ejemplo:

```
directorio-equipo
```

Claude también te va a preguntar si necesitás datos privados de Humand (usuarios, áreas). Si tu mockup usa datos internos, decí que sí. Si no, decí que no.

Claude va a crear el proyecto, descargar todo lo necesario, y avisarte cuando esté listo. Te va a dar instrucciones para verlo en el navegador:

> Para ver el proyecto en tu browser:
> 1. Abrí una terminal
> 2. Escribí exactamente esto y presioná Enter:
>    `cd /ruta/al/proyecto && bun dev`
> 3. Abrí http://localhost:5173 en tu navegador

---

### Paso 3 — Planificar en Notion

**Antes de construir nada, Claude arma un plan.** Esto es obligatorio — asegura que estemos alineados antes de escribir código.

Describile a Claude lo que querés:

```
Quiero un directorio de empleados. Tiene que tener:
- Una pantalla con la lista del equipo en una tabla (nombre, rol, área, email)
- Al hacer clic en alguien, se abre un panel lateral con más detalle
- Si no hay nadie cargado, se muestra un mensaje de "no hay empleados"
```

Claude va a:

1. Crear una **página en Notion** con el plan del proyecto
2. Armar un **diagrama de flujo** mostrando cómo se navegan las pantallas
3. Listar las **pantallas** que identificó
4. Pedirte que revises y apruebes

Vas a ver algo como:

> Creé la página del proyecto acá: [link a Notion]. Tiene el objetivo, los flujos y las pantallas.
>
> Estas son las pantallas que identifiqué:
> 1. **Empleados — Lista**: tabla con búsqueda y la lista del equipo
> 2. **Empleados — Detalle**: panel lateral con la info completa
>
> ¿Están todas, o falta alguna?

**Revisá el plan con calma.** Podés pedir cambios, agregar pantallas, o reordenar. Claude no va a construir nada hasta que des el OK.

---

### Paso 4 — Detallar cada pantalla

Una vez que aprobás el plan, Claude va a detallar cada pantalla antes de construirla. Esto se llama "refinar" y se hace pantalla por pantalla.

Claude te va a mostrar:

> La pantalla "Lista de empleados" tiene 2 partes que conviene construir por separado:
>
> 1. **Lista principal** — la tabla con nombre, rol, área y email, con barra de búsqueda. Se valida: al entrar se ve la tabla con datos.
> 2. **Empty state** — lo que se muestra cuando no hay empleados. Se valida: si borro los datos, se ve el mensaje de vacío.
>
> ¿Te parece este orden?

También te va a mostrar una vista previa de cómo se va a armar cada parte, usando los componentes del sistema de diseño de Humand. No necesitás entender el código — solo revisá que la descripción coincida con lo que tenés en mente.

---

### Paso 5 — Construir pantalla por pantalla

Ahora viene la parte divertida. Claude construye cada parte y te pide que la revises en el navegador.

> Agregué la tabla de empleados. La encontrás en el menú de la izquierda como "Empleados". ¿La podés revisar y decirme si se ve como lo planeamos?

**Abrí el navegador** (o refrescá si ya lo tenías abierto) y revisá:

- ¿Se ve la tabla con las columnas correctas?
- ¿Funciona la búsqueda?
- ¿El menú de la izquierda tiene la sección nueva?

Si algo no está bien, decíselo a Claude:

```
La tabla se ve bien pero le falta la columna de email
```

Claude lo ajusta y te pide que revises de nuevo. **No se avanza hasta que estés conforme.**

Cuando das el OK, Claude:
- Guarda un punto de guardado del proyecto
- Actualiza el plan en Notion marcando esa parte como lista
- Pasa a la siguiente parte

Este ciclo se repite para cada parte de cada pantalla.

---

### Paso 6 — Conectar un servicio externo (opcional)

Si querés que tu mockup muestre datos reales en vez de datos de ejemplo, podés conectar un servicio externo. Por ejemplo, Google Sheets, Supabase, HubSpot, etc.

Decile a Claude:

```
Quiero conectar una planilla de Google Sheets que tiene los datos del equipo
```

Claude te va a guiar:

1. Te pregunta qué operaciones necesitás (leer datos, escribir, o ambas)
2. Crea la conexión de forma segura (las credenciales nunca se exponen)
3. Te pide las credenciales del servicio y te explica dónde ponerlas
4. Te dice cómo usar los datos en tus pantallas

> **Importante:** Las credenciales se guardan solo en tu máquina y nunca se suben al proyecto. Claude se encarga de que esto sea seguro.

---

### Paso 7 — Limpiar el entorno (cuando termines)

Cuando ya no necesites el entorno de desarrollo, podés desinstalar todo lo que se instaló en el Paso 1:

```
/cleanup-sandbox
```

Claude te muestra qué va a desinstalar y qué no (las herramientas que ya tenías antes del setup no se tocan). Te pide confirmación antes de hacer nada.

---

## Resumen de comandos

Estos son todos los comandos que podés usar. Se escriben directamente en Claude Desktop.

| Comando | ¿Cuándo usarlo? | ¿Qué hace? |
|---|---|---|
| `/setup-sandbox` | Una sola vez, al principio | Prepara tu máquina con las herramientas necesarias |
| `/bootstrap-react-project` | Al iniciar un proyecto nuevo | Crea el proyecto y descarga todo |
| `/plan-project` | Después de crear el proyecto | Arma el plan en Notion con flujos y pantallas |
| `/refine-feature` | Antes de construir cada pantalla | Detalla los bloques de cada pantalla |
| `/build-feature` | Para cada bloque de cada pantalla | Construye, te pide revisar, y guarda |
| `/connect-service` | Cuando quieras datos reales | Conecta un servicio externo (Sheets, Supabase, etc.) |
| `/cleanup-sandbox` | Cuando ya no necesites el entorno | Desinstala las herramientas de forma segura |
| `/tsc-check` | Si Claude te dice que hay un error de tipos | Revisa errores de tipado en el proyecto |
| `/lint-fix` | Si Claude te dice que hay errores de formato | Corrige el formato del código automáticamente |

---

## Troubleshooting — Problemas comunes

### "No se ve nada en el navegador"

**Posible causa:** El servidor no está corriendo.

**Solución:**
1. Abrí una terminal
2. Escribí el comando que Claude te dio para iniciar el servidor (generalmente `cd /ruta/al/proyecto && bun dev`)
3. Esperá a ver el mensaje `Local: http://localhost:5173`
4. Abrí esa dirección en tu navegador

Si ya estaba corriendo, probá refrescar el navegador (Ctrl+R en Windows, Cmd+R en Mac).

---

### "Claude me dice que falta algo para empezar"

**Posible causa:** El entorno no está configurado.

**Solución:** Corré `/setup-sandbox` en Claude. Esto revisa y instala lo que falte.

---

### "El proyecto no se creó bien / faltan cosas"

**Posible causa:** El token de GitHub expiró o no está configurado.

**Solución:** Decile a Claude:

```
El proyecto no se creó bien, creo que el token de GitHub no funciona
```

Claude va a pedirte un token nuevo. Consultá con tu equipo de desarrollo para obtenerlo.

---

### "Claude no me deja construir sin planificar primero"

**Esto es por diseño.** El toolkit requiere que primero se arme un plan en Notion y se apruebe. Esto evita retrabajo y asegura que estemos alineados.

Si querés saltar directo a construir, primero respondé las preguntas del plan rápidamente. El plan puede ser simple — no necesita ser perfecto, pero sí existir.

---

### "La pantalla se ve en blanco o con un error"

**Solución:** Decile a Claude exactamente qué ves:

```
La pantalla de empleados se ve en blanco, no aparece la tabla
```

Claude va a diagnosticar el problema y corregirlo. No necesitás entender el error técnico — solo describí lo que ves (o lo que no ves).

---

### "Quiero cambiar algo de una pantalla que ya se construyó"

No hay problema. Decile a Claude qué querés cambiar:

```
En la tabla de empleados, quiero agregar una columna de "Fecha de ingreso"
```

Claude va a hacer el cambio, pedirte que revises, y guardar un nuevo punto.

---

### "Algo falló al instalar y no puedo seguir"

Si ves un error de permisos durante `/setup-sandbox`, Claude te va a dar un mensaje para enviarle a IT pidiendo los permisos necesarios. Copiale ese mensaje a tu equipo de IT y esperá a que te lo resuelvan.

Si es otro tipo de error, describíselo a Claude — generalmente puede diagnosticarlo y resolverlo solo.

---

### "¿Puedo trabajar en el mismo proyecto en otra sesión?"

Sí. Abrí Claude Desktop y abrí el proyecto. Claude va a leer el último punto de guardado y retomar donde quedaste. Decile algo como:

```
Quiero seguir trabajando en el directorio de equipo
```

Claude va a revisar el estado del proyecto y decirte en qué quedaron.

---

### "¿Puedo deshacer todo lo que se instaló?"

Sí. Corré `/cleanup-sandbox` en Claude. Solo se desinstala lo que el toolkit instaló — si ya tenías alguna herramienta antes, no se toca.

---

## Glosario

| Término | ¿Qué significa? |
|---|---|
| **Sandbox** | Un proyecto de prueba aislado — no afecta nada en producción |
| **Mockup funcional** | Un prototipo que se ve y se navega como una app real, pero con datos de ejemplo |
| **Pantalla** | Una vista completa de la app (por ejemplo: "la lista de empleados") |
| **Feature / Funcionalidad** | Una parte independiente de una pantalla (por ejemplo: "la tabla" o "el panel de detalle") |
| **Punto de guardado** | Una foto del estado del proyecto en un momento — se puede volver atrás si algo sale mal |
| **Notion** | La herramienta donde se documenta el plan y se sigue el progreso |
| **Claude Desktop** | La app donde trabajás — le escribís lo que necesitás y Claude lo construye |
| **Servidor local** | Tu proyecto corriendo en tu propia máquina, visible en el navegador |
| **Token** | Una clave que permite acceder a los componentes de diseño de Humand |

---

## Preguntas frecuentes

**¿Necesito saber programar?**
No. El toolkit está diseñado para que puedas describir lo que necesitás en lenguaje natural. Claude se encarga de todo lo técnico.

**¿Puedo romper algo?**
No. Los sandboxes son proyectos aislados — no están conectados a producción ni afectan a otros sistemas. Además, tenés puntos de guardado para volver atrás.

**¿Otras personas pueden ver mi mockup?**
Sí, una vez que el proyecto esté listo se puede publicar con un link compartible para que otros lo vean en su navegador.

**¿Cuánto tarda hacer un mockup?**
Depende de la complejidad, pero un mockup simple (2-3 pantallas) se puede tener listo en una sesión de trabajo.

**¿Puedo agregar más pantallas después?**
Sí. Podés volver al proyecto en cualquier momento y agregar pantallas nuevas siguiendo el mismo flujo: planificar → detallar → construir.

**¿Los datos son reales?**
Por defecto, los datos son de ejemplo. Pero podés conectar servicios reales (como Google Sheets o una base de datos) usando `/connect-service`.

**¿Qué pasa si cierro Claude a mitad de camino?**
No se pierde nada. Al volver a abrir, Claude retoma desde el último punto de guardado.
