Aller au contenu

InsightsSoftware Factory

Backlog.md : le backlog Markdown pour Claude Code et Codex

Backlog.md range chaque tâche dans un fichier Markdown du dépôt et la pilote par une CLI. Installation, commandes vérifiées sur la version 1.57.4, format exact d'un fichier de tâche, branchement de Claude Code et Codex, et limites pour une DSI.

Backlog.md : le backlog Markdown pour Claude Code et Codex

Backlog.md transforme un dossier de votre dépôt en tableau de projet : chaque tâche est un fichier Markdown, créé et modifié par une CLI qui fonctionne sans configuration. C'est l'outil prêt à l'emploi le plus direct pour mettre vos tickets là où travaillent vos agents. Il ne remplace pas un outil de portefeuille : il sert une équipe, sur un dépôt, qui fait déjà travailler Claude Code ou Codex. Cette page couvre l'installation, les commandes, le format des fichiers, le branchement des agents et les limites, vérifiés sur la version 1.57.4 publiée le 22 novembre 2026.

Qu'est-ce que Backlog.md ?

Backlog.md est un projet open source sous licence MIT, créé par Alex Gavrilescu (MrLesk) et lancé en juin 2025. Le 22 novembre 2026, son dépôt GitHub comptait 7 469 étoiles, 497 forks et environ 1 530 commits1. Le rythme de publication est soutenu : la v1.54.0 du 16 octobre 2026 a été suivie de la v1.55.0 le 20 octobre, de trois correctifs jusqu'au 23 octobre, puis des v1.56.0 et v1.57.0 le 21 novembre et de quatre correctifs jusqu'à la v1.57.4 du 22 novembre2. Le README précise que presque tout le code du projet est écrit par des agents qui travaillent eux-mêmes via Backlog.md, et que le registre complet des tâches est public dans le dossier backlog/ du dépôt1.

Le README décrit une méthode autant qu'un outil : trois relectures humaines, sur les tâches et leurs critères d'acceptation, sur le plan d'implémentation que l'agent écrit dans la tâche, puis sur le code. Il pose une règle simple : une tâche, une fenêtre de contexte, une pull request1.

Comment l'installer ?

npm i -g backlog.md        # ou : bun add -g backlog.md
brew install backlog-md    # Homebrew
backlog init "Mon projet"  # dans le dépôt : crée le dossier backlog/

Pour un essai sans installation, utilisez le nom complet du paquet : npx backlog.md init "Mon projet". La documentation prévient que npx backlog appelle un paquet tiers sans rapport3. L'option --no-git de backlog init crée un projet sur le seul système de fichiers. L'option --task-prefix change le préfixe des identifiants, TASK-1 par défaut1.

L'assistant d'initialisation demande le nom du projet, l'emplacement du dossier (backlog/, .backlog/ ou un chemin choisi) et la façon de brancher vos outils d'IA. Trois choix : des instructions CLI (option recommandée, qui écrit dans AGENTS.md une consigne courte demandant aux agents de lancer backlog instructions overview), un connecteur MCP, ou aucune intégration3. La commande backlog agents --update-instructions met ensuite à jour CLAUDE.md, AGENTS.md, GEMINI.md et .github/copilot-instructions.md3. Depuis la v1.54.0, init échoue s'il ne peut pas obtenir une réponse obligatoire : un script d'installation doit donc fournir toutes ses options4.

Quelles sont les commandes essentielles ?

ActionCommande
Créer une tâchebacklog task create "Ajouter l'OAuth"
Détaillerbacklog task edit 1 -d "Contexte" --ac "Critère d'acceptation"
Cocher un critèrebacklog task edit 1 --check-ac 1
Lister par statutbacklog task list -s "To Do"
Lister ce qui n'est bloqué par rienbacklog task list --ready
Sortie pour scriptsbacklog task list --json
Paginerbacklog task list --max-count 20 --skip 20 --plain
Rechercherbacklog search "kanban"
Board en terminalbacklog board
Interface web localebacklog browser --port 8080
Retirer du boardbacklog task archive 1
Remettre sur le boardbacklog task restore 1

Deux changements récents cassent d'anciens tutoriels. Depuis la v1.54.0, backlog task complete et l'outil MCP task_complete ne font plus rien : passez la tâche au statut final (« Done » par défaut), puis archivez-la. L'archivage garde l'identifiant, les dépendances et les références ; une tâche archivée se lit encore et ne se modifie plus. Une dépendance archivée ne débloque la tâche suivante que si elle a été archivée au statut final : archiver une tâche « In Progress » laisse ses dépendantes bloquées. Pour supprimer définitivement, on archive d'abord, puis backlog task delete, qui ne demande aucune confirmation4. Depuis la v1.53.0, les commandes de liste et de recherche acceptent --max-count et --skip, et --count n'affiche que le nombre de résultats5. Sur un backlog de plusieurs centaines de tâches, l'agent lit une page à la fois au lieu de charger toute la liste dans son contexte.

La sortie --json suit un contrat versionné (schemaVersion: 1), base de tout reporting maison, et chaque tâche y porte un champ isReady qui dit si ses dépendances sont terminées3.

À quoi ressemble un fichier de tâche ?

Chaque tâche est un fichier backlog/tasks/task-<id> - <Titre-avec-tirets>.md. Depuis la v1.56.0, le nom du fichier suit les changements de titre, sans changer l'identifiant6. Voici la forme d'une tâche, calquée sur les fichiers du dépôt de Backlog.md lui-même7 :

---
id: TASK-12
title: Ajouter la recherche plein texte
status: In Progress
assignee:
  - '@claude'
created_date: '2026-11-22T09:30:45Z'
labels:
  - backend
  - search
dependencies:
  - TASK-9
priority: high
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Indexer les tâches, les documents et les décisions.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 La recherche renvoie les tâches par titre et par contenu
<!-- AC:END -->

Trois détails comptent si vous générez ces fichiers vous-même. L'en-tête doit être du YAML entre deux lignes ---, et un @ en tête de valeur doit être entre guillemets. Les commentaires SECTION et AC bornent les sections que la CLI réécrit : sans eux, Backlog.md refuse de remplacer une section ambiguë plutôt que de deviner3. Depuis la v1.56.0, les dates de création et de mise à jour sont enregistrées en UTC à la seconde6.

Le dossier backlog/ contient aussi docs/, decisions/, drafts/, milestones/, archive/ et le fichier config.yml7. La configuration peut aussi vivre à la racine du dépôt, dans backlog.config.yml, qui est prioritaire et seul à accepter un dossier de backlog personnalisé1. Tout est versionné avec le code : en revue, vous relisez la modification d'une tâche dans la même merge request que le code qu'elle décrit. Le README demande de passer par la CLI, le MCP ou l'interface web plutôt que d'éditer ces fichiers à la main, pour garder des champs cohérents1.

Comment l'utiliser avec Claude Code et Codex ?

La voie par défaut est la CLI : l'agent lit AGENTS.md ou CLAUDE.md, lance backlog instructions overview, puis appelle les commandes backlog comme un développeur. Le README présente le serveur MCP comme une option maintenue « when you explicitly prefer an MCP connector »1. Si vous le préférez :

claude mcp add backlog --scope user -- backlog mcp start
codex mcp add backlog -- backlog mcp start

Un seul serveur déclaré au niveau utilisateur couvre tous vos dépôts : il trouve le projet actif à partir des racines MCP du client et suit les changements d'espace de travail ou de worktree. La variable BACKLOG_CWD l'épingle à un projet. Les agents lisent alors le guide de travail à l'adresse backlog://workflow/overview1. La v1.51.0 du 2 septembre 2026 a changé la consigne donnée aux agents : « Agents are told to read the Backlog overview once per conversation instead of before every request »8. Le guide ne coûte plus de contexte à chaque requête.

La boucle de travail que décrit le README, appliquée à Codex CLI comme à Claude Code :

  1. décrire la fonctionnalité et demander à l'agent de la découper en petites tâches Backlog.md, avec description et critères d'acceptation ;
  2. relire et corriger ces critères ;
  3. confier une seule tâche par session et demander d'abord un plan d'implémentation écrit dans la tâche ;
  4. valider le plan, laisser l'agent coder, relire le code et les tests, passer la tâche à « Done ».

Si le résultat ne convient pas, le README conseille de préciser la tâche et de la relancer dans une session neuve1. C'est du context engineering appliqué au ticket : la tâche devient la mémoire qui survit à la fin de la session.

Quelles sont les limites en entreprise ?

Backlog.md sert très bien une équipe sur un dépôt. Au-delà, voici ce que vous devrez construire ou accepter :

  • Pas de vue de portefeuille. Un backlog vit dans un dépôt. L'attribut project, ajouté en v1.51.0, range les tâches d'un monorepo8, mais rien n'agrège dix dépôts.
  • Pas de reporting de vélocité ni de burndown. Vous le construisez à partir de la sortie --json ; seuls le board et des statistiques de projet sont fournis.
  • Des permissions héritées du dépôt. Qui lit le code lit les tâches. Un ticket sensible n'a pas sa place dans ce dossier.
  • Un accès difficile pour les profils non techniques. L'interface web écoute par défaut sur 127.0.0.1 et suppose un poste avec le dépôt. Depuis la v1.57.0, backlog browser export public/backlog produit un site statique en lecture seule (board, tâches, documents, décisions et jalons) à publier sur GitLab Pages ou GitHub Pages ; les options --tasks, --docs, --decisions et --milestones limitent les sections publiées9. Le README prévient que tout lecteur du site voit les plans, notes et commentaires des tâches publiées1.
  • Des écarts entre branches. Une même tâche peut évoluer sur deux branches. Dans ses vues multi-branches, Backlog.md retient la version la plus avancée selon l'ordre des statuts6, et backlog doctor signale les identifiants en double3. La discipline « une tâche, une branche » reste la meilleure protection. Sur un gros dépôt, les réglages checkActiveBranches, activeBranchDays et remoteOperations bornent ce que Backlog.md inspecte sur les autres branches et au distant, et autoCommit et bypassGitHooks décident s'il committe lui-même et s'il contourne vos hooks1.

Questions fréquentes

Backlog.md est-il gratuit ?

Oui. Il est publié sous licence MIT, sans compte, sans serveur et, selon le README, sans télémétrie.

Faut-il Git ?

Non : backlog init --no-git crée un projet sur le seul système de fichiers ; la configuration enregistrée force alors checkActiveBranches, remoteOperations et autoCommit à false. L'intérêt principal reste pourtant le versionnement des tâches avec le code.

Peut-on importer Jira dans Backlog.md ?

Pas nativement. Un script d'export comme celui de notre page exporter ses tickets Jira en Markdown produit des fichiers à en-tête YAML ; vérifiez ensuite le nommage, les marqueurs de section et lancez backlog doctor.

Mes anciens scripts appellent backlog task complete. Que faire ?

Remplacez l'appel par un passage au statut final (backlog task edit <id> -s Done), puis par backlog task archive au moment du nettoyage. Les tâches restées dans un ancien dossier completed se lisent comme archivées, et backlog doctor --fix les déplace dans archive/tasks.

Piloter un premier essai sur un dépôt

Backlog.md convient à une équipe qui confie déjà une partie du développement à des agents et relit chaque merge request. Il ne pilote pas un portefeuille de cinquante équipes. Un pilote tient en une semaine : un dépôt, une équipe volontaire, la consigne dans AGENTS.md, et la règle d'écrire les tâches par la CLI. Pour le situer face aux autres options, consultez notre grille des 15 solutions et notre comparatif Backlog.md, Beads ou Task Master.

Sources

  1. Alex Gavrilescu, dépôt Backlog.md (README, étoiles, forks et commits), GitHub, consulté le 22 novembre 2026. github.com
  2. Backlog.md, page des versions (v1.54.0 à v1.57.4), GitHub, consultée le 22 novembre 2026. github.com
  3. Backlog.md, « CLI Reference » (CLI-INSTRUCTIONS.md), GitHub, consulté le 22 novembre 2026. github.com
  4. Backlog.md, notes de version v1.54.0, 16 octobre 2026. github.com
  5. Backlog.md, notes de version v1.53.0, 24 septembre 2026. github.com
  6. Backlog.md, notes de version v1.56.0, 21 novembre 2026. github.com
  7. Backlog.md, dossier backlog/ du dépôt et tâche BACK-260, GitHub, consultés le 22 novembre 2026. github.com
  8. Backlog.md, notes de version v1.51.0, 2 septembre 2026. github.com
  9. Backlog.md, notes de version v1.57.0, 21 novembre 2026. github.com

Passer à l’action

Sortir de Jira : par où commencer ?

Nous cadrons avec vous un pilote Backlog.md sur un dépôt et une équipe déjà outillés en agents, avant toute décision de migration.

Demander un Diagnostic 10x