Was macht Beads – Persistent Task Memory für KI-Agenten?
Graphbasierter Issue-Tracker, der Konversationskomprimierung überlebt. Bietet persistenten Speicher für sitzungsübergreifende Arbeit mit komplexen Abhängigkeiten.
Überblick
bd (beads) ersetzt Markdown-Aufgabenlisten durch einen abhängigkeitsbewussten Graphen, der in Git gespeichert ist. Im Gegensatz zu TodoWrite (sitzungsbezogen) überlebt bd Komprimierungen und verfolgt komplexe Abhängigkeiten.
Wesentlicher Unterschied:
- bd: Sitzungsübergreifende Arbeit, Abhängigkeiten, überlebt Komprimierung, git-gestützt
- TodoWrite: Einzelsitzungsaufgaben, lineare Ausführung, auf die Sitzung beschränkt
Kernfunktionen:
- 📊 Abhängigkeitsgraphen: Verfolgen, was was blockiert (blocks, parent-child, discovered-from, related)
- 💾 Überlebensfähigkeit bei Komprimierung: Aufgaben bleiben erhalten, wenn der Konversationsverlauf komprimiert wird
- 🐙 Git-Integration: Versionierte Issues in
.beads/issues.jsonl, Synchronisation mitbd sync - 🔍 Intelligente Erkennung: Automatische Suche nach bereiter Arbeit (
bd ready), blockierter Arbeit (bd blocked) - 📝 Prüfpfade: Vollständige Historie von Statusänderungen, Notizen und Entscheidungen
- 🏷️ Reichhaltige Metadaten: Priorität (P0-P4), Typen (Bug/Feature/Task/Epic), Labels, Bearbeiter
Wann bd vs. TodoWrite verwenden:
- ❓ „Werde ich diesen Kontext in 2 Wochen brauchen?“ → JA = bd
- ❓ „Könnte der Konversationsverlauf komprimiert werden?“ → JA = bd
- ❓ „Hat dies Blocker/Abhängigkeiten?“ → JA = bd
- ❓ „Ist dies vage/erkundende Arbeit?“ → JA = bd
- ❓ „Wird dies in dieser Sitzung erledigt?“ → JA = TodoWrite
- ❓ „Ist dies nur eine Aufgabenliste für mich im Moment?“ → JA = TodoWrite
Entscheidungsregel: Wenn das Fortsetzen in 2 Wochen ohne bd schwer wäre, verwenden Sie bd.
Voraussetzungen
Erforderlich:
- bd CLI: Version 0.34.0 oder höher installiert und im PATH
- Git-Repository: Das aktuelle Verzeichnis muss ein Git-Repository sein
- Initialisierung:
bd initmuss einmal ausgeführt werden (Menschen tun dies, nicht Agenten)
Installation überprüfen:
bd --version # Sollte 0.34.0 oder höher zurückgeben
Erstmalige Einrichtung (Menschen führen einmal aus):
cd /pfad/zu/ihrem/repo
bd init # Erstellt .beads/-Verzeichnis mit Datenbank
Optional:
- BEADS_DIR-Umgebungsvariable für alternativen Datenbankspeicherort
- Daemon für Hintergrundsynchronisation:
bd daemon --start
Anleitung
Sitzungsstartprotokoll
Beginnen Sie jede Sitzung hier:
Schritt 1: Nach bereiter Arbeit suchen
bd ready
Zeigt Aufgaben ohne offene Blocker, sortiert nach Priorität (P0 → P4).
Was dies anzeigt:
- Aufgaben-ID (z. B.
myproject-abc) - Titel
- Prioritätsstufe
- Aufgabentyp (Bug, Feature, Task, Epic)
Beispielausgabe:
claude-code-plugins-abc [P1] [task] open
Benutzerauthentifizierung implementieren
claude-code-plugins-xyz [P0] [epic] in_progress
Datenbankschicht umgestalten
Schritt 2: Aufgabe mit höchster Priorität auswählen
Wählen Sie die Aufgabe mit der höchsten Priorität (P0 > P1 > P2 > P3 > P4), die bereit ist.
Schritt 3: Vollständigen Kontext abrufen
bd show <task-id>
Zeigt:
- Vollständige Aufgabenbeschreibung
- Abhängigkeitsgraph (was blockiert dies, was wird von diesem blockiert)
- Prüfpfad (alle Statusänderungen, Notizen)
- Metadaten (erstellt, aktualisiert, Bearbeiter, Labels)
Schritt 4: Mit der Arbeit beginnen
bd update <task-id> --status in_progress
Markiert die Aufgabe als aktiv bearbeitet.
Schritt 5: Notizen während der Arbeit hinzufügen
bd update <task-id> --notes "Abgeschlossen: X. In Bearbeitung: Y. Blockiert durch: Z"
Kritisch für das Überleben der Komprimierung: Schreiben Sie Notizen, als ob Sie einem zukünftigen Agenten ohne jeglichen Konversationskontext erklären würden.
Notizformat (Best Practice):
ABGESCHLOSSEN: Spezifische Ergebnisse (z. B. „JWT-Refresh-Endpunkt + Ratenbegrenzung implementiert“)
IN BEARBEITUNG: Aktueller Zustand + nächster unmittelbarer Schritt
BLOCKER: Was den Fortschritt verhindert
WICHTIGE ENTSCHEIDUNGEN: Wichtiger Kontext oder Benutzerführung
Arbeitsablauf zur Aufgabenerstellung
Wann Aufgaben erstellt werden sollten
Erstellen Sie bd-Aufgaben, wenn:
- Der Benutzer die Verfolgung von Arbeit über Sitzungen hinweg erwähnt
- Der Benutzer sagt „wir sollten X beheben/erstellen/hinzufügen“
- Die Arbeit Abhängigkeiten oder Blocker hat
- Erkundungs-/Forschungsarbeit mit vagen Grenzen
Grundlegende Aufgabenerstellung
bd create "Aufgabentitel" -p 1 --type task
Argumente:
- Titel: Kurze Beschreibung (erforderlich)
- Priorität: 0-4, wobei 0=kritisch, 1=hoch, 2=mittel, 3=niedrig, 4=Rückstand (Standard: 2)
- Typ: Bug, Feature, Task, Epic, Chore (Standard: task)
Beispiel:
bd create "Authentifizierungsfehler beheben" -p 0 --type bug
Mit Beschreibung erstellen
bd create "OAuth implementieren" -p 1 --description "OAuth2-Unterstützung für Google, GitHub, Microsoft hinzufügen. passport.js-Bibliothek verwenden."
Epic mit Kindern
# Übergeordnetes Epic erstellen
bd create "Epic: OAuth-Implementierung" -p 0 --type epic
# Gibt zurück: myproject-abc
# Unteraufgaben erstellen
bd create "OAuth-Anbieter recherchieren" -p 1 --parent myproject-abc
bd create "Auth-Endpunkte implementieren" -p 1 --parent myproject-abc
bd create "Frontend-Login-UI hinzufügen" -p 2 --parent myproject-abc
Arbeitsablauf zum Aktualisieren und Fortschritt
Status ändern
bd update <task-id> --status <neuer-status>
Statuswerte:
open- Nicht gestartetin_progress- Wird aktiv bearbeitetblocked- Steckt fest, wartet auf etwasclosed- Abgeschlossen
Beispiel:
bd update myproject-abc --status blocked
Fortschrittsnotizen hinzufügen
bd update <task-id> --notes "Fortschrittsupdate hier"
Hängt an vorhandenes Notizfeld an (ersetzt nicht).
Priorität ändern
bd update <task-id> -p 0 # Auf kritisch eskalieren
Labels hinzufügen
bd label add <task-id> backend
bd label add <task-id> security
Labels bieten übergreifende Kategorisierung über Status/Typ hinaus.
Abhängigkeitsverwaltung
Abhängigkeiten hinzufügen
bd dep add <kind-id> <eltern-id>
Bedeutung: <eltern-id> blockiert <kind-id> (Elternteil muss zuerst abgeschlossen sein).
Abhängigkeitstypen:
- blocks: Eltern muss geschlossen werden, bevor Kind bereit wird
- parent-child: Hierarchische Beziehung (Epics und Unteraufgaben)
- discovered-from: Aufgabe A führte zur Entdeckung von Aufgabe B
- related: Aufgaben sind verwandt, blockieren sich aber nicht gegenseitig
Beispiel:
# Bereitstellung blockiert durch bestandene Tests
bd dep add deploy-task test-task # test-task blockiert deploy-task
Abhängigkeiten anzeigen
bd dep list <task-id>
Zeigt:
- Was diese Aufgabe blockiert (abhängige)
- Was diese Aufgabe blockiert (Blocker)
Verhinderung zirkulärer Abhängigkeiten
bd verhindert automatisch zirkuläre Abhängigkeiten. Wenn Sie versuchen, einen Kreislauf zu erstellen, schlägt der Befehl fehl.
Arbeitsablauf zum Abschluss
Eine Aufgabe schließen
bd close <task-id> --reason "Zusammenfassung des Abschlusses"
Best Practice: Fügen Sie immer einen Grund hinzu, der beschreibt, was erreicht wurde.
Beispiel:
bd close myproject-abc --reason "Abgeschlossen: OAuth-Endpunkte mit Google-, GitHub-Anbietern implementiert. Tests bestanden."
Neu freigegebene Arbeit prüfen
Nach dem Schließen einer Aufgabe ausführen:
bd ready
Das Schließen einer Aufgabe kann abhängige Aufgaben freigeben, die neu bereit werden.
Epics schließen, wenn Kinder abgeschlossen sind
bd epic close-eligible
Schließt automatisch Epics, bei denen alle untergeordneten Aufgaben geschlossen sind.
Git-Synchronisations-Workflow
All-in-One-Synchronisation
bd sync
Führt aus:
- Exportieren der Datenbank nach
.beads/issues.jsonl - Änderungen in Git committen
- Von Remote pullen (bei Bedarf merge)
- Aktualisiertes JSONL zurück in Datenbank importieren
- Lokale Commits zu Remote pushen
Verwenden Sie, wenn: Sitzungsende, vor der Übergabe an einen Kollegen, nach größeren Fortschritten.
Nur exportieren
bd export -o backup.jsonl
Erstellt JSONL-Backup ohne Git-Operationen.
Nur importieren
bd import -i backup.jsonl
Importiert JSONL-Datei in die Datenbank.
Hintergrund-Daemon
bd daemon --start # Automatische Synchronisation im Hintergrund
bd daemon --status # Daemon-Status prüfen
bd daemon --stop # Automatische Synchronisation beenden
Der Daemon überwacht Datenbankänderungen und exportiert automatisch nach JSONL.
Befehle zum Finden & Suchen
Bereite Arbeit finden
bd ready
Zeigt Aufgaben ohne offene Blocker.
Alle Aufgaben auflisten
bd list --status open # Nur offene Aufgaben
bd list --priority 0 # Nur P0 (kritisch)
bd list --type bug # Nur Bugs
bd list --label backend # Nur mit „backend“ gekennzeichnete
bd list --assignee alice # Nur alice zugewiesene
Aufgabendetails anzeigen
bd show <task-id>
Vollständige Details: Beschreibung, Abhängigkeiten, Prüfpfad, Metadaten.
Nach Text suchen
bd search "Authentifizierung" # Titel und Beschreibungen durchsuchen
bd search login --status open # Mit Filtern kombinieren
Blockierte Arbeit finden
bd blocked
Zeigt alle Aufgaben, die offene Blocker haben, die sie an der Bearbeitung hindern.
Projektstatistiken
bd stats
Zeigt:
- Gesamtissues nach Status (open, in_progress, blocked, closed)
- Issues nach Priorität (P0-P4)
- Issues nach Typ (Bug, Feature, Task, Epic, Chore)
- Abschlussrate
Vollständige Befehlsreferenz
| Befehl | Wann verwenden | Beispiel |
|---|---|---|
| FIND-BEFEHLE | ||
bd ready | Unblockierte Aufgaben finden | Benutzer fragt „Woran soll ich arbeiten?“ |
bd list | Alle Aufgaben anzeigen (mit Filtern) | „Zeig mir alle offenen Bugs“ |
bd show <id> | Aufgabendetails abrufen | „Zeig mir Aufgabe bd-42“ |
bd search <abfrage> | Textsuche über Aufgaben | „Aufgaben zum Thema Auth finden“ |
bd blocked | Stockende Arbeit finden | „Was blockiert uns?“ |
bd stats | Projektmetriken | „Wie viele Aufgaben sind offen?“ |
| ERSTELLUNGSBEFEHLE | ||
bd create | Neue Arbeit verfolgen | „Erstelle eine Aufgabe für diesen Bug“ |
bd template create | Issue-Vorlage verwenden | „Aufgabe aus Bug-Vorlage erstellen“ |
bd init | Beads initialisieren | „Beads in diesem Repo einrichten“ (nur Menschen) |
| AKTUALISIERUNGSBEFEHLE | ||
bd update <id> | Status/Priorität/Notizen ändern | „Als in Bearbeitung markieren“ |
bd dep add | Abhängigkeiten verknüpfen | „Dies blockiert das“ |
bd label add | Mit Labels markieren | „Dies als backend kennzeichnen“ |
bd comments add | Kommentar hinzufügen | „Kommentar zu Aufgabe hinzufügen“ |
bd reopen <id> | Geschlossene Aufgabe wieder öffnen | „bd-42 wieder öffnen, Regression gefunden“ |
bd rename-prefix | Issue-Präfix umbenennen | „Präfix von bd- in proj- ändern“ |
bd epic status | Epic-Fortschritt prüfen | „Epic-Abschluss % anzeigen“ |
| ABSCHLUSSBEFEHLE | ||
bd close <id> | Aufgabe als erledigt markieren | „Schließe diese Aufgabe, sie ist erledigt“ |
bd epic close-eligible | Vollständige Epics automatisch schließen | „Epics schließen, bei denen alle Kinder erledigt sind“ |
| SYNC-BEFEHLE | ||
bd sync | Git-Sync (All-in-One) | „Aufgaben mit git synchronisieren“ |
bd export | Nach JSONL exportieren | „Alle Aufgaben sichern“ |
bd import | Von JSONL importieren | „Aus Backup wiederherstellen“ |
bd daemon | Hintergrund-Sync-Manager | „Auto-Sync-Daemon starten“ |
| BEREINIGUNGSBEFEHLE | ||
bd delete <id> | Issues löschen | „Testaufgabe löschen“ (erfordert --force) |
bd compact | Alte geschlossene Aufgaben archivieren | „Datenbank komprimieren“ |
| BERICHTSBEFEHLE | ||
bd stats | Projektmetriken | „Projektzustand anzeigen“ |
bd audit record | Interaktionen protokollieren | „Diesen LLM-Aufruf aufzeichnen“ |
bd workflow | Arbeitsablauf-Leitfaden anzeigen | „Wie verwende ich beads?“ |
| ERWEITERTE BEFEHLE | ||
bd prime | KI-Kontext aktualisieren | „bd-Workflow-Regeln laden“ |
bd quickstart | Interaktives Tutorial | „Mir die Grundlagen von beads beibringen“ |
bd daemons | Multi-Repo-Daemon-Verwaltung | „Alle beads-Daemons verwalten“ |
bd version | Versionsprüfung | „bd-Version prüfen“ |
bd restore <id> | Komprimiertes Issue wiederherstellen | „Vollständigen Verlauf von git abrufen“ |
Ausgabe
Diese Skill erzeugt:
Aufgaben-IDs: Format <präfix>-<hash> (z. B. claude-code-plugins-abc, myproject-xyz)
Statuszusammenfassungen:
5 open, 2 in_progress, 1 blocked, 47 closed
Abhängigkeitsgraphen (visueller Baum):
myproject-abc: In Produktion bereitstellen [P0] [blocked]
Blockiert durch:
↳ myproject-def: Integrationstests ausführen [P1] [in_progress]
↳ myproject-ghi: Fehlschlagende Tests beheben [P1] [open]
Prüfpfade (vollständige Historie):
2025-12-22 10:00 - Erstellt von alice (P2, task)
2025-12-22 10:15 - Priorität geändert: P2 → P0
2025-12-22 10:30 - Status geändert: open → in_progress
2025-12-22 11:00 - Notizen hinzugefügt: „JWT-Auth implementiert...“
2025-12-22 14:00 - Status geändert: in_progress → blocked
2025-12-22 14:01 - Notizen hinzugefügt: „Blockiert: API-Endpunkt gibt 503 zurück“
Fehlerbehandlung
Häufige Fehler
1. bd: command not found
Ursache: bd CLI nicht installiert oder nicht im PATH Lösung: Installieren von https://github.com/steveyegge/beads
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# Oder über npm
npm install -g @beads/bd
# Oder über Homebrew
brew install steveyegge/beads/bd
2. No .beads database found
Ursache: beads in diesem Repository nicht initialisiert
Lösung: Führen Sie bd init aus (Menschen tun dies einmal, nicht Agenten)
bd init # Erstellt .beads/-Verzeichnis
3. Task not found: <id>
Ursache: Ungültige Aufgaben-ID oder Aufgabe existiert nicht
Lösung: Verwenden Sie bd list, um alle Aufgaben zu sehen und das ID-Format zu überprüfen
bd list # Alle Aufgaben sehen
bd search <teil-titel> # Aufgabe nach Titel finden
4. Circular dependency detected
Ursache: Versuch, einen Abhängigkeitskreislauf zu erstellen (A blockiert B, B blockiert A) Lösung: bd verhindert automatisch zirkuläre Abhängigkeiten. Strukturieren Sie den Abhängigkeitsgraphen um.
bd dep list <id> # Aktuelle Abhängigkeiten anzeigen
5. Git-Merge-Konflikte in .beads/issues.jsonl
Ursache: Mehrere Benutzer haben dasselbe Issue geändert Lösung: bd sync behandelt JSONL-Konflikte automatisch. Falls manuelles Eingreifen erforderlich:
# Konflikt anzeigen
git status
# bd bietet Konfliktlösungswerkzeuge
bd sync --merge # Automatische Auflösung versuchen
6. Database is locked
Ursache: Daemon oder ein anderer Prozess hat exklusive Sperre Lösung: Daemon neu starten oder auf Freigabe der Sperre warten
bd daemon --stop
bd daemon --start
7. Synchronisationsfehler
Ursache: Netzwerkprobleme, Authentifizierungsfehler oder Git-Konfiguration Lösung: Git-Remote-Zugriff und Anmeldeinformationen prüfen
git fetch # Konnektivität testen
git status # Repo-Status überprüfen
Beispiele
...