Deine Codebase sollte aus jeder Debugging-Session lernen

Ein Agent sollte das Retry-Delay im Checkout ändern. Er suchte im Checkout Service, im Network Client, im Environment Schema und im Retry Helper. Gefunden wurde der Wert schließlich in analytics/config.ts, wo er bei einem Refactoring vor zwei Jahren gelandet war.

Der Agent änderte fünf Sekunden auf acht, führte die Tests aus und beendete die Aufgabe.

Der nächste Agent wird dieselbe Suche durchführen.

Mit der Untersuchung war nichts falsch. Sie führte zur richtigen Antwort. Die Verschwendung liegt darin, die Codebase in einem Zustand zu hinterlassen, der wieder dieselben falschen Wege erzeugt. Ein neuer Entwickler im Team würde nächsten Monat denselben Preis zahlen.

Die erste Version meines breadcrumbs Skills sollte das verhindern, indem sie das Ergebnis aufschrieb. Der Agent sollte eine verankerte Notiz in AGENTS.md oder einer eigenen Breadcrumb-Datei hinterlassen: Das Retry-Delay liegt dort, dieser Workaround existiert wegen Safari, diese Funktion muss innerhalb einer Transaktion laufen.

Das klingt verantwortungsvoll. Es erzeugt auch ein weiteres System, das gepflegt werden muss, einen weiteren Ort, der veralten kann, und eine weitere Gewohnheit, die zukünftige Leser kennen müssen. Ich hatte ein besseres Untersuchungstagebuch entworfen. Die Codebase selbst war keinen Deut klarer geworden.

Die neue Version des Skills dreht das Prinzip um:

Wenn ein Trace vermeidbare Verwirrung aufdeckt, repariert der Agent ihre Ursache, solange die Beweise noch frisch sind. Er verschiebt oder benennt das Retry-Setting um. Er macht die Transaktion zum Teil des Funktionsvertrags. Er verbessert die Fehlermeldung, die das kaputte Feld versteckt hat. Er erklärt die Safari-Einschränkung direkt am Workaround. Er korrigiert die veraltete Setup-Anleitung.

Der nächste Leser soll davon profitieren, ohne den Skill zu kennen.

Entwickler lesen ein Repository nicht von oben nach unten. Sie folgen Hinweisen. Ein Dateiname verspricht Zuständigkeit. Ein Symbolname verspricht Verhalten. Ein Import öffnet einen Weg in ein anderes Modul. Eine Fehlermeldung zeigt zur Ursache oder davon weg.

Die Forschung zur Navigation von Programmierern nennt das Information Scent. In einer Studie mit professionellen Entwicklern, die eine echte Anwendung debuggen sollten, sagte ein Modell aus Information Scent und Navigationstopologie ihre Wege besser voraus als vergleichbare Modelle ohne Scent.¹ Wörter und Wege in der Umgebung beeinflussen die Untersuchung.

Damit wird aus dem diffusen Gefühl, Code sei schwer verständlich, ein brauchbares Signal. Die Form des Traces ist ein Beweisstück.

• Du folgst einem plausiblen Namen in das falsche Subsystem. Der Information Scent führt in die Irre.
• Du kehrst immer wieder zum selben Ausgangspunkt zurück und springst manuell zwischen Schichten. Der Navigationstopologie fehlt eine sichtbare Kante oder ein kanonischer Einstieg.
• Du liest jeden Aufrufer, um eine einzige Vorbedingung zu verstehen. Der Vertrag ist unsichtbar.
• Du vergleichst mehrere Werte, weil jeder verbindlich aussieht. Die Zuständigkeit ist fragmentiert.
• Du erreichst die Ursache erst nach einem nutzlosen Folgefehler. Die Diagnose ist undurchsichtig.

Speichere nicht das Suchprotokoll. Nutze es, um die Stelle zu finden, an der die Codebase die falsche Lektion erteilt hat.

Sobald der Smell einen Namen hat, liegt die Reparatur oft nahe. Entscheidend ist ihre Form. Eine Notiz ist schnell geschrieben, aber meistens die schwächste dauerhafte Form.

Der breadcrumbs Skill arbeitet mit einer Reparaturleiter. Beginne oben und gehe nur dann weiter nach unten, wenn die stärkere Form nicht sicher passt:

1. Lösche veraltetes oder irreführendes Material.
2. Zeige die Wahrheit durch Namen, Platzierung, Struktur oder eine explizite Abhängigkeit.
3. Kodiere den Vertrag in Typen, Schemas, Validierung, Assertions oder Tests.
4. Verbessere Fehler und Diagnosekontext.
5. Erkläre einen Grund, den der Code nicht ausdrücken kann.
6. Aktualisiere eine bestehende Dokumentationsfläche, die Leser bereits nutzen.

Das ist keine Rangliste der Wichtigkeit. Es ist eine Rangliste der Direktheit. Code, der nicht falsch verwendet werden kann, ist stärker als ein Absatz, der darum bittet, ihn nicht falsch zu verwenden.

Angenommen, du stellst fest, dass saveOrder innerhalb einer bestehenden Datenbanktransaktion aufgerufen werden muss. Die schwache Reparatur ist eine Notiz:

ts
// Muss innerhalb einer Transaktion aufgerufen werden.
await saveOrder(order);

Sie hilft dem Leser, der sie sieht und sich daran hält. Für den Aufrufer, der sie übersieht, ändert sie nichts. Eine stärkere API macht die Verpflichtung sichtbar:

ts
await saveOrder(transaction, order);

Je nach Sprache und Architektur kann die beste Form ein transaktionsgebundenes Repository, ein zustandsspezifischer Typ, eine Assertion an der Grenze oder eine Validierung mit gezieltem Vertragstest sein. Bertrand Meyers Design by Contract liefert dafür ein nützliches Vokabular: Preconditions beschreiben die Pflichten des Aufrufers, Postconditions die Garantien der Operation und Invariants das, was über Operationen hinweg wahr bleibt.² Dafür braucht es keine Eiffel-Syntax.

invalid configuration ist technisch korrekt und praktisch wertlos. Wenn der Trace zeigt, dass region nach der Interpolation der Umgebungsvariablen leer geworden ist, sollte die früheste Grenze mit genug Kontext genau das melden:

text
checkout config: region is required after environment interpolation

Gute Fehlertypen bewahren die Operation, das betroffene Ziel und die ursprüngliche Ursache. PathError aus dem Go-Projekt ist ein kompaktes Beispiel: Der Fehler trägt Operation, Pfad und Ursache und bleibt dadurch verständlich, selbst wenn er weit entfernt vom fehlerhaften Aufruf ausgegeben wird.³ Strukturierte Details erlauben Tools außerdem zu reagieren, ohne Text parsen zu müssen. Auch hier braucht es Urteilskraft. Tokens, personenbezogene Daten oder ganze Request Bodies gehören nicht in Logs, nur damit sie informativer wirken.

Kommentare sind keine kostenlose Klarheit. Sie gehören zur Leseroberfläche und konkurrieren mit dem Code um Aufmerksamkeit.

Eine Eye-Tracking-Studie von 2025 zeigte, dass Kommentare rund 23 Prozent der visuellen Aufmerksamkeit vom Code abzogen. Ihre Wirkung auf das Verständnis hing vom jeweiligen Snippet ab. Manche halfen, manche verschlechterten die Leistung. Qualität und Kontext entschieden.⁴ Google formuliert die praktische Regel: Wenn ein Reviewer eine Erklärung braucht, sollte die erste Antwort meist klarerer Code sein. Ein Kommentar passt, wenn er etwas trägt, das der Code nicht ausdrücken kann, vor allem den Grund für eine überraschende Entscheidung. Eine Erklärung, die nur im Review Tool steht, hilft später keinem Leser.⁵

Dieser Kommentar verdient seinen Platz:

ts
// Reading layout here forces Safari to apply the pending style before focus.
// Removing it restores the selection jump covered by safari-focus.spec.ts.
void input.offsetHeight;
input.focus();

// Needed for Safari tut das nicht. Der Kommentar nennt einen Browser und lässt die eigentliche Einschränkung weiter unsichtbar.

Manches Wissen gehört tatsächlich in Prosa. Lokales Setup, Incident Recovery, modulübergreifende Architektur und Designentscheidungen passen nicht sauber in eine Typensignatur.

Die Antwort ist trotzdem keine Breadcrumb-Datei. Ändere die gepflegte Fläche, die den Bedarf des Lesers bereits besitzt.

Diátaxis trennt Dokumentation in vier Formen, weil sie verschiedene Probleme lösen: Tutorials lehren, How-to Guides helfen bei einer Aufgabe, Reference liefert nachschlagbare Fakten und Explanation vermittelt Kontext und Gründe.⁶ Ein fehlender Recovery-Befehl gehört ins Runbook. Ein Konfigurationsfeld gehört in die Reference. Ein modulübergreifender Tradeoff gehört in eine Explanation.

Architecture Decision Records haben eine noch höhere Schwelle. Michael Nygards ursprünglicher Vorschlag begrenzt sie auf Entscheidungen, die Struktur, nichtfunktionale Eigenschaften, Abhängigkeiten, Schnittstellen oder Konstruktionstechniken betreffen.⁷ Eine lokale Umbenennung verdient keinen ADR. Eine einzelne überraschende Zeile auch nicht. Wenn das Repository bereits bedeutende Entscheidungen festhält, nutze dieses System für bedeutende Entscheidungen. Führe es nicht als beiläufige Aufräumarbeit ein.

Diese Platzierungsregel ist wichtig, weil Dokumentation genau das Problem nachbauen kann, das sie lösen sollte. Schreibst du die Transaktionspflicht in eine allgemeine Agent-Notiz, hat saveOrder plötzlich zwei Schnittstellen: die Funktionssignatur und ein Dokument an anderer Stelle. Irgendwann widersprechen sie sich.

"Hinterlasse es besser, als du es vorgefunden hast" klingt angenehm und ist eine gefährliche Erlaubnis. Ein Agent kann damit begründen, während eines Bugfixes ein halbes Package umzubenennen.

Breadcrumbs stellt vor jeder Änderung zwei Fragen:

• Wiederholbarkeit: Könnte ein anderer kompetenter Entwickler vernünftigerweise auf dieselbe Verwirrung stoßen?
• Nutzen: Würde die Reparatur diesen Trace verkürzen, ohne dass der nächste Entwickler den Skill kennen muss?

Danach prüft der Skill Sicherheit und Reichweite. Ein nachweislich veralteter Kommentar direkt am Code lässt sich gefahrlos korrigieren. Ein lokaler Fehler kann meist mehr Kontext erhalten. Eine öffentliche API-Umbenennung, Datenmigration, Architekturänderung oder sicherheitsrelevante Verhaltensänderung darf sich nicht in einer beiläufigen Heilung verstecken. In diesem Fall meldet der Agent Belege und Reparaturvorschlag, statt den Scope heimlich auszuweiten.

Null Reparaturen sind ein erfolgreiches Ergebnis, wenn der Trace keinen echten Smell aufgedeckt hat. Der Skill belohnt weniger zukünftige Reibung, nicht sichtbare Aktivität.

Diese Zurückhaltung verhindert, dass aus einer selbstheilenden Praxis eine sich selbst umschreibende Codebase wird.

Der Skill hält den kurzen Healing Loop in SKILL.md und lagert die tiefere Urteilshilfe in ein verlinktes Open-Knowledge-Format-Bundle aus: Smell-Katalog, Reparaturmuster, Autonomiegrenzen, ausgearbeitete Beispiele und die Forschung dahinter. Ein Agent lädt den Katalog nur dann, wenn ein Trace nicht eindeutig zu diagnostizieren ist.

Installiere ihn aus dem saschb2b/skills Repository:

bash
npx skills@latest add saschb2b/skills --skill breadcrumbs

Er kann aus normaler Arbeit heraus anspringen:

text
Wir haben das Retry-Delay nach vier irrelevanten Modulen unter analytics
config gefunden. Ändere den Wert und mach die Zuständigkeit klarer.

Oder in dem Moment, in dem der Smell sichtbar wird:

text
Ich musste jeden Aufrufer lesen, um zu verstehen, dass saveOrder eine
bestehende Transaktion braucht. Mach diesen Vertrag schwerer zu übersehen.

Entscheidend ist, was der Skill nicht erzeugt. Es gibt kein Breadcrumb-Register, kein Untersuchungslog, kein Freshness-Protokoll und keine Pflicht, vor dem Debugging eine Spezialdatei zu lesen. Er führt eine zusammenhängende Reparatur aus, verifiziert sie, erwähnt die beiläufige Änderung im normalen Handoff und kehrt zur Aufgabe zurück.

Du kannst den vollständigen breadcrumbs Skill mit Smell-Katalog und Beispielen lesen.

Am Ende jeder nichttrivialen Untersuchung gibt es ein kurzes Fenster, in dem du sowohl das System als auch die Reibung verstehst, die es verborgen hat. Dieses Fenster schließt sich schnell. Nutze es.

Stelle eine Frage, bevor du den Bereich verlässt:

Lautet die Antwort "keine, ich habe die Domäne gelernt", beende die Aufgabe. Lautet sie irreführender Name, unsichtbare Vorbedingung, toter Pfad, vager Fehler oder veraltete Anweisung, repariere genau diese eine Sache.

Der nächste Trace beginnt in einer besseren Codebase.

• breadcrumbs Skill

  Skill, Knowledge-Smell-Katalog, Reparaturmuster, Scope-Grenzen, Beispiele und Forschungssynthese.

• An Information Foraging Theory of How Programmers Debug

  Die empirische Grundlage dafür, Navigationshinweise und Topologie als beobachtbare Debugging-Signale zu behandeln.

• The Effect of Comments on Program Comprehension

  Eine Eye-Tracking-Studie von 2025 zur kontextabhängigen Wirkung von Kommentaren auf Aufmerksamkeit und Verständnis.

• Design by Contract

  Bertrand Meyers Beschreibung expliziter Preconditions, Postconditions und Invariants.

• Diátaxis in five minutes

  Die praktische Trennung zwischen Tutorial, How-to Guide, Reference und Explanation.

• Documenting Architecture Decisions

  Michael Nygards ursprünglicher ADR-Vorschlag und seine Schwelle für architektonisch bedeutende Entscheidungen.