Die beste Erklärung Ihres Codes ist in einem Chat-Log begraben

Sie haben fünfundvierzig Minuten mit Claude damit verbracht, einen Retry-Circuit zu entwerfen. Sie haben die Failure Modes erklärt, exponentielles Backoff abgelehnt, weil es kaskadierenden Druck verbirgt, sich auf Token-Bucket Rate Limiting mit Jitter geeinigt und eine funktionierende Implementierung generiert. Die Erklärung war klar, das Reasoning war solide, und der Code hat tatsächlich die Tests bestanden.

Dann haben Sie den Tab geschlossen.

Zwei Wochen später fragt ein Kollege, warum die Retry-Logik Jitter statt exponentiellem Backoff verwendet. Sie öffnen eine neue Claude-Session und rekonstruieren das Argument aus dem Gedächtnis. Die neue Erklärung ist nah, aber nicht identisch. Sie haben eine zweite, leicht unterschiedliche mündliche Tradition geschaffen. Keine ist durch Suche auffindbar. Keine ist in einem Pull Request reviewbar. Beide werden verschwinden, wenn Sie das Unternehmen verlassen.

Das ist kein Tooling-Problem. Es ist ein Kategorienfehler. Wir behandeln LLM-Konversationen als private Scratchpads, wenn sie tatsächlich das sind, was den meisten Ingenieuren je an Literate Programming am nächsten kam.

Was Knuth meinte, und warum LLMs es versehentlich geliefert haben

Donald Knuth definierte 1984 Literate Programming als das Schreiben von Programmen als literarische Werke. Code und Dokumentation werden in einer einzigen Erzählung verwoben. Der Leser folgt dem Reasoning des Autors, sieht die in Betracht gezogenen Alternativen und versteht, warum die endgültige Form existiert.

Vierzig Jahre lang blieb Literate Programming eine Nischenpraxis. Tools wie WEB und CWEB erforderten Disziplin. Die meisten Entwickler schrieben Code in eine Datei und Docs in eine andere, und die beiden drifteten sofort auseinander.

Eine LLM-Konversation ist versehentliches Literate Programming. Sie formulieren das Problem in Prosa. Das Modell stellt klärende Fragen. Sie verfeinern Constraints. Es schlägt Code vor. Sie lehnen den Vorschlag ab und erklären warum. Es überarbeitet. Das finale Artefakt ist nicht nur der Code-Block. Es ist der gesamte Thread: die verworfenen Ansätze, die Trade-offs, die Domain-Annahmen.

Das Problem ist, dass das Medium flüchtig ist. Chat-Interfaces sind für Task Completion konzipiert, nicht für Wissenserhaltung. Sobald die Session endet, ist die Erzählung in Bernstein eingefroren, nicht durchsuchbar, nicht versioniert und im Besitz eines Vendors.

Warum Chat-Logs traditionelle Dokumentation für komplexe Entscheidungen schlagen

Traditionelle Dokumentation beschreibt den Endzustand. Sie beantwortet “was.” Ein guter Chat-Log beantwortet “warum,” was die schwierigere Frage ist und diejenige, die am schnellsten verrottet.

Betrachten Sie einen typischen Architecture Decision Record. Er könnte sagen: “Wir haben PostgreSQL statt DynamoDB für den Inventory-Service gewählt wegen starker Konsistenzanforderungen.” Das ist eine Schlussfolgerung. Er sagt nichts über die Queries, die zu langsam waren, die replication lag, die akzeptabel war, oder den Vendor Lock-in, der debattiert und abgelehnt wurde.

Ein Claude-Thread enthält all das. Er enthält die Schema-Iterationen, die fehlgeschlagen sind, die Query-Pläne, die Sie überrascht haben, und den Moment, als Sie realisierten, dass der Composite Index den Status-Filter abdecken musste. Es ist ein Decision Record mit vollständigem Kontext.

Der Haken ist, dass der Kontext in einem konversationellen Format gefangen ist. Durch einen Hundert-Turn-Thread zu scrollen, um die eine Einsicht über Index-Design zu finden, ist miserabel. Das Wissen ist da, aber es ist nicht zugänglich.

Die drei Failure Modes von Chat-as-Docs

Roh-Chat-Logs als Dokumentation zu behandeln scheitert in vorhersehbaren Weisen. Jeder Failure Mode hat eine Lösung, aber Sie müssen absichtlich vorgehen.

Hallucination drift. Claude erfindet APIs, zitiert nichtexistierende Papers und schlägt selbstbewusst Designs vor, die Ihre tatsächlichen Constraints ignorieren. Ein Chat-Log, der als Dokumentation erhalten bleibt, bewahrt die Hallucinations neben der Weisheit auf. Wenn Sie nicht markieren, welche Teile verifiziert und welche spekulativ waren, behandelt der nächste Leser alles als Evangelium.

Narrative sprawl. Eine gute Konversation schweift ab. Sie erkunden Sackgassen, lassen sich von Edge Cases ablenken und kehren zurück. Dieses Abschweifen ist wertvoll für das Verständnis, aber es ist schrecklich für die Referenz. Ein neuer Ingenieur, der die Retry-Policy braucht, muss nicht den zwanzigminütigen Abstecher in die TCP-Congestion-Control lesen.

Vendor lock-in. Ihre Dokumentation lebt in Anthropics Datenbank, hinter deren Such-Interface, unterworfen deren Retention-Policy. Wenn das Konto abläuft oder das Interface sich ändert, verschwinden Ihre Docs. Dokumentation, die Sie nicht greppen können, ist keine Dokumentation.

Wie man ein dauerhaftes Dokument aus einem flüchtigen Chat extrahiert

Die Lösung ist, den Chat als ersten Entwurf zu behandeln, nicht als finales Artefakt. Sie extrahieren, verifizieren und veröffentlichen. Der Workflow ist einfach und dauert etwa zehn Minuten pro signifikanter Entscheidung.

Schritt eins: Markieren Sie die Turns. Während der Konversation markieren Sie die Schlüsselentscheidungen. Ich verwende eine einfache Konvention. Wenn Claude einen Code-Block produziert, den ich behalten möchte, antworte ich mit KEEP: <one-line reason>. Wenn es etwas vorschlägt, das ich ablehne, antworte ich mit REJECT: <reason>. Diese Tags machen die Extraktion trivial.

Schritt zwei: Extrahieren Sie nach Markdown. Nach der Session kopieren Sie den Thread in eine Markdown-Datei und entfernen den Noise. Entfernen Sie die Begrüßungen, die “let me think”-Füllwörter und die Turns, in denen Sie beide verwirrt waren. Behalten Sie die Problemstellung, die in Betracht gezogenen Alternativen, die finale Entscheidung und den verifizierten Code. Das Ergebnis sollte wie eine technische Notiz lesbar sein, nicht wie ein Transkript.

Hier ist ein Skript, das die Extraktion automatisiert, wenn Sie die Claude-API verwenden oder Ihre Konversation als JSON exportieren:

#!/usr/bin/env python3
"""
Extract a readable technical note from a Claude conversation export.
Expects Anthropic's conversation JSON format.
"""

import json
import argparse
from pathlib import Path


def extract_note(conversation_path: Path, output_path: Path) -> None:
    with open(conversation_path) as f:
        data = json.load(f)

    turns = data.get("chat_messages", [])
    lines = []

    for turn in turns:
        sender = turn.get("sender", "unknown")
        text = turn.get("text", "").strip()

        if not text:
            continue

        # Skip pleasantries and meta-turns
        if any(phrase in text.lower() for phrase in [
            "hello", "how can i help", "you're welcome", "glad i could help"
        ]):
            continue

        if sender == "human":
            lines.append(f"**Q:** {text}\n")
        else:
            lines.append(f"**A:** {text}\n")

    with open(output_path, "w") as f:
        f.write("# Technical Note: Extracted from Claude Session\n\n")
        f.write("\n".join(lines))


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", type=Path, required=True)
    parser.add_argument("--output", type=Path, required=True)
    args = parser.parse_args()
    extract_note(args.input, args.output)

Schritt drei: Verifizieren Sie jeden Code-Block. Führen Sie den extrahierten Code aus. Wenn er nicht kompiliert oder die Tests nicht besteht, fixen Sie ihn im Markdown und notieren Sie die Korrektur. Das extrahierte Dokument muss eine Source of Truth sein, nicht ein Transkript einer Konversation, die Fehler enthalten haben könnte.

Schritt vier: Committen Sie ins Repository. Speichern Sie das Markdown in docs/decisions/ oder docs/notes/ neben dem Code, den es beschreibt. Geben Sie ihm einen aussagekräftigen Dateinamen: retry-circuit-jitter-over-exponential.md, nicht claude-chat-july-19.md. Fügen Sie es demselben Pull Request wie die Code-Änderung hinzu, oder öffnen Sie sofort einen Folge-PR. Wenn die Docs nicht unter Versionskontrolle sind, existieren sie nicht.

Wann das funktioniert und wann nicht

Dieser Ansatz glänzt bei komplexen, mehrdeutigen Entscheidungen, bei denen das Reasoning genauso wichtig ist wie das Ergebnis. Circuit-Design, Schema-Migrations-Strategien, API-Versioning-Policies und Performance-Trade-offs sind alles gute Kandidaten.

Es funktioniert nicht für Referenzdokumentation. Ein Chat-Log über die Authentifizierung mit der internen API ist ein schrecklicher Ersatz für eine strukturierte OpenAPI-Spec und ein cURL-Beispiel. Verwenden Sie das richtige Tool für den Job.

Es funktioniert auch nicht ohne Kuratierung. Roh-Chat-Logs in ein Wiki zu kippen, ist keine Dokumentation. Es ist Horten. Die zehn Minuten Extraktion und Bearbeitung sind nicht verhandelbar. Wenn Sie sie überspringen, produzieren Sie durchsuchbaren Müll.

Ein praktischer Ausgangspunkt

Sie brauchen kein neues Tool. Sie brauchen eine Gewohnheit.

Das nächste Mal, wenn Sie eine lange, produktive Session mit Claude über eine nicht-triviale Design-Entscheidung haben, exportieren Sie den Thread, bevor Sie den Tab schließen. Verbringen Sie zehn Minuten damit, ihn in eine Markdown-Notiz zu bearbeiten, die drei Fragen beantwortet: Welches Problem haben wir gelöst? Welche Alternativen haben wir in Betracht gezogen und abgelehnt? Worauf haben wir uns geeinigt und warum?

Committen Sie diese Notiz in Ihr Repo. Verlinken Sie sie aus dem Code-Kommentar über der Funktion, die sie beschreibt. Der nächste Ingenieur, der diesen Code anfasst, wird Ihnen danken, und er wird Claude nicht öffnen müssen, um Ihr Reasoning zu rekonstruieren.

Ihr Chat mit Claude kann Dokumentation werden. Er braucht nur, dass Sie ihn wie Code behandeln: extrahiert, verifiziert, versioniert und gepflegt.