Spaces & Workspaces

Erfahren Sie, wie Sie mit isolierten Umgebungen für Agent-Ausführung in TeamDay arbeiten.

Inhaltsverzeichnis

Was sind Spaces?

Spaces sind isolierte Workspaces, in denen Agenten:

  • Dateien lesen und schreiben können
  • Code und Befehle ausführen können
  • Änderungen in Git commiten können
  • Daten über Sitzungen hinweg persistieren können
  • Mit anderen Agenten zusammenarbeiten können

Jeder Space bietet:

  • Isolation - Separates Dateisystem pro Space
  • Persistenz - Dateien überleben über Ausführungen hinweg
  • S3 Sync - Automatische Sicherung zum Cloud-Storage
  • Git-Integration - Vollständige Versionskontrolle
  • Zugriffskontrolle - Sichtbarkeit und Berechtigungen
  • Agent-Zuweisung - Dedizierte Agenten pro Space

Anwendungsfälle:

  • Entwicklungsprojekte - Code-Repositories mit Git
  • Datenanalyse - Persistente Datensätze und Skripte
  • Content Creation - Entwurfsdokumente und Iteration
  • Automatisierung - Speicherung von Skripten und Konfigurationen
  • Zusammenarbeit - Mehrere Agenten arbeiten zusammen

Spaces erstellen

Über Benutzeroberfläche

Schritt 1: Navigieren Sie zur Spaces-Seite

Schritt 2: Klicken Sie auf "+ Neuer Space"

Schritt 3: Konfigurieren Sie Space

Grundeinstellungen:

  • Name (Erforderlich)
    • 1-100 Zeichen
    • Aussagekräftig und spezifisch
    • Beispiel: "Customer API Project", "Marketing Content"
  • Beschreibung (Optional)
    • Wofür dieser Space ist
    • Wichtiger Kontext für Agenten
    • Beispiel: "Backend API für das Kundenverwaltungssystem"
  • Sichtbarkeit
    • private - Nur Sie
    • organization - Alle Org-Mitglieder
    • public - Jeder mit Link

Initialisierungstyp:

  1. Leerer Workspace - Frisch beginnen
    • Erstellt leeres Verzeichnis
    • Initialisiert Git-Repository
    • Fügt Standard-CLAUDE.md Anweisungen hinzu
  2. Git Repository - Bestehendes Repo klonen
    • Geben Sie Git-URL ein (HTTPS oder SSH)
    • Optional Branches spezifizieren
    • Beispiel: https://github.com/user/repo.git
  3. Starter Kit - Template verwenden
    • Wählen aus: Nuxt, Next.js, Vue, React
    • Vorkonfiguriert mit Best Practices
    • Beinhaltet CLAUDE.md Anweisungen

Schritt 4: Klicken Sie auf "Space erstellen"

Initialisierung passiert im Hintergrund. Statusaktualisierungen:

  • pending → initializing → ready
  • Fortschritt in der Benutzeroberfläche angezeigt
  • Dauert normalerweise 10-30 Sekunden

Schritt 5: Space öffnen

Sobald fertig, klicken Sie auf "Öffnen", um Dateien anzusehen, oder "Chat", um mit Agents in diesem Space zu interagieren.

Über CLI

# Leeren Space erstellen
teamday spaces create \
  --name "Mein Projekt" \
  --description "Backend API Entwicklung" \
  --visibility organization \
  --type empty

# Von Git klonen
teamday spaces create \
  --name "Bestehendes Repo" \
  --type git \
  --git-url "https://github.com/user/repo.git" \
  --git-branch "main"

# Starter Kit verwenden
teamday spaces create \
  --name "Neue Nuxt App" \
  --type starterKit \
  --kit nuxt

Verfügbare Kits: nuxt, nextjs, vue, react, express, fastify

Workspace-Struktur

Jeder Space hat ein isoliertes Dateisystem:

/data/sandbox/{orgId}/spaces/s-{spaceId}/
├── CLAUDE.md                    # Agent-Anweisungen (auto-generiert)
├── .git/                        # Git-Repository
├── .gitignore                   # Standard-Ignores
├── ...ihre Dateien...

CLAUDE.md Datei

Auto-generierte Anweisungen für Agenten, die in diesem Space arbeiten:

# Projekt: {Space Name}

{Beschreibung}

## Kontext

