Warum ich meine eigene backlog.md nicht mehr lese – und was stattdessen hilft

Es begann an einem ganz normalen Morgen. Nach dem Aufwachen und dem ersten Kaffee startete ich meinen Code-Assistenten, um den Fortschritt unserer DEV.to-Serie zu prüfen. Die Antwort klang präzise: „Vier Artikel stehen zur Veröffentlichung bereit.“ Doch etwas stimmte nicht. Ich erinnerte mich dunkel, dass einige davon bereits veröffentlicht worden waren – doch die Unsicherheit blieb. Also fragte ich nach: „Bist du sicher, dass sie noch nicht online sind?“

Der Assistent durchsuchte sofort das state.json-Skript, verglich es mit dem Inhalt von backlog.md und korrigierte sich selbst: Die vier Artikel waren bereits seit zwei oder drei Tagen live. Plötzlich wurde mir klar: Nicht der Assistent hatte sich geirrt – ich selbst hatte meine eigene To-do-Liste nicht mehr aktualisiert. Das Dokument sagte „wartend“, während die Produktion längst weiter war. Die Diskrepanz war kein Fehler der Software, sondern meiner eigenen Nachlässigkeit.

Wenn Dokumentation zur Falle wird

Dieses Problem ist typisch für Solo-Projekte, die über Monate oder Jahre wachsen. Jeder Entwicklungstag produziert zwei parallele Ströme:

• Die dynamische Seite – Commits, Deployments, Datenbankänderungen, Statusübergänge.
• Die statische Seite – Notizen wie backlog.md, MEMORY.md oder README-Dateien, die in Eile erstellt werden, aber selten aktualisiert.

Diese Dokumente entstehen oft in einem Sprint-Abschluss oder einem Refactoring, werden aber selten automatisch synchronisiert. Sobald sich der Code weiterentwickelt, bleiben die Notizen zurück – und werden zu wertlosen Caches. Ohne einen automatischen „Refresh-Mechanismus“ veralten sie schneller, als man denkt.

Code-Regeln für die Dokumentation: Liveness statt Illusion

Die Counterpart Toolkit-Regel R6 (Live / Snapshot / Cache) lässt sich direkt auf Dokumentation übertragen. Jede Information, die aus dem Code abgeleitet werden kann, muss klar einer Kategorie zugeordnet sein:

• Live-Daten sind direkt aus dem System abrufbar (z. B. git log).
• Snapshots sind Momentaufnahmen mit festem Zeitstempel (z. B. ein commit-bezogener Screenshot).
• Caches sind abgeleitete Daten, die regelmäßig aktualisiert werden müssen.

Ein backlog.md, das nicht automatisch mit dem tatsächlichen Stand abgeglichen wird, ist ein fauler Cache. Es sagt nur dann die Wahrheit, wenn jemand manuell nachbessert – was selten passiert.

Die vier Befehle, die alles ändern

Seit Mitte Mai setze ich auf eine neue Routine. Bevor ich überhaupt ein Dokument öffne, führe ich vier einfache Shell-Befehle aus – in dieser Reihenfolge:

git log --since='7d' --oneline

Zeigt alle Commits der letzten sieben Tage an – sortiert und komprimiert.

git status --porcelain

Gibt einen Überblick über ungecommitete Änderungen in Echtzeit.

ls docs/adr/ | wc -l

Zählt die Anzahl der Architekturentscheidungen (ADRs) im Projekt.

cat scripts/devto/state.json | jq 'to_entries|map(select(.value.published))|length'

Ermittelt die Anzahl der veröffentlichten DEV.to-Artikel automatisch.

Das Ergebnis liegt innerhalb von drei Sekunden vor. Falls etwas Unerwartetes auftaucht – ein vergessener Commit oder eine zusätzliche ADR –, gründe ich meine Recherche direkt in den Quelldaten, nicht in einer Notizdatei. Wenn ich doch backlog.md öffne, tue ich das mit der kritischen Frage: „Wer hat dieses Dokument zuletzt aktualisiert – und wann?“. Findet sich darauf keine Antwort im git log, handle ich es wie veraltete Information.

Die Regel, die alles löst: Dateisystem vor Zusammenfassung

Die Counterpart Toolkit-Regel R2 („Filesystem über Summary“) besagt:

„Ein Agent, der `backlog.md` vor `git log` liest, ist kein schlechter Assistent – er führt nur eine menschliche Gewohnheit aus, die eigentlich verboten sein sollte.“

Die Lösung liegt nicht darin, bessere Tools zu bauen, sondern die richtigen Quellen zu nutzen. Ein Dokument, das nicht automatisch aktualisiert wird, ist kein Autoritätsdokument – es ist ein Entwurf. Entweder man baut einen Mechanismus, der es regelmäßig synchronisiert (z. B. via Cron-Job oder Git-Hook), oder man akzeptiert, dass es nur noch als Gedankenstütze dient.

Der Vorfall vom 21. Mai war keine Lüge des Assistenten, sondern eine Erinnerung daran, dass ich selbst meine Dokumentationsroutinen vernachlässigt hatte. Heute vertraue ich nicht mehr auf statische Dateien, sondern auf Systeme, die sich selbst aktualisieren. Die Moral: Echte Daten kommen aus dem Code – nicht aus der Erinnerung.