Spaces & Espaces de travail

Apprenez à travailler avec des environnements isolés pour l'exécution d'agents dans TeamDay.

Table des matières

Que sont les Spaces ?

Les Spaces sont des espaces de travail isolés où les agents peuvent :

  • Lire et écrire des fichiers
  • Exécuter du code et des commandes
  • Commiter des changements dans Git
  • Persister des données entre les sessions
  • Collaborer avec d'autres agents

Chaque space fournit :

  • Isolation - Système de fichiers séparé par space
  • Persistance - Les fichiers survivent entre les exécutions
  • Synchro S3 - Sauvegarde automatique vers le stockage cloud
  • Intégration Git - Contrôle de version complet
  • Contrôle d'accès - Visibilité et permissions
  • Assignation d'agents - Agents dédiés par space

Cas d'usage :

  • Projets de développement - Dépôts de code avec Git
  • Analyse de données - Jeux de données et scripts persistants
  • Création de contenu - Brouillons de documents et itération
  • Automatisation - Stocker scripts et configurations
  • Collaboration - Plusieurs agents travaillant ensemble

Créer des Spaces

Via l'interface

Étape 1 : Accéder à la page Spaces

Étape 2 : Cliquer sur "+ New Space"

Étape 3 : Configurer le Space

Paramètres de base :

  • Nom (Requis)
    • 1-100 caractères
    • Descriptif et spécifique
    • Exemple : "Projet API Client", "Contenu Marketing"
  • Description (Optionnel)
    • À quoi sert ce space
    • Contexte clé pour les agents
    • Exemple : "API backend pour système de gestion client"
  • Visibilité
    • private - Seulement vous
    • organization - Tous les membres de l'org
    • public - Quiconque avec le lien

Type d'initialisation :

  1. Espace de travail vide - Commencer de zéro
    • Crée un répertoire vide
    • Initialise un dépôt Git
    • Ajoute les instructions CLAUDE.md par défaut
  2. Dépôt Git - Cloner un dépôt existant
    • Entrer l'URL Git (HTTPS ou SSH)
    • Optionnellement spécifier la branche
    • Exemple : https://github.com/user/repo.git
  3. Starter Kit - Utiliser un modèle
    • Choisir parmi : Nuxt, Next.js, Vue, React
    • Pré-configuré avec bonnes pratiques
    • Inclut les instructions CLAUDE.md

Étape 4 : Cliquer sur "Create Space"

L'initialisation se fait en arrière-plan. Mises à jour du statut :

  • pending → initializing → ready
  • Progression affichée dans l'interface
  • Prend généralement 10-30 secondes

Étape 5 : Ouvrir le Space

Une fois prêt, cliquez sur "Open" pour voir les fichiers ou "Chat" pour interagir avec les agents dans ce space.

Via CLI

# Créer un space vide
teamday spaces create \
  --name "Mon projet" \
  --description "Développement API backend" \
  --visibility organization \
  --type empty

# Cloner depuis Git
teamday spaces create \
  --name "Dépôt existant" \
  --type git \
  --git-url "https://github.com/user/repo.git" \
  --git-branch "main"

# Utiliser un starter kit
teamday spaces create \
  --name "Nouvelle app Nuxt" \
  --type starterKit \
  --kit nuxt

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

Structure de l'espace de travail

Chaque space a un système de fichiers isolé :

/data/sandbox/{orgId}/spaces/s-{spaceId}/
├── CLAUDE.md                    # Instructions pour l'agent (auto-généré)
├── .git/                        # Dépôt Git
├── .gitignore                   # Ignores standards
├── ...vos fichiers...

Fichier CLAUDE.md

Instructions auto-générées pour les agents travaillant dans ce space :

# Projet : {Nom du Space}

{Description}

## Contexte

Ceci est un espace de travail TeamDay pour : {objectif}

Organisation : {nom-org}
ID du Space : s-{id}
Créé : {date}

## Directives

Lors du travail dans ce space :
- Suivre les modèles de code existants
- Écrire des messages de commit clairs
- Tester avant de commiter
- Documenter les changements significatifs