Dies ist ein TeamDay Workspace für: {Zweck}

Organisation: {org-name}
Space ID: s-{id}
Erstellt: {Datum}

## Richtlinien

Bei der Arbeit in diesem Space:
- Folgen Sie bestehenden Code-Mustern
- Schreiben Sie klare Commit-Nachrichten
- Testen Sie vor dem Commiten
- Dokumentieren Sie signifikante Änderungen

## Dateien

[Agent: Verwenden Sie das `filesystem` Tool zum Erkunden von Dateien]

## Befehle

[Häufige Befehle für diesen Projekttyp]

Sie können CLAUDE.md bearbeiten, um Folgendes hinzuzufügen:

  • Projektspezifische Anweisungen
  • Coding-Standards
  • Architektur-Notizen
  • Häufige Aufgaben
  • Links zur Dokumentation

Dateisystem-Limits

  • Gesamtgröße: 10 GB pro Space
  • Dateianzahl: Unbegrenzt (vernünftige Nutzung)
  • Dateigröße: 100 MB pro Datei-Upload
  • Sync: Automatisch alle 5 Minuten + bei Änderungen

Dateioperationen

Agenten können Dateioperationen mit dem Computer-Service durchführen.

Dateien lesen

Datei anzeigen:

Agent: Zeigen Sie mir den Inhalt von src/api/users.ts

[Agent verwendet Filesystem-Tool zum Lesen der Datei]

Verzeichnis auflisten:

Agent: Welche Dateien sind im src/ Verzeichnis?

[Agent listet Verzeichnisinhalte auf]

Dateien suchen:

Agent: Finden Sie alle Dateien, die "TODO" enthalten

[Agent verwendet ripgrep Tool]

Dateien schreiben

Neue Datei erstellen:

Agent: Erstelle eine neue Datei src/utils/helpers.ts mit Utility-Funktionen

[Agent schreibt Datei]

Bestehende Datei bearbeiten:

Agent: Aktualisiere src/api/users.ts zum Hinzufügen von Input-Validierung

[Agent macht zielgerichtete Änderungen]

Inhalt ersetzen:

Agent: Ersetze die getUserById Funktion mit dieser neuen Implementierung:
[Code]

[Agent führt String-Ersetzung durch]

Datei-Upload

Laden Sie Dateien von Ihrem lokalen Computer hoch:

Über Benutzeroberfläche:

  1. Space öffnen
  2. Klicken Sie auf "Dateien hochladen"
  3. Wählen Sie bis zu 20 Dateien (100MB jeweils)
  4. Dateien erscheinen im Workspace-Stammverzeichnis (oder angegebenem Verzeichnis)

Über CLI:

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

Datei-Download

Laden Sie Workspace-Dateien herunter:

Über Benutzeroberfläche:

  1. Space-Datei-Browser öffnen
  2. Rechtsklick Datei → Download
  3. Oder mehrere wählen → Als ZIP herunterladen

Über CLI:

# Einzelne Datei herunterladen
teamday spaces download s-space123 --file src/app.ts

# Gesamten Workspace herunterladen
teamday spaces download s-space123 --all --format zip

Git-Integration

Jeder Space ist ein Git-Repository.

Automatische Initialisierung

Beim Erstellen eines 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"

Agent Git-Operationen

Agenten können Git mit Befehlen verwenden:

Agent: Check git status

[Agent führt aus: git status]

Agent: Commit diese Änderungen mit der Nachricht "Add user validation"

[Agent führt aus: git add . && git commit -m "Add user validation"]

Agent: Zeigen Sie aktuellen Commit-Verlauf

[Agent führt aus: git log --oneline -10]

Git-Verlauf anzeigen

Über Benutzeroberfläche:

  1. Space öffnen
  2. Klicken Sie auf "History" Tab
  3. Commits, Branches, Diffs anzeigen

Über CLI:

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

Branching

Erstellen und wechseln Sie Branches:

# Via Agent
"Erstelle einen neuen Branch 'feature/add-auth'"

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

Remote Repositories

Verbinden Sie sich mit GitHub, GitLab, etc:

Schritt 1: Remote hinzufügen

# Via Agent
"Füge Git Remote hinzu: 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

Schritt 2: Änderungen pushen

# Via Agent (erfordert GitHub PAT in Space Config)
"Push zu origin main"

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

