Backlog.md workflow in Claude Code

Definitie

Backlog.md is een CLI-gebaseerd taakbeheersysteem dat Markdown-native Kanban-borden beheert via losse .md-bestanden per taak. In Claude Code-sessies fungeert het als de centrale backlog voor alle actieve projecten, aangestuurd via CLI-commando’s en optioneel als MCP server.

Context

Claude Code heeft geen persistent geheugen tussen sessies. Backlog.md vult dat gat door taakstatus, prioriteit en projectlabels buiten de sessie te bewaren in versiebeheerde Markdown-bestanden. De centrale backlog staat in ~/Claude/projects/backlog/ en bevat taken voor alle actieve projecten gecombineerd onder projectlabels.

Kernpunten

Installatie via Homebrew

Backlog.md is beschikbaar via Homebrew en niet via npm. Correcte installatie:

brew install backlog-md

Versie tijdens installatie: v1.44.0. Na installatie initialiseren in de gewenste map:

cd ~/Claude/projects && backlog init

Dit maakt een backlog/ map aan met backlog.config.json en een tasks/-submap.

Remote operations uitschakelen

Claude Code heeft geen git-credentials in de sessieomgeving. Remote push/pull via Backlog.md leidt dan tot fouten. Zet autoCommit en remote sync uit in backlog.config.json:

{
  "autoCommit": false
}

Reden: de projects/-map staat in .gitignore van de Claude workspace repo, waardoor automatische commits naar de verkeerde remote zouden gaan of helemaal mislukken. Handmatige git-commits buiten Backlog.md blijven altijd mogelijk.

Centrale vs. per-project backlog

Twee werkbare aanpakken:

• Centrale backlog in ~/Claude/projects/backlog/: alle projecttaken op één plek, gescheiden via labels (#eindredacteur, website, boek-engagency, cc-setup).
• Per-project backlog in projectmap/.backlog/tasks/: backlog leeft naast de projectbestanden, handig bij een geïsoleerde projectworkflow.

De centrale aanpak werkt beter voor sessies die meerdere projecten overspannen. Per-project is handiger bij dedicated project-sessies.

Zoek-eerst-patroon

Begin elke sessie met oriëntatie voordat taken worden uitgevoerd:

backlog board          # visueel Kanban overzicht
backlog task list      # gesorteerde takenlijst
backlog task 080 --plain  # detail van één taak

Volgorde: lees eerst de taak volledig, inclusief acceptatiecriteria, voordat je begint. Eén taak per sessie: volledig afronden is effectiever dan meerdere taken half doen.

Statussen

Standaard statussen in Backlog.md: To Do, In Progress, Done. Status wijzigen:

backlog task 42 --status "In Progress"

Labels toevoegen:

backlog task 42 --label website

Batch-grooming via backlog task edit

Voor backlog-onderhoud zonder hele task-beschrijvingen te herschrijven, biedt backlog task edit losse flags:

Flag	Doel
--ac "tekst"	Acceptance criterion toevoegen (meermaals gebruiken)
--dod "tekst"	Definition of Done item toevoegen
--dep TASK-XXX	Dependency (blockedBy) zetten
--add-label <label>	Label toevoegen
--remove-label <label>	Label verwijderen
--remove-ac <index>	AC verwijderen op 1-based index
--check-ac <index>	AC aanvinken
--priority <high|medium|low>	Prioriteit zetten
--notes "tekst"	Implementation notes (replace)
--append-notes "tekst"	Notes toevoegen zonder te overschrijven

Voorbeeld: dependency en twee criteria toevoegen in een keer.

backlog task edit TASK-088 \
  --dep TASK-087 \
  --ac "URL-structuur besloten (pad of subdomein)" \
  --ac "DNS records geconfigureerd" \
  --dod "Live URL bereikbaar met geldig SSL"

Grooming-patroon voor grote backlogs

Voor een sessie waarin meerdere open tasks tegelijk bijgewerkt moeten worden zonder ze uit te voeren:

1. Oriëntatie: backlog task list --plain --status "To Do" voor de lijst met open IDs.
2. Parallelle analyse: dispatch een Explore-subagent met de task-IDs en laat die een compact rapport teruggeven over gaps (missing criteria, stale refs, ontbrekende labels, impliciete dependencies). Zie wiki-parallelle-subagents-workflow.
3. Batch-edits toepassen met backlog task edit flags in parallelle Bash calls, elk met korte description en duidelijke intent.
4. Decision-tasks (beslisvragen, geen implementatie) krijgen een apart decision label en acceptance criteria die de beslisruimte definieren.

Dit werkt goed voor backlogs van 40+ open tasks in een enkele sessie, mits de prompt expliciet is over “niet uitvoeren”.

MCP-koppeling

Backlog.md kan als MCP server draaien naast Claude Code. Toevoegen aan ~/.claude/settings.local.json:

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "start"]
    }
  }
}

De MCP server biedt volledige schrijftoegang via tools: task_list, task_search, task_view, task_create, task_edit, task_complete, task_archive, plus document- en DoD-tools. MCP is de voorkeursmethode boven CLI omdat MCP relaties, metadata en geschiedenis consistent houdt. CLI (backlog task ...) is een bruikbaar alternatief als MCP niet beschikbaar is.

Correctie op eerdere versie van dit artikel: de MCP server bood aanvankelijk alleen leestoegang. Vanaf de huidige versie (v1.44+) zijn alle schrijfoperaties ook via MCP beschikbaar.

Instructiedocumenten in ~/.claude/references/

Twee documenten sturen het backlog-gedrag in Claude Code:

• backlog-workflow.md — leidende gedragsgids: WANNEER en HOE backlog gebruiken. Bevat checklist, trigger-regels, statusvolgorde en anti-rationalisaties.
• backlog-md-guide.md — volledige commandoreferentie: alle CLI-flags, MCP-tools, configuratie.

De globale CLAUDE.md verwijst naar backlog-workflow.md als primaire gids. De gedragsgids is trigger-gericht: expliciete “wanneer X, doe Y”-regels met anti-rationalisaties, gebaseerd op het patroon uit de Superpowers-skills.

Trigger-patroon voor gedragsinstructies

Regels zonder trigger furen niet. Effectieve gedragsinstructies hebben:

1. Een checklist bovenaan (scanbaar bij sessiestart)
2. Een beslisregel (“moet ik nadenken over HOE? ja/nee”)
3. Expliciete anti-rationalisaties voor de meest voorkomende ontwijkingen

Kwaliteitsdiscipline na 2 weken gebruik

Evaluatie op 2026-04-16 na twee weken Backlog.md-gebruik (115 taken, 5 projecten):

• Done-rate: 75% — taken worden netjes afgesloten
• 40% van taken miste een Definition of Done — “done” was daarmee arbitrair
• Slechts 2 van 115 taken hadden notities of een log — backlog functioneerde als archief, niet als werkinstrument
• 78 van 115 taken aangemaakt op dag 1 — bulk dump, geen organische workflow

Twee interventies die het meest effect hebben:

1. DoD verplicht bij aanmaken: elke nieuwe taak krijgt minimaal 1 --dod criterium. Zonder DoD is onduidelijk wanneer een taak klaar is.
2. In Progress = loggen: bij het zetten op In Progress direct een notitieregel toevoegen met datum en aanpak via --append-notes. Ook tussentijds bij beslissingen of blokkades.

Deze regels zijn vastgelegd in gedragsregels 9, 10, 11 van ~/.claude/references/backlog-md-guide.md.

Backlog-structuur per project

Vastgelegde verdeling in de guide:

Project	Backlog-locatie
Vault / KennisBank / cc-setup	~/Claude/projects/backlog/ (centraal)
jimvandenbreemen.nl	~/Claude/projects/jimvandenbreemen.nl/.backlog/
atelier	~/Claude/projects/atelier/backlog/
Overige projecten	eigen backlog/ in projectdirectory

Vuistregel: gebruik de backlog in de werkdirectory. De centrale backlog is alleen voor taken zonder eigen repo.

Verbanden

• Zie ook: wiki-claude-workspace-setup
• Gerelateerd project: cc-setup

Sessie-herkomst

• raw-cc-2026-04-10-backlog-installatie
• raw-cc-2026-03-25-backlog-website-rtvoost
• raw-sessie-2026-04-14-cozempic-en-backlog-update
• raw-sessie-2026-04-16-backlog-evaluatie-en-claude-md-cleanup
• raw-sessie-2026-04-21-backlog-workflow-herziening