Espacios y Áreas de Trabajo

Aprende cómo trabajar con entornos aislados para ejecución de agentes en TeamDay.

Tabla de Contenidos

¿Qué son los Espacios?

Los espacios son áreas de trabajo aisladas donde los agentes pueden:

  • Leer y escribir archivos
  • Ejecutar código y comandos
  • Confirmar cambios en Git
  • Persistir datos entre sesiones
  • Colaborar con otros agentes

Cada espacio proporciona:

  • Aislamiento - Sistema de archivos separado por espacio
  • Persistencia - Los archivos sobreviven entre ejecuciones
  • Sincronización S3 - Copia de seguridad automática a almacenamiento en la nube
  • Integración con Git - Control de versiones completo
  • Control de Acceso - Visibilidad y permisos
  • Asignación de Agentes - Agentes dedicados por espacio

Casos de Uso:

  • Proyectos de Desarrollo - Repositorios de código con Git
  • Análisis de Datos - Conjuntos de datos persistentes y scripts
  • Creación de Contenido - Documentos de borrador e iteración
  • Automatización - Almacena scripts y configuraciones
  • Colaboración - Múltiples agentes trabajando juntos

Crear Espacios

Vía UI

Paso 1: Navega a la página de Espacios

Paso 2: Haz clic en "+ Nuevo Espacio"

Paso 3: Configura el Espacio

Configuración Básica:

  • Nombre (Requerido)
    • 1-100 caracteres
    • Descriptivo y específico
    • Ejemplo: "Proyecto de API de Cliente", "Contenido de Marketing"
  • Descripción (Opcional)
    • Qué es para este espacio
    • Contexto clave para agentes
    • Ejemplo: "API de backend para sistema de gestión de clientes"
  • Visibilidad
    • privado - Solo tú
    • organización - Todos los miembros de org
    • público - Cualquiera con enlace

Tipo de Inicialización:

  1. Área de Trabajo Vacía - Comienza fresco
    • Crea directorio vacío
    • Inicializa repositorio Git
    • Añade instrucciones CLAUDE.md predeterminadas
  2. Repositorio Git - Clona repo existente
    • Ingresa URL de Git (HTTPS o SSH)
    • Opcionalmente especifica rama
    • Ejemplo: https://github.com/user/repo.git
  3. Kit de Iniciación - Usa plantilla
    • Elige entre: Nuxt, Next.js, Vue, React
    • Preconfigurado con mejores prácticas
    • Incluye instrucciones CLAUDE.md

Paso 4: Haz clic en "Crear Espacio"

La inicialización ocurre en segundo plano. Actualizaciones de estado:

  • pendiente → inicializando → listo
  • Progreso mostrado en UI
  • Generalmente toma 10-30 segundos

Paso 5: Abre Espacio

Una vez listo, haz clic en "Abrir" para ver archivos o "Chat" para interactuar con agentes en este espacio.

Vía CLI

# Crear espacio vacío
teamday spaces create \
  --name "Mi Proyecto" \
  --description "Desarrollo de API de Backend" \
  --visibility organization \
  --type empty

# Clonar desde Git
teamday spaces create \
  --name "Repo Existente" \
  --type git \
  --git-url "https://github.com/user/repo.git" \
  --git-branch "main"

# Usar kit de iniciación
teamday spaces create \
  --name "Nueva Aplicación Nuxt" \
  --type starterKit \
  --kit nuxt

Kits disponibles: nuxt, nextjs, vue, react, express, fastify

Estructura del Área de Trabajo

Cada espacio tiene un sistema de archivos aislado:

/data/sandbox/{orgId}/spaces/s-{spaceId}/
├── CLAUDE.md                    # Instrucciones del agente (auto-generado)
├── .git/                        # Repositorio Git
├── .gitignore                   # Ignorados estándar
├── ...tus archivos...

Archivo CLAUDE.md

Instrucciones auto-generadas para agentes que trabajan en este espacio:

# Proyecto: {Nombre del Espacio}

{Descripción}

## Contexto

Este es un área de trabajo de TeamDay para: {propósito}

Organización: {org-name}
ID de Espacio: s-{id}
Creado: {date}

## Directrices

Al trabajar en este espacio:
- Sigue patrones de código existentes
- Escribe mensajes de confirmación claros
- Prueba antes de confirmar
- Documenta cambios significativos

## Archivos