## Fichiers

[Agent : Utilisez l'outil `filesystem` pour explorer les fichiers]

## Commandes

[Commandes courantes pour ce type de projet]

Vous pouvez éditer CLAUDE.md pour ajouter :

  • Instructions spécifiques au projet
  • Normes de codage
  • Notes d'architecture
  • Tâches courantes
  • Liens vers la documentation

Limites du système de fichiers

  • Taille totale : 10 GB par space
  • Nombre de fichiers : Illimité (usage raisonnable)
  • Taille de fichier : 100 MB par téléchargement de fichier
  • Synchro : Automatique toutes les 5 minutes + sur changements

Opérations de fichiers

Les agents peuvent effectuer des opérations de fichiers en utilisant le service Computer.

Lire des fichiers

Voir un fichier :

Agent : Montre-moi le contenu de src/api/users.ts

[L'agent utilise l'outil filesystem pour lire le fichier]

Lister un répertoire :

Agent : Quels fichiers sont dans le répertoire src/ ?

[L'agent liste le contenu du répertoire]

Chercher des fichiers :

Agent : Trouver tous les fichiers contenant "TODO"

[L'agent utilise l'outil ripgrep]

Écrire des fichiers

Créer un nouveau fichier :

Agent : Créer un nouveau fichier src/utils/helpers.ts avec des fonctions utilitaires

[L'agent écrit le fichier]

Éditer un fichier existant :

Agent : Mettre à jour src/api/users.ts pour ajouter la validation des entrées

[L'agent fait des modifications ciblées]

Remplacer du contenu :

Agent : Remplacer la fonction getUserById par cette nouvelle implémentation :
[code]

[L'agent effectue le remplacement de chaîne]

Téléchargement de fichiers

Télécharger des fichiers depuis votre machine locale :

Via l'interface :

  1. Ouvrir le space
  2. Cliquer sur "Upload Files"
  3. Sélectionner jusqu'à 20 fichiers (100MB chacun)
  4. Les fichiers apparaissent à la racine de l'espace (ou répertoire spécifié)

Via CLI :

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

Téléchargement de fichiers

Télécharger les fichiers de l'espace de travail :

Via l'interface :

  1. Ouvrir l'explorateur de fichiers du space
  2. Clic droit sur le fichier → Download
  3. Ou sélectionner plusieurs → Download as ZIP

Via CLI :

# Télécharger un seul fichier
teamday spaces download s-space123 --file src/app.ts

# Télécharger l'espace de travail entier
teamday spaces download s-space123 --all --format zip

Intégration Git

Chaque space est un dépôt Git.

Initialisation automatique

Lors de la création d'un space :

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

Opérations Git de l'agent

Les agents peuvent utiliser Git via des commandes :

Agent : Vérifier le statut git

[Agent exécute : git status]

Agent : Commiter ces changements avec le message "Add user validation"

[Agent exécute : git add . && git commit -m "Add user validation"]

Agent : Afficher l'historique récent des commits

[Agent exécute : git log --oneline -10]

Consulter l'historique Git

Via l'interface :

  1. Ouvrir le space
  2. Cliquer sur l'onglet "History"
  3. Voir les commits, branches, diffs

Via CLI :

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

Branches

Créer et basculer entre branches :

# Via l'agent
"Créer une nouvelle branche appelée 'feature/add-auth'"

# Via CLI
teamday spaces git s-space123 checkout -b feature/add-auth

Dépôts distants

Se connecter à GitHub, GitLab, etc :

Étape 1 : Ajouter un dépôt distant

# Via l'agent
"Ajouter le dépôt distant Git : git remote add origin https://github.com/user/repo.git"

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

Étape 2 : Pousser les changements

# Via l'agent (nécessite un PAT GitHub dans la config du space)
"Push vers origin main"

# Via CLI
teamday spaces git s-space123 push origin main

Authentification : Pour les dépôts privés, ajouter les identifiants :

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

Synchronisation S3

Les espaces de travail se synchronisent automatiquement vers S3 pour la durabilité et le partage.

Comment ça marche

Synchro local vers S3 :

  1. L'agent modifie des fichiers dans l'espace de travail
  2. Changements détectés par le surveillant de fichiers
  3. Fichiers modifiés téléchargés vers S3
  4. Synchro toutes les 5 minutes + immédiatement à la fermeture du fichier

Synchro S3 vers local (Chargement paresseux) :

  1. L'agent demande un fichier qui n'existe pas localement
  2. Le service Computer vérifie S3
  3. Fichier téléchargé si disponible
  4. Les lectures suivantes sont locales (rapides)

Structure du bucket S3

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

Synchro manuelle

Forcer une synchronisation immédiate :

Télécharger vers S3 :

teamday spaces sync s-space123 --direction up

Télécharger depuis S3 :

teamday spaces sync s-space123 --direction down

Bi-directionnel :

teamday spaces sync s-space123

Statut de synchro

Vérifier le statut de synchro :

teamday spaces sync-status s-space123

Sortie :

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

Désactiver la synchro

Pour des espaces de travail locaux uniquement (tests) :

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

Ou via variable d'environnement lors de l'exécution du service Computer :

SYNC_VOLUMES_TO_S3=false bun run dev

Partager des Spaces

Niveaux de visibilité

Privé :

  • Seul le propriétaire du space peut accéder
  • Les agents doivent être explicitement assignés

Organisation :

  • Tous les membres de l'org peuvent accéder
  • N'importe quel agent de l'org peut être utilisé

Public :

  • Quiconque avec le lien peut voir (lecture seule)
  • L'exécution nécessite l'adhésion à l'org

Assigner des agents

Donner l'accès à des agents spécifiques à un space :

Via l'interface :

  1. Ouvrir les paramètres du space
  2. Aller dans l'onglet "Agents"
  3. Cliquer sur "Assign Agent"
  4. Sélectionner le(s) agent(s) de la liste
  5. Sauvegarder

Via CLI :

teamday spaces assign s-space123 --agent char_abc123

Les agents assignés :

  • Peuvent lire/écrire des fichiers dans le space
  • Voient le contexte du space dans les exécutions
  • Reçoivent les instructions spécifiques au space depuis CLAUDE.md

Spaces collaboratifs

Plusieurs utilisateurs/agents travaillant ensemble :

Configuration :

  1. Créer un space au niveau de l'organisation
  2. Assigner des agents spécialistes (Backend, Frontend, QA)
  3. Ajouter des instructions de projet à CLAUDE.md
  4. Les membres de l'équipe exécutent des agents dans le space

Exemple de flux de travail :

# PM crée le space et les tâches
teamday spaces create --name "Projet API" --visibility org
teamday agents exec char_pm "Décomposer le projet API en tâches" --space s-api

# L'agent ingénieur backend travaille sur l'implémentation
teamday agents exec char_backend "Implémenter les endpoints utilisateur" --space s-api

# L'agent QA examine et teste
teamday agents exec char_qa "Tester les endpoints utilisateur" --space s-api

# Tout le travail se fait dans le même espace de travail

Contrôle d'accès

Permissions granulaires (interface uniquement, via paramètres du space) :

  • Viewer - Lire les fichiers uniquement
  • Editor - Lire/écrire les fichiers
  • Admin - Contrôle complet + paramètres

Bonnes pratiques

1. Utiliser des noms descriptifs

✅ Bien :
- "API Backend Client"
- "Contenu Site Marketing"
- "Analyse Données Q4"

❌ Mal :
- "Projet 1"
- "Test"
- "Trucs"

2. Ajouter des instructions claires

Éditer CLAUDE.md avec le contexte du projet :

# Projet API Client

API backend pour système de gestion client.

## Stack technique
- Node.js + Express
- Base de données PostgreSQL
- Authentification JWT

## Normes
- Suivre les conventions RESTful
- Écrire des tests pour tous les endpoints
- Utiliser JSDoc pour les fonctions
- Longueur max de fonction : 50 lignes

## Tâches courantes

### Exécuter les tests
```bash
bun test

Démarrer le serveur dev

bun run dev

Migration base de données

bun run migrate


### 3. Organiser les fichiers

Utiliser une structure de projet standard :

project-space/ ├── CLAUDE.md # Instructions ├── README.md # Aperçu du projet ├── package.json # Dépendances ├── src/ # Code source │ ├── api/ # Routes API │ ├── services/ # Logique métier │ ├── utils/ # Utilitaires │ └── types/ # Types TypeScript ├── tests/ # Fichiers de test ├── docs/ # Documentation └── .github/ # Configs CI/CD


### 4. Commiter fréquemment

Guider les agents pour faire de petits commits focalisés :

"Après avoir implémenté chaque endpoint, commiter avec un message clair"


Plutôt que :

"Implémenter tous les endpoints puis commiter à la fin"


### 5. Utiliser les branches pour les fonctionnalités

"Créer une nouvelle branche 'feature/add-auth' pour le travail d'authentification"


Avantages :
- Expérimentation sûre
- Retour en arrière facile
- Isolation claire des fonctionnalités

### 6. Nettoyer régulièrement

Supprimer les fichiers et branches non utilisés :

```bash
# Via l'agent
"Supprimer les fichiers inutilisés dans /tmp et les branches git obsolètes"

# Via CLI
teamday spaces git s-space123 branch -d old-feature

7. Surveiller la taille du Space

Garder les spaces sous 1GB pour des performances optimales :

# Vérifier la taille du space
teamday spaces info s-space123 | grep size

Gros fichiers à éviter :

  • node_modules (utiliser .gitignore)
  • Artefacts de compilation (.next, dist, build)
  • Grands jeux de données (utiliser stockage externe)
  • Fichiers binaires (images, vidéos)

8. Sauvegarder le travail important

Bien que la synchro S3 fournisse une sauvegarde, également :

Option 1 : Push vers dépôt distant Git

teamday spaces git s-space123 push origin main

Option 2 : Télécharger des snapshots

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

Option 3 : Sauvegardes automatisées

#!/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. Configurer .gitignore

Toujours ignorer :

# .gitignore

# Dépendances
node_modules/
vendor/

# Sorties de compilation
dist/
build/
.next/
out/

# Environnement
.env
.env.local

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

10. Utiliser les Spaces pour l'isolation

Créer des spaces séparés pour :

  • Développement - Travail actif
  • Staging - Tests pré-production
  • Production - Déploiements en direct (lecture seule)
  • Expérimentations - Essayer de nouvelles approches

Dépannage

Space bloqué en "Initializing"

Symptômes : Le statut du space n'atteint jamais "ready"

Solutions :

# Vérifier les logs d'initialisation
teamday spaces logs s-space123 --tail 50

# Annuler et recréer
teamday spaces delete s-space123
teamday spaces create --name "Mon Space" --type empty

Fichiers non synchronisés vers S3

Symptômes : Les changements n'apparaissent pas dans S3

Vérifier :

# Vérifier que la synchro est activée
teamday spaces config s-space123 --get SYNC_ENABLED

# Forcer la synchro
teamday spaces sync s-space123 --direction up

# Vérifier les logs de synchro
teamday spaces logs s-space123 --grep sync

Conflits Git

Symptômes : Les opérations Git échouent avec des erreurs de conflit

Solutions :

# Via l'agent
"Afficher le statut git et résoudre les conflits dans [fichier]"

# Ou réinitialiser au dernier bon état
teamday spaces git s-space123 reset --hard HEAD

Erreurs Permission Denied

Symptômes : L'agent ne peut pas accéder aux fichiers du space

Vérifier :

  1. Vérifier que l'agent est assigné au space
  2. Vérifier la visibilité du space
  3. Vérifier l'adhésion à l'org
teamday spaces info s-space123 | grep -E 'visibility|assignedAgents'

Prochaines étapes