Authentifizierung: Für private Repos fügen Sie Anmeldedaten hinzu:

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

S3-Synchronisierung

Workspaces synchronisieren automatisch mit S3 für Haltbarkeit und Freigabe.

Funktionsweise

Lokal zu S3 Sync:

  1. Agent ändert Dateien im Workspace
  2. Änderungen werden vom File Watcher erkannt
  3. Geänderte Dateien zu S3 hochgeladen
  4. Sync passiert alle 5 Minuten + sofort beim Dateischließen

S3 zu Lokal Sync (Lazy Loading):

  1. Agent fordert Datei an, die lokal nicht existiert
  2. Computer-Service überprüft S3
  3. Datei wird heruntergeladen, falls verfügbar
  4. Nachfolgende Lesevorgänge sind lokal (schnell)

S3 Bucket-Struktur

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

Manuelles Sync

Erzwinge sofortige Synchronisierung:

Zu S3 hochladen:

teamday spaces sync s-space123 --direction up

Von S3 herunterladen:

teamday spaces sync s-space123 --direction down

Bidirektional:

teamday spaces sync s-space123

Sync-Status

Überprüfen Sie Sync-Status:

teamday spaces sync-status s-space123

Ausgabe:

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

Sync deaktivieren

Für lokale Workspaces (zum Testen):

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

Oder über Umgebungsvariable beim Ausführen des Computer-Service:

SYNC_VOLUMES_TO_S3=false bun run dev

Spaces freigeben

Sichtbarkeitsstufen

Privat:

  • Nur Space-Eigentümer kann zugreifen
  • Agenten müssen explizit zugewiesen werden

Organisation:

  • Alle Org-Mitglieder können zugreifen
  • Jeder Org-Agent kann verwendet werden

Öffentlich:

  • Jeder mit Link kann anzeigen (Lesezugriff)
  • Die Ausführung erfordert Org-Mitgliedschaft

Agenten zuweisen

Geben Sie bestimmten Agenten Zugriff auf einen Space:

Über Benutzeroberfläche:

  1. Space-Einstellungen öffnen
  2. Gehen Sie zum "Agents" Tab
  3. Klicken Sie auf "Agent zuweisen"
  4. Wählen Sie Agent(s) aus der Liste
  5. Speichern

Über CLI:

teamday spaces assign s-space123 --agent char_abc123

Zugewiesene Agenten:

  • Können Dateien im Space lesen/schreiben
  • Sehen Space-Kontext in Ausführungen
  • Erhalten Space-spezifische Anweisungen aus CLAUDE.md

Gemeinsame Spaces

Mehrere Benutzer/Agenten arbeiten zusammen:

Setup:

  1. Erstelle Organisations-Level Space
  2. Weisen Sie spezialisierte Agenten zu (Backend, Frontend, QA)
  3. Fügen Sie Projektanweisungen zu CLAUDE.md hinzu
  4. Team-Mitglieder führen Agenten im Space aus

Beispiel-Workflow:

# PM erstellt Space und Aufgaben
teamday spaces create --name "API Project" --visibility org
teamday agents exec char_pm "Break down the API project into tasks" --space s-api

# Backend Engineer Agent arbeitet an der Implementierung
teamday agents exec char_backend "Implement user endpoints" --space s-api

# QA Agent überprüft und testet
teamday agents exec char_qa "Test the user endpoints" --space s-api

# Alle arbeiten im gleichen Workspace

Zugriffskontrolle

Granulare Berechtigungen (nur UI, über Space-Einstellungen):

  • Viewer - Nur Dateien lesen
  • Editor - Dateien lesen/schreiben
  • Admin - Vollständige Kontrolle + Einstellungen

Best Practices

1. Verwenden Sie aussagekräftige Namen

✅ Gut:
- "Customer API Backend"
- "Marketing Website Content"
- "Q4 Data Analysis"

❌ Schlecht:
- "Project 1"
- "Test"
- "Stuff"

2. Fügen Sie klare Anweisungen hinzu

Bearbeiten Sie CLAUDE.md mit Projektkontext:

# Customer API Project

Backend API für das Kundenverwaltungssystem.

## Tech Stack
- Node.js + Express
- PostgreSQL Datenbank
- JWT Authentifizierung

## Standards
- Folgen Sie RESTful Konventionen
- Schreiben Sie Tests für alle Endpunkte
- Verwenden Sie JSDoc für Funktionen
- Max. Funktionslänge: 50 Zeilen

## Häufige Aufgaben

### Tests ausführen
```bash
bun test

Dev Server starten

bun run dev

Datenbank-Migration

bun run migrate


### 3. Organisieren Sie Dateien

Verwenden Sie Standard-Projektstruktur:

project-space/ ├── CLAUDE.md # Anweisungen ├── README.md # Projekt-Überblick ├── package.json # Abhängigkeiten ├── src/ # Quellcode │ ├── api/ # API-Routes │ ├── services/ # Business Logic │ ├── utils/ # Utilities │ └── types/ # TypeScript-Typen ├── tests/ # Test-Dateien ├── docs/ # Dokumentation └── .github/ # CI/CD Configs


### 4. Commiten Sie häufig

Leiten Sie Agenten an, kleine, fokussierte Commits zu machen:

"Nach der Implementierung jedes Endpunkts mit einer klaren Nachricht commiten"


Anstelle von:

"Alle Endpunkte implementieren und dann am Ende commiten"


### 5. Verwenden Sie Branches für Features

"Erstelle einen neuen Branch 'feature/add-auth' für die Authentifizierungsarbeit"


Vorteile:
- Sichere Experimente
- Einfaches Rollback
- Klare Feature-Isolation

### 6. Räumen Sie regelmäßig auf

Entfernen Sie ungenutzte Dateien und alte Branches:

```bash
# Via Agent
"Lösche ungenutzte Dateien in /tmp und alte Git Branches"

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

7. Überwachen Sie die Space-Größe

Halten Sie Spaces unter 1GB für optimale Leistung:

# Space-Größe überprüfen
teamday spaces info s-space123 | grep size

Große Dateien zum Vermeiden:

  • node_modules (verwenden Sie .gitignore)
  • Build-Artefakte (.next, dist, build)
  • Große Datensätze (verwenden Sie externen Storage)
  • Binary-Dateien (Bilder, Videos)

8. Sichern Sie wichtige Arbeiten

Während S3-Sync Sicherung bietet, auch:

Option 1: Zu Git Remote pushen

teamday spaces git s-space123 push origin main

Option 2: Snapshots herunterladen

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

Option 3: Automatische Sicherungen

#!/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. Richten Sie .gitignore auf

Ignorieren Sie immer:

# .gitignore

# Abhängigkeiten
node_modules/
vendor/

# Build-Ausgaben
dist/
build/
.next/
out/

# Umgebung
.env
.env.local

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

10. Verwenden Sie Spaces zur Isolation

Erstellen Sie separate Spaces für:

  • Development - Aktive Arbeiten
  • Staging - Vor-Produktions-Tests
  • Production - Live-Bereitstellungen (Lesezugriff)
  • Experiments - Neue Ansätze probieren

Fehlerbehebung

Space bleibt in "Initializing"

Symptome: Space-Status erreicht nie "ready"

Lösungen:

# Initialisierungs-Logs überprüfen
teamday spaces logs s-space123 --tail 50

# Abbrechen und neu erstellen
teamday spaces delete s-space123
teamday spaces create --name "My Space" --type empty

Dateien synchronisieren nicht zu S3

Symptome: Änderungen erscheinen nicht in S3

Überprüfung:

# Überprüfen Sie, ob Sync aktiviert ist
teamday spaces config s-space123 --get SYNC_ENABLED

# Erzwinge Sync
teamday spaces sync s-space123 --direction up

# Überprüfen Sie Sync-Logs
teamday spaces logs s-space123 --grep sync

Git-Konflikte

Symptome: Git-Operationen schlagen mit Konfliktfehlern fehl

Lösungen:

# Via Agent
"Zeigen Sie git status an und beheben Sie Konflikte in [Datei]"

# Oder auf letzten guten Zustand zurücksetzen
teamday spaces git s-space123 reset --hard HEAD

Zugriff verweigert Fehler

Symptome: Agent kann nicht auf Space-Dateien zugreifen

Überprüfen:

  1. Überprüfen Sie, ob Agent dem Space zugewiesen ist
  2. Überprüfen Sie Space-Sichtbarkeit
  3. Überprüfen Sie Org-Mitgliedschaft
teamday spaces info s-space123 | grep -E 'visibility|assignedAgents'

Nächste Schritte