[Agente: Usa la herramienta de `filesystem` para explorar archivos]

## Comandos

[Comandos comunes para este tipo de proyecto]

Puedes editar CLAUDE.md para añadir:

  • Instrucciones específicas del proyecto
  • Estándares de código
  • Notas de arquitectura
  • Tareas comunes
  • Enlaces a documentación

Límites del Sistema de Archivos

  • Tamaño total: 10 GB por espacio
  • Recuento de archivos: Ilimitado (uso razonable)
  • Tamaño de archivo: 100 MB máximo de carga
  • Sincronización: Automática cada 5 minutos + en cambios

Operaciones de Archivos

Los agentes pueden realizar operaciones de archivos usando el servicio Computer.

Leer Archivos

Ver Archivo:

Agente: Muéstrame el contenido de src/api/users.ts

[El agente usa la herramienta de sistema de archivos para leer archivo]

Listar Directorio:

Agente: ¿Qué archivos hay en el directorio src/?

[El agente lista contenidos del directorio]

Buscar Archivos:

Agente: Encuentra todos los archivos que contienen "TODO"

[El agente usa la herramienta ripgrep]

Escribir Archivos

Crear Archivo Nuevo:

Agente: Crea un nuevo archivo src/utils/helpers.ts con funciones de utilidad

[El agente escribe archivo]

Editar Archivo Existente:

Agente: Actualiza src/api/users.ts para añadir validación de entrada

[El agente hace ediciones dirigidas]

Reemplazar Contenido:

Agente: Reemplaza la función getUserById con esta nueva implementación:
[código]

[El agente realiza reemplazo de cadena]

Carga de Archivos

Carga archivos desde tu máquina local:

Vía UI:

  1. Abre espacio
  2. Haz clic en "Cargar Archivos"
  3. Selecciona hasta 20 archivos (100MB cada uno)
  4. Los archivos aparecen en raíz del área de trabajo (o directorio especificado)

Vía CLI:

teamday spaces upload s-space123 \
  --files data.csv,config.json \
  --dest /data/

Descargar Archivos

Descarga archivos del área de trabajo:

Vía UI:

  1. Abre navegador de archivos del espacio
  2. Click derecho en archivo → Descargar
  3. O selecciona múltiples → Descargar como ZIP

Vía CLI:

# Descargar archivo único
teamday spaces download s-space123 --file src/app.ts

# Descargar área de trabajo completa
teamday spaces download s-space123 --all --format zip

Integración con Git

Cada espacio es un repositorio Git.

Inicialización Automática

Al crear un espacio:

git init
git config user.name "TeamDay Agent"
git config user.email "[email protected]"
git add CLAUDE.md
git commit -m "Initialize TeamDay workspace"

Operaciones Git de Agentes

Los agentes pueden usar Git a través de comandos:

Agente: Verifica el estado de git

[El agente ejecuta: git status]

Agente: Confirma estos cambios con mensaje "Añadir validación de usuario"

[El agente ejecuta: git add . && git commit -m "Add user validation"]

Agente: Muestra historial de confirmaciones reciente

[El agente ejecuta: git log --oneline -10]

Ver Historial de Git

Vía UI:

  1. Abre espacio
  2. Haz clic en la pestaña "Historial"
  3. Ve confirmaciones, ramas, diffs

Vía CLI:

teamday spaces git s-space123 log
teamday spaces git s-space123 diff HEAD~1
teamday spaces git s-space123 show abc123

Ramificación

Crea y cambia de rama:

# Vía agente
"Create a new branch called 'feature/add-auth'"

# Vía CLI
teamday spaces git s-space123 checkout -b feature/add-auth

Repositorios Remotos

Conecta a GitHub, GitLab, etc:

Paso 1: Añade remoto

# Vía agente
"Add Git remote: git remote add origin https://github.com/user/repo.git"

# Vía CLI
teamday spaces git s-space123 remote add origin https://github.com/user/repo.git

Paso 2: Empuja cambios

# Vía agente (requiere GitHub PAT en configuración del espacio)
"Push to origin main"

# Vía CLI
teamday spaces git s-space123 push origin main

Autenticación: Para repos privados, añade credenciales:

teamday spaces config s-space123 \
  --set GIT_USERNAME=user \
  --set GIT_TOKEN=ghp_xxxxx

Sincronización S3

Los espacios de trabajo se sincronizan automáticamente con S3 para durabilidad y compartir.

Cómo Funciona

Sincronización Local a S3:

  1. El agente modifica archivos en el área de trabajo
  2. Los cambios se detectan por observador de archivos
  3. Los archivos modificados se cargan a S3
  4. La sincronización ocurre cada 5 minutos + inmediatamente al cerrar archivo

Sincronización S3 a Local (Carga Perezosa):

  1. El agente solicita archivo que no existe localmente
  2. El servicio Computer verifica S3
  3. El archivo se descarga si está disponible
  4. Las lecturas posteriores son locales (rápido)

Estructura del Bucket S3

s3://teamday-workspaces/
└── {orgId}/
    └── spaces/
        └── s-{spaceId}/
            ├── CLAUDE.md
            ├── src/
            │   └── app.ts
            └── ...

Sincronización Manual

Fuerza sincronización inmediata:

Carga a S3:

teamday spaces sync s-space123 --direction up

Descarga desde S3:

teamday spaces sync s-space123 --direction down

Bi-direccional:

teamday spaces sync s-space123

Estado de Sincronización

Verifica estado de sincronización:

teamday spaces sync-status s-space123

Salida:

{
  "spaceId": "s-space123",
  "lastSync": "2025-01-15T10:30:00Z",
  "pendingChanges": 3,
  "syncEnabled": true,
  "s3Bucket": "teamday-workspaces",
  "s3Prefix": "org-xyz/spaces/s-space123/"
}

Desabilitar Sincronización

Para espacios solo locales (pruebas):

teamday spaces config s-space123 --set SYNC_ENABLED=false

O vía variable de entorno al ejecutar servicio Computer:

SYNC_VOLUMES_TO_S3=false bun run dev

Compartir Espacios

Niveles de Visibilidad

Privado:

  • Solo el propietario del espacio puede acceder
  • Los agentes deben ser asignados explícitamente

Organización:

  • Todos los miembros de org pueden acceder
  • Cualquier agente de org puede ser utilizado

Público:

  • Cualquiera con enlace puede ver (solo lectura)
  • La ejecución requiere membresía de org

Asignar Agentes

Otorga acceso específico a agentes a un espacio:

Vía UI:

  1. Abre configuración del espacio
  2. Ve a la pestaña "Agentes"
  3. Haz clic en "Asignar Agente"
  4. Selecciona agente(s) de lista
  5. Guarda

Vía CLI:

teamday spaces assign s-space123 --agent char_abc123

Los agentes asignados:

  • Pueden leer/escribir archivos en el espacio
  • Ven contexto del espacio en ejecuciones
  • Reciben instrucciones específicas del espacio desde CLAUDE.md

Espacios Colaborativos

Múltiples usuarios/agentes trabajando juntos:

Configuración:

  1. Crea espacio a nivel de organización
  2. Asigna agentes especialistas (Backend, Frontend, QA)
  3. Añade instrucciones del proyecto a CLAUDE.md
  4. Los miembros del equipo ejecutan agentes en el espacio

Ejemplo de Flujo de Trabajo:

# PM crea espacio y tareas
teamday spaces create --name "Proyecto de API" --visibility org
teamday agents exec char_pm "Break down the API project into tasks" --space s-api

# Agente de ingeniero backend trabaja en implementación
teamday agents exec char_backend "Implement user endpoints" --space s-api

# Agente de QA revisa y prueba
teamday agents exec char_qa "Test the user endpoints" --space s-api

# Todo el trabajo ocurre en el mismo área de trabajo

Control de Acceso

Permisos granulares (solo UI, vía configuración del espacio):

  • Visor - Solo lectura de archivos
  • Editor - Lectura/escritura de archivos
  • Admin - Control completo + configuración

Mejores Prácticas

1. Usa Nombres Descriptivos

✅ Bueno:
- "API de Backend de Cliente"
- "Contenido del Sitio Web de Marketing"
- "Análisis de Datos Q4"

❌ Malo:
- "Proyecto 1"
- "Prueba"
- "Cosas"

2. Añade Instrucciones Claras

Edita CLAUDE.md con contexto del proyecto:

# Proyecto de API de Cliente

API de backend para sistema de gestión de clientes.

## Stack de Tecnología
- Node.js + Express
- Base de datos PostgreSQL
- Autenticación JWT

## Estándares
- Sigue convenciones RESTful
- Escribe pruebas para todos los endpoints
- Usa JSDoc para funciones
- Longitud máxima de función: 50 líneas

## Tareas Comunes

### Ejecutar Pruebas
```bash
bun test

Iniciar Servidor de Desarrollo

bun run dev

Migración de Base de Datos

bun run migrate


### 3. Organiza Archivos

Usa estructura estándar del proyecto:

project-space/ ├── CLAUDE.md # Instrucciones ├── README.md # Vista general del proyecto ├── package.json # Dependencias ├── src/ # Código fuente │ ├── api/ # Rutas de API │ ├── services/ # Lógica de negocio │ ├── utils/ # Utilidades │ └── types/ # Tipos de TypeScript ├── tests/ # Archivos de prueba ├── docs/ # Documentación └── .github/ # Configuraciones CI/CD


### 4. Confirma Frecuentemente

Guía a los agentes a hacer confirmaciones pequeñas y enfocadas:

"After implementing each endpoint, commit with a clear message"


En lugar de:

"Implement all endpoints then commit at the end"


### 5. Usa Ramas para Características

"Create a new branch 'feature/add-auth' for the authentication work"


Beneficios:
- Experimentación segura
- Reversión fácil
- Aislamiento claro de características

### 6. Limpia Regularmente

Elimina archivos no utilizados y ramas obsoletas:

```bash
# Vía agente
"Delete unused files in /tmp and stale git branches"

# Vía CLI
teamday spaces git s-space123 branch -d old-feature

7. Monitorea el Tamaño del Espacio

Mantén espacios bajo 1GB para rendimiento óptimo:

# Verifica tamaño del espacio
teamday spaces info s-space123 | grep size

Archivos grandes a evitar:

  • node_modules (usa .gitignore)
  • Artefactos de compilación (.next, dist, build)
  • Conjuntos de datos grandes (usa almacenamiento externo)
  • Archivos binarios (imágenes, videos)

8. Respalda Trabajo Importante

Si bien la sincronización S3 proporciona respaldo, también:

Opción 1: Empuja a Git Remoto

teamday spaces git s-space123 push origin main

Opción 2: Descarga Instantáneas

teamday spaces download s-space123 --all --output backup-$(date +%Y%m%d).zip

Opción 3: Copias de Seguridad Automatizadas

#!/bin/bash
# daily-backup.sh

for space in $(teamday spaces list --format json | jq -r '.[].id'); do
  teamday spaces download $space \
    --all \
    --output "backups/${space}-$(date +%Y%m%d).zip"
done

9. Configura .gitignore

Siempre ignora:

# .gitignore

# Dependencias
node_modules/
vendor/

# Salida de compilación
dist/
build/
.next/
out/

# Entorno
.env
.env.local

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

10. Usa Espacios para Aislamiento

Crea espacios separados para:

  • Desarrollo - Trabajo activo
  • Staging - Pruebas pre-producción
  • Producción - Implementaciones en vivo (solo lectura)
  • Experimentos - Probando nuevos enfoques

Solución de Problemas

Espacio Atrapado en "Inicializando"

Síntomas: El estado del espacio nunca alcanza "listo"

Soluciones:

# Verifica registros de inicialización
teamday spaces logs s-space123 --tail 50

# Cancela y recrea
teamday spaces delete s-space123
teamday spaces create --name "Mi Espacio" --type empty

Archivos No Se Sincronizan a S3

Síntomas: Los cambios no aparecen en S3

Verifica:

# Verifica que la sincronización esté habilitada
teamday spaces config s-space123 --get SYNC_ENABLED

# Fuerza sincronización
teamday spaces sync s-space123 --direction up

# Verifica registros de sincronización
teamday spaces logs s-space123 --grep sync

Conflictos de Git

Síntomas: Las operaciones de Git fallan con errores de conflicto

Soluciones:

# Vía agente
"Show git status and resolve conflicts in [file]"

# O reinicia a último buen estado
teamday spaces git s-space123 reset --hard HEAD

Errores de Permiso Denegado

Síntomas: El agente no puede acceder a archivos del espacio

Verifica:

  1. Verifica que el agente sea asignado al espacio
  2. Verifica visibilidad del espacio
  3. Verifica membresía de org
teamday spaces info s-space123 | grep -E 'visibility|assignedAgents'

Próximos Pasos