Beads - Mémoire persistante des tâches pour agents IA

Que fait Beads - Mémoire persistante des tâches pour agents IA ?

Tracker de tickets basé sur un graphe de dépendances, qui survit à la compaction des conversations. Fournit une mémoire persistante pour un travail multi-sessions avec des dépendances complexes.

Aperçu

bd (beads) remplace les listes de tâches Markdown par un graphe de dépendances stocké dans Git. Contrairement à TodoWrite (limité à la session), bd persiste à travers les compactions et suit les dépendances complexes.

Distinction clé :

• bd : Travail multi-sessions, dépendances, survit à la compaction, basé sur Git
• TodoWrite : Tâches mono-session, exécution linéaire, limité à la conversation

Capacités principales :

• 📊 Graphes de dépendances : Suivi de ce qui bloque quoi (bloque, parent-enfant, découvert, lié)
• 💾 Survie à la compaction : Les tâches persistent lorsque l'historique de la conversation est compacté
• 🐙 Intégration Git : Tickets versionnés dans .beads/issues.jsonl, synchronisation avec bd sync
• 🔍 Découverte intelligente : Trouve automatiquement le travail prêt (bd ready) et bloqué (bd blocked)
• 📝 Pistes d'audit : Historique complet des changements de statut, notes et décisions
• 🏷️ Métadonnées riches : Priorité (P0-P4), types (bogue/fonctionnalité/tâche/épopée), étiquettes, assignés

Quand utiliser bd vs TodoWrite :

• ❓ "Aurai-je besoin de ce contexte dans 2 semaines ?" → OUI = bd
• ❓ "L'historique de la conversation pourrait-il être compacté ?" → OUI = bd
• ❓ "Y a-t-il des bloqueurs/dépendances ?" → OUI = bd
• ❓ "S'agit-il d'un travail flou/exploratoire ?" → OUI = bd
• ❓ "Ce travail sera-t-il terminé dans cette session ?" → OUI = TodoWrite
• ❓ "S'agit-il simplement d'une liste de tâches pour moi maintenant ?" → OUI = TodoWrite

Règle de décision : Si reprendre dans 2 semaines serait difficile sans bd, utilisez bd.

Prérequis

Requis :

• CLI bd : Version 0.34.0 ou ultérieure installée et dans le PATH
• Dépôt Git : Le répertoire courant doit être un dépôt Git
• Initialisation : bd init doit être exécuté une fois (fait par les humains, pas les agents)

Vérifier l'installation :

bd --version  # Doit retourner 0.34.0 ou ultérieure

Configuration initiale (les humains l'exécutent une fois) :

cd /chemin/vers/votre/depot
bd init  # Crée le répertoire .beads/ avec la base de données

Optionnel :

• Variable d'environnement BEADS_DIR pour un emplacement alternatif de la base de données
• Démon pour la synchronisation en arrière-plan : bd daemon --start

Instructions

Protocole de début de session

Chaque session, commencez ici :

Étape 1 : Vérifier le travail prêt

bd ready

Affiche les tâches sans bloqueurs ouverts, triées par priorité (P0 → P4).

Ce que cela montre :

• ID de la tâche (ex : monprojet-abc)
• Titre
• Niveau de priorité
• Type de ticket (bogue, fonctionnalité, tâche, épopée)

Exemple de sortie :

claude-code-plugins-abc [P1] [tâche] ouvert
  Implémenter l'authentification utilisateur

claude-code-plugins-xyz [P0] [épopée] en_cours
  Refactoriser la couche base de données

Étape 2 : Choisir la tâche de plus haute priorité

Choisissez la tâche prête de plus haute priorité (P0 > P1 > P2 > P3 > P4).

Étape 3 : Obtenir le contexte complet

bd show <id-tâche>

Affiche :

• Description complète de la tâche
• Graphe de dépendances (ce qui bloque cette tâche, ce que cette tâche bloque)
• Piste d'audit (tous les changements de statut, notes)
• Métadonnées (création, mise à jour, assigné, étiquettes)

Étape 4 : Commencer à travailler

bd update <id-tâche> --status en_cours

Marque la tâche comme étant activement travaillée.

Étape 5 : Ajouter des notes en travaillant

bd update <id-tâche> --notes "Terminé : X. En cours : Y. Bloqué par : Z"

Critique pour la survie à la compaction : Écrivez les notes comme si vous expliquiez à un futur agent sans aucun contexte de conversation.

Format des notes (meilleure pratique) :

TERMINÉ : Livrables spécifiques (ex : "implémenté endpoint de rafraîchissement JWT + limitation de débit")
EN COURS : État actuel + prochaine étape immédiate
BLOQUEURS : Ce qui empêche la progression
DÉCISIONS CLÉS : Contexte important ou orientation de l'utilisateur

---

Flux de création de tâches

Quand créer des tâches

Créez des tâches bd quand :

• L'utilisateur mentionne le suivi d'un travail sur plusieurs sessions
• L'utilisateur dit "nous devrions corriger/construire/ajouter X"
• Le travail a des dépendances ou des bloqueurs
• Travail exploratoire/de recherche avec des limites floues

Création de tâche de base

bd create "Titre de la tâche" -p 1 --type tâche

Arguments :

• Titre : Brève description (obligatoire)
• Priorité : 0-4 où 0=critique, 1=haute, 2=moyenne, 3=basse, 4=backlog (défaut : 2)
• Type : bogue, fonctionnalité, tâche, épopée, chore (défaut : tâche)

Exemple :

bd create "Corriger le bogue d'authentification" -p 0 --type bogue

Créer avec description

bd create "Implémenter OAuth" -p 1 --description "Ajouter le support OAuth2 pour Google, GitHub, Microsoft. Utiliser la bibliothèque passport.js."

Épopée avec enfants

# Créer l'épopée parent
bd create "Épopée : Implémentation OAuth" -p 0 --type épopée
# Retourne : monprojet-abc

# Créer les tâches enfants
bd create "Rechercher les fournisseurs OAuth" -p 1 --parent monprojet-abc
bd create "Implémenter les endpoints d'authentification" -p 1 --parent monprojet-abc
bd create "Ajouter l'interface utilisateur de connexion frontale" -p 2 --parent monprojet-abc

---

Flux de mise à jour et progression

Changer le statut

bd update <id-tâche> --status <nouveau-statut>

Valeurs de statut :

• ouvert - Non commencé
• en_cours - Activement travaillé
• bloqué - Bloqué, en attente de quelque chose
• fermé - Terminé

Exemple :

bd update monprojet-abc --status bloqué

Ajouter des notes de progression

bd update <id-tâche> --notes "Mise à jour de la progression ici"

Ajoute au champ de notes existant (ne remplace pas).

Changer la priorité

bd update <id-tâche> -p 0  # Escalader à critique

Ajouter des étiquettes

bd label add <id-tâche> backend
bd label add <id-tâche> sécurité

Les étiquettes offrent une catégorisation transversale au-delà du statut/type.

---

Gestion des dépendances

Ajouter des dépendances

bd dep add <id-enfant> <id-parent>

Signification : <id-parent> bloque <id-enfant> (le parent doit être terminé en premier).

Types de dépendances :

• bloque : Le parent doit se fermer avant que l'enfant devienne prêt
• parent-enfant : Relation hiérarchique (épopées et sous-tâches)
• découvert-de : La tâche A a conduit à la découverte de la tâche B
• lié : Les tâches sont liées mais ne se bloquent pas

Exemple :

# Déploiement bloqué par la réussite des tests
bd dep add tâche-déploiement tâche-test  # tâche-test bloque tâche-déploiement

Voir les dépendances

bd dep list <id-tâche>

Affiche :

• Ce que cette tâche bloque (dépendants)
• Ce qui bloque cette tâche (bloqueurs)

Prévention des dépendances circulaires

bd empêche automatiquement les dépendances circulaires. Si vous essayez de créer un cycle, la commande échoue.

---

Flux de terminaison

Fermer une tâche

bd close <id-tâche> --reason "Résumé de la terminaison"

Meilleure pratique : Incluez toujours une raison décrivant ce qui a été accompli.

Exemple :

bd close monprojet-abc --reason "Terminé : Endpoints OAuth implémentés avec les fournisseurs Google, GitHub. Tests réussis."

Vérifier le travail nouvellement débloqué

Après avoir fermé une tâche, exécutez :

bd ready

La fermeture d'une tâche peut débloquer des tâches dépendantes, les rendant nouvellement prêtes.

Fermer les épopées lorsque les enfants sont terminés

bd epic close-eligible

Ferme automatiquement les épopées dont toutes les tâches enfants sont fermées.

---

Flux de synchronisation Git

Synchronisation tout-en-un

bd sync

Effectue :

1. Exportation de la base de données vers .beads/issues.jsonl
2. Validation des changements dans Git
3. Tirage depuis le dépôt distant (fusion si nécessaire)
4. Importation du JSONL mis à jour dans la base de données
5. Push des validations locales vers le dépôt distant

À utiliser quand : Fin de session, avant de passer le relais à un collègue, après un progrès majeur.

Exporter uniquement

bd export -o sauvegarde.jsonl

Crée une sauvegarde JSONL sans opérations Git.

Importer uniquement

bd import -i sauvegarde.jsonl

Importe un fichier JSONL dans la base de données.

Démon en arrière-plan

bd daemon --start  # Synchronisation automatique en arrière-plan
bd daemon --status # Vérifier l'état du démon
bd daemon --stop   # Arrêter la synchronisation automatique

Le démon surveille les changements de la base de données et exporte automatiquement vers JSONL.

---

Commandes de recherche et de découverte

Trouver le travail prêt

bd ready

Affiche les tâches sans bloqueurs ouverts.

Lister toutes les tâches

bd list --status ouvert           # Uniquement les tâches ouvertes
bd list --priority 0              # Uniquement P0 (critique)
bd list --type bogue              # Uniquement les bogues
bd list --label backend           # Uniquement étiquetées "backend"
bd list --assignee alice          # Uniquement assignées à alice

Afficher les détails d'une tâche

bd show <id-tâche>

Détails complets : description, dépendances, piste d'audit, métadonnées.

Recherche par texte

bd search "authentification"      # Recherche dans les titres et descriptions
bd search connexion --status ouvert   # Combiner avec des filtres

Trouver le travail bloqué

bd blocked

Affiche toutes les tâches qui ont des bloqueurs ouverts les empêchant d'être travaillées.

Statistiques du projet

bd stats

Affiche :

• Total des tickets par statut (ouvert, en_cours, bloqué, fermé)
• Tickets par priorité (P0-P4)
• Tickets par type (bogue, fonctionnalité, tâche, épopée, chore)
• Taux d'achèvement

---

Référence complète des commandes

Commande	Quand l'utiliser	Exemple
COMMANDES DE RECHERCHE
bd ready	Trouver les tâches non bloquées	L'utilisateur demande "sur quoi devrais-je travailler ?"
bd list	Voir toutes les tâches (avec filtres)	"Montre-moi tous les bogues ouverts"
bd show <id>	Obtenir les détails d'une tâche	"Montre-moi la tâche bd-42"
bd search <requête>	Recherche textuelle dans les tâches	"Trouver les tâches sur l'auth"
bd blocked	Trouver le travail bloqué	"Qu'est-ce qui nous bloque ?"
bd stats	Métriques du projet	"Combien de tâches sont ouvertes ?"
COMMANDES DE CRÉATION
bd create	Suivre un nouveau travail	"Créer une tâche pour ce bogue"
bd template create	Utiliser un modèle de ticket	"Créer une tâche à partir du modèle de bogue"
bd init	Initialiser beads	"Configurer beads dans ce dépôt" (humains uniquement)
COMMANDES DE MISE À JOUR
bd update <id>	Changer le statut/priorité/notes	"Marquer comme en cours"
bd dep add	Lier des dépendances	"Ceci bloque cela"
bd label add	Étiqueter avec des labels	"Étiqueter ceci comme backend"
bd comments add	Ajouter un commentaire	"Ajouter un commentaire à la tâche"
bd reopen <id>	Rouvrir une tâche fermée	"Rouvrir bd-42, régression trouvée"
bd rename-prefix	Renommer le préfixe du ticket	"Changer le préfixe de bd- à proj-"
bd epic status	Vérifier la progression d'une épopée	"Afficher le % d'achèvement de l'épopée"
COMMANDES DE TERMINAISON
bd close <id>	Marquer une tâche comme terminée	"Fermer cette tâche, c'est fini"
bd epic close-eligible	Fermer automatiquement les épopées complètes	"Fermer les épopées dont tous les enfants sont terminés"
COMMANDES DE SYNCHRONISATION
bd sync	Synchronisation Git (tout-en-un)	"Synchroniser les tâches vers Git"
bd export	Exporter vers JSONL	"Sauvegarder toutes les tâches"
bd import	Importer depuis JSONL	"Restaurer depuis la sauvegarde"
bd daemon	Gestionnaire de synchronisation en arrière-plan	"Démarrer le démon de synchronisation automatique"
COMMANDES DE NETTOYAGE
bd delete <id>	Supprimer des tickets	"Supprimer la tâche de test" (nécessite --force)
bd compact	Archiver les anciennes tâches fermées	"Compresser la base de données"
COMMANDES DE RAPPORT
bd stats	Métriques du projet	"Afficher la santé du projet"
bd audit record	Enregistrer les interactions	"Enregistrer cet appel LLM"
bd workflow	Afficher le guide de flux de travail	"Comment utiliser beads ?"
COMMANDES AVANCÉES
bd prime	Rafraîchir le contexte IA	"Charger les règles de flux de travail bd"
bd quickstart	Tutoriel interactif	"Apprendre les bases de beads"
bd daemons	Gestion multi-dépôts du démon	"Gérer tous les démons beads"
bd version	Vérification de version	"Vérifier la version de bd"
bd restore <id>	Restaurer un ticket compacté	"Obtenir l'historique complet depuis Git"

---

Sortie

Cette compétence produit :

IDs de tâches : Format <préfixe>-<hash> (ex : claude-code-plugins-abc, monprojet-xyz)

Résumés de statut :

5 ouverts, 2 en_cours, 1 bloqué, 47 fermés

Graphes de dépendances (arbre visuel) :

monprojet-abc : Déployer en production [P0] [bloqué]
  Bloqué par :
    ↳ monprojet-def : Exécuter les tests d'intégration [P1] [en_cours]
    ↳ monprojet-ghi : Corriger les tests échoués [P1] [ouvert]

Pistes d'audit (historique complet) :

2025-12-22 10:00 - Créé par alice (P2, tâche)
2025-12-22 10:15 - Priorité changée : P2 → P0
2025-12-22 10:30 - Statut changé : ouvert → en_cours
2025-12-22 11:00 - Notes ajoutées : "Implémenté JWT auth..."
2025-12-22 14:00 - Statut changé : en_cours → bloqué
2025-12-22 14:01 - Notes ajoutées : "Bloqué : Endpoint API retourne 503"

---

Gestion des erreurs

Échecs courants

1. bd : commande introuvable

Cause : CLI bd non installée ou pas dans le PATH Solution : Installer depuis https://github.com/steveyegge/beads

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Ou via npm
npm install -g @beads/bd

# Ou via Homebrew
brew install steveyegge/beads/bd

2. Aucune base de données .beads trouvée

Cause : beads non initialisé dans ce dépôt Solution : Exécuter bd init (les humains le font une fois, pas les agents)

bd init  # Crée le répertoire .beads/

3. Tâche non trouvée : <id>

Cause : ID de tâche invalide ou tâche inexistante Solution : Utiliser bd list pour voir toutes les tâches et vérifier le format de l'ID

bd list                    # Voir toutes les tâches
bd search <titre-partiel>  # Trouver une tâche par titre

4. Dépendance circulaire détectée

Cause : Tentative de créer un cycle de dépendances (A bloque B, B bloque A) Solution : bd empêche automatiquement les dépendances circulaires. Restructurer le graphe de dépendances.

bd dep list <id>  # Voir les dépendances actuelles

5. Conflits de fusion Git dans .beads/issues.jsonl

Cause : Plusieurs utilisateurs ont modifié le même ticket Solution : bd sync gère automatiquement les conflits JSONL. Si une intervention manuelle est nécessaire :

# Voir le conflit
git status

# bd fournit des outils de résolution de conflits
bd sync --merge  # Tenter la résolution automatique

6. Base de données verrouillée

Cause : Le démon ou un autre processus a un verrou exclusif Solution : Redémarrer le démon ou attendre la libération du verrou

bd daemon --stop
bd daemon --start

7. Échecs de synchronisation

Cause : Problèmes réseau, échecs d'authentification ou configuration Git Solution : Vérifier l'accès au dépôt distant et les informations d'identification

git fetch  # Tester la connectivité
git status # Vérifier l'état du dépôt

---

Exemples

…

[tronqué pour la traduction]