Praxisteil 0. AgentClinic-production-Labor

Status: Standard für den Lernpfad. Dieser Teil führt keine neue Technik ein. Er erklärt, wie der zweite Band als ein einziger Laborzweig nach dem ersten Band gelesen wird.

Der erste Band baut eine kleine AgentClinic: Routen, SQLite, Feature-Spezifikationen, Prüfungen und Reviews. Im zweiten Band dient dasselbe Projekt als didaktisches Produktionsmodell. Wir verlangen kein echtes Kubernetes, Grafana, PagerDuty oder GitOps. Diese Begriffe bezeichnen Rollen in Szenarien: woher das Signal kam, welche Aktion gefährlich sein könnte, wo ein Rollback nötig ist und welches Artefakt die Lösung belegt.

Wenn man die Kapitel als Sammlung unabhängiger fortgeschrittener Techniken liest, wird der Band schnell schwer. Lesen Sie ihn anders: ein Projekt, ein Hauptproduktionskontur, ein wachsendes Beweispaket. Für die Standardzulassung verwenden Sie high_memory_usage; die übrigen Incidents dienen als kleine Laborfenster für einzelne Mechanismen.

Praktische Regel für den ersten Durchlauf: capstone/README.md sollte zu einem Incident-Case Auskunft geben. Ein lokales Beispiel aus einem anderen Kapitel kann einen anderen Incident verwenden, aber in das Zulassungspaket wird nur der prüfbare Grundsatz übernommen. Aus autoscale_200pct wird beispielsweise nicht der zweite Fall übernommen, sondern die Schutzregel (guard) „den Auswirkungsradius nicht über das Kontingent hinaus ausdehnen“. Aus cdn_error_budget_burn wird nicht ein neuer Service übernommen, sondern das Anti-Goodhart-Invariante „MTTR darf nicht auf Kosten eines silent P0 verbessert werden“.

Vor dem Lesen

Teil 0 ist methodisch, ohne didaktischen Fall. Hier gibt es keine Schritte und keinen Kontrollfakt; die Aufgabe besteht darin, eine Landkarte des Bandes zu entwerfen und den Ausführungs-Stack abzustimmen. Ab dem nächsten Kapitel kehrt der Standardblock „Vor dem Lesen“ zurück und fungiert als Vertrag zwischen Kapitel und Zulassung.

Ziel

Vor Kapitel 1 müssen vier Dinge verstanden werden:

• welcher didaktischer Produktionsfall den Zulassungspfad durchläuft;
• welche Dateien als Ergebnis jedes Kapitels gelten;
• welche Befehle tatsächlich ausführbar (runnable) sind und welche nur die Schnittstelle einer zukünftigen Produktionsschicht darstellen;
• wo der didaktische Mindestumfang endet und der vollständige Implementierungstrack beginnt.

Durchgängiger Fall

Das Basisszenario heißt AgentClinic-production. Das ist dieselbe AgentClinic, aber nun gibt es einen Betriebskontur um sie herum. Der Hauptzulassungsfall ist high_memory_usage in appointments-api: er lässt sich bequem bis zur Normalisierung des Webhooks, des Readiness-Gateways, des Probelaufs und des abschließenden Beweispakets führen. Zusätzliche Fälle zeigen einzelne Mechanismen, müssen aber nicht in einem einzigen capstone/ vermischt werden.

• Service appointments-api;
• Alerts high_memory_usage, autoscale_200pct, appointment_latency / appointment_latency_spike, node_not_ready, cdn_error_budget_burn;
• Spezifikationen, die /clear, Modellwechsel und Review durch eine andere Person überleben müssen;
• Verbot gefährlicher Aktionen ohne Beweise: Ausweitung des Auswirkungsradius, Verlust der Auditierung, verdecktes Schließen eines P0, automatische Umgehung eines Rollbacks.

Der didaktische Zweig muss keinen echten Produktionscode enthalten. Es genügen Artefakte in capstone/, Vorlagen aus examples/templates/ und ausführbare Beispiele aus examples/. Wenn ein Kapitel nicht high_memory_usage verwendet, notieren Sie in capstone/ nur die prüfbare Ausgabe: welcher Defekt, Gegenbeispiel, Budgetrisiko oder Invariante in den Hauptfall übernommen werden muss.

Kurze Übernahmekarte:

Ausführungs-Stack

Im ersten Band ist AgentClinic eine Anwendung mit TypeScript, Hono, serverseitigem JSX, SQLite und Vitest. Dieser Stack bleibt erhalten: im didaktischen Modell AgentClinic-production ist er weiterhin der Stack des Produkts selbst.

Im zweiten Band erscheint eine zweite Code-Schicht — kleine ausführbare Skripte in book2/examples/. Sie sind in Python-Stdlib geschrieben und dienen nur dazu, dass eine Person auf ihrer Maschine ein Mindestbeispiel des Kapitels in wenigen Sekunden ohne Infrastrukturaufbau starten kann. Das ist kein Stackwechsel des Produkts und kein Hinweis, dass die Produktions-AgentClinic auf Python umgeschrieben wurde. Das sind didaktische Simulatoren: Stress-Mutator, Duell, Spec CI, Token-Budget, Readiness-Rechner. In einem echten Projekt werden solche Prüfungen häufig als Pre-Commit, GitHub Actions, MCP-Tool oder Service im eigenen Stack umgesetzt — Python ist hier nur die billigste Sprache für einen buildfreien Start.

Die Regel ist einfach: Alles, was in book2/examples/ vorkommt, lässt sich als python3 ... ohne Abhängigkeiten starten. Alles, was im Kapitel als [project script] oder [conceptual interface] gekennzeichnet ist, ist die Form eines zukünftigen Skripts oder einer Integration in Ihrem Projekt, nicht an Python gebunden.

Mindestpfad

Wenn Sie wenig Zeit haben, gehen Sie den zweiten Band so durch:

1. Lesen Sie diesen Teil und die README des gewählten ausführbaren Beispiels.
2. In den Kapiteln 1–3 füllen Sie drei manuelle Artefakte aus: genealogy.md, Poisoned/Fixed-Paar und constitution.md.

1. In den Kapiteln 4–11 starten Sie nur [runnable]-Befehle aus examples/; Ergebnisse anderer Fälle übernehmen Sie in capstone/ als Prinzip, nicht als neue Domäne.
2. In Kapitel 12 prüfen Sie das Paket anhand des diagnostischen Checklists.
3. In Kapitel 13 bauen Sie ein kleines capstone/ zu einem Incident zusammen.

Der Mindestpfad erfordert keine externen Orchestratoren, MCP-Server, Kubernetes-Integrationen oder echten CI-Gateways. Diese Elemente gehören zum vollständigen Track.

Die Pfadprüfung ist einfach: Nach jedem Kapitel muss in capstone/ eine neue prüfbare Ausgabe erscheinen. Kein vollständiger Produktionsprozess, sondern ein kleiner Eintrag, den man einer anderen Person zeigen kann.

> So lesen Sie die Tabelle. Die Spalte „Ausgabe“ ist bewusst in eigenen Worten beschrieben, ohne Begriffe der Kapitel 4–13. Wenn in der rechten Spalte ein Wort vorkommt, das noch nicht im kurzen Wörterbuch unten steht, wird es in dem Kapitel eingeführt, in dem es benötigt wird. Versuchen Sie nicht, den Bandwortschatz anhand dieser Tabelle zu lernen.

| 3 | constitution.md mit zwei unveränderlichen Regeln und einer Regel mit Geltungsdauer | | 4 | minimales Gegenbeispiel zu einer Regel oder Formulierung des nächsten Beschränkers | | 5 | Ergebnis des Smoke-Laufs des Stress-Mutators oder kurzer Bericht, welche Mutationen der Validator gefangen hat | | 6 | ein akzeptierter und ein abgelehnter Schattenkandidat (Regeln, die in die Spezifikation hätten eingehen können) | | 7 | Spec CI-Zeile: was abgedeckt ist, was blockiert wird | | 8 | eine Datei mit Verdikt zu einer umstrittenen Änderung und Verweis auf den Beweis | | 9 | Risiko der Budgeterschöpfung der Modelle und Schwellenwert, bei dem auf die billige Ebene umgeschaltet wird | | 10 | Zielmetrik und paarweise Schutzmetrik gegen ihre Goodhart-Verzerrung | | 11 | Verdikt der Produktionszulassung und Dry-Run der erlaubten Aktion | | 12 | drei Punkte blocker / owner / next_check | | 13 | zusammengestelltes capstone/ zu einem Incident mit fünf PASS-Zeilen der Rubrik |

Wenn in einem Kapitel zusätzliche Begriffe vorkamen, aber diese Ausgabe fehlt, schließen Sie zuerst die Ausgabe ab. Begriffe können später nachgelesen werden.

Als Orientierungshilfe halten Sie das ausgefüllte Beispiel [examples/templates/capstone-dossier.md](examples/templates/capstone-dossier.md) bereit. Das ist keine Vorlage zum gedankenlosen Kopieren, sondern die Mindestform der Antwort auf die Frage: „Welche Spur sollte nach dem ersten Durchlauf zurückbleiben?“

Das Mindestwörterbuch für den ersten Durchlauf ist kurz:

• capstone/ — abschließendes Beweispaket zu einem Incident;
• genealogy.md — Herkunft der Anforderung und Vertrauensniveau;
• validation.md — Befehle, manuelle Fakten und Blocker;
• judgment.md — Verdikt zu einer umstrittenen Änderung;
• readiness.md — warum eine Aktion zugelassen, blockiert oder in halbmanuellen Modus übergeht.

Alle übrigen Begriffe sind nur dann nötig, wenn sie beim Ausfüllen einer dieser Dateien helfen. Wenn ein Begriff die aktuelle Kapitelausgabe nicht beeinflusst, bleiben Sie beim ersten Lesen nicht daran hängen.

Was wirklich gestartet wird

Der zweite Band verwendet drei Typen von Befehlsblöcken:

• [runnable] — starten Sie wie geschrieben. Das Beispiel liegt in book2/examples/.
• [project script] — das ist der Vertrag eines zukünftigen Skripts in Ihrem Projekt. Wenn kein ausführbares Analog angegeben ist, muss der Befehl im Repository des Lehrbuchs nicht existieren.

• [conceptual interface] — Form einer zukünftigen Integration. Sie muss beim didaktischen Durchlauf nicht gestartet werden.

Die Regel ist einfach: Das Zulassungspaket darf sich nur auf Fakten beziehen, die Sie tatsächlich gestartet haben, oder auf manuelle Artefakte, die ohne Chatverlauf lesbar sind.

Erster Smoke-Lauf

Vor dem Lesen der Kapitel 4–11 ist es nützlich, sich zu vergewissern, dass die lokalen Beispiele funktionieren:

bash book2/examples/smoke_all.sh

Das Skript führt einen Smoke-Lauf auf einer temporären Kopie von book2/examples/ aus, hinterlässt also kein out/ und __pycache__ im Arbeitsbaum. Wenn die Zeit knapp ist, öffnen Sie examples/README.md und wählen Sie nur den Block des Kapitels, das Sie gerade durchgehen.

Arbeitsverzeichnis für die Zulassung

Erstellen Sie das Verzeichnis des zukünftigen Pakets:

mkdir -p capstone

Lassen Sie es vorerst leer. In den Kapiteln 1–12 werden Sie nach und nach verstehen, welche Dateien dort hineingelangen. Vermischen Sie nicht mehrere Incidents in einem Beweispaket: Eine Datei kann auf ein ausführbares Analog aus einem anderen Fall verweisen, aber die Lösung muss einen Hauptincident erklären.

capstone/
  README.md
  genealogy.md
  poisoned-spec.md
  fixed-spec.md
  constitution.md
  validation.md
  judgment.md
  budget-note.md

goodhart-note.md
  readiness.md
  antipattern-audit.md

Diese Struktur wiederholt den ersten Band: zuerst Intention und Grenzen, dann Plan und Fakten, dann Review und abschließendes Paket. Der Unterschied des zweiten Bands liegt nur darin, dass sich die Fakten nicht auf ein einzelnes Feature, sondern auf die Produktionszulassung einer gefährlichen Aktion beziehen.

Fügen Sie beim ersten Durchlauf keine Dateien aus dem vollständigen Track in capstone/ ein nur weil sie im Kapitel genannt werden. scorebook, metric_network, decision_hash, precedents.md und CI-Berichte sind nötig, wenn Sie sie tatsächlich erstellt haben oder erklären können, welches ausführbare Analog denselben Grundsatz bestätigt.

Zur leichteren Orientierung, welches Kapitel welche Datei eröffnet:

Wenn unterwegs im Kapitel eine vierte oder fünfte Datei erscheint, die nicht in dieser Liste steht — das ist der vollständige Track. Notieren Sie den Grundsatz in einer Zeile und gehen Sie weiter.

Kontrollfakt

Nach diesem Kapitel ist ein Haupt-Incident-Case gewählt, ein leeres capstone/ erstellt und die ausführbaren Beispiele mit dem Befehl bash book2/examples/smoke_all.sh geprüft oder mit explizitem Grund verschoben. Wenn Sie den Hauptfall und die erste Datei, die in capstone/ gelangt, nicht benennen können, ist der Übergang zu Kapitel 1 zu früh.

Kontrollfragen

1. Warum ist AgentClinic-production ein didaktisches Modell und keine Anforderung, echte Infrastruktur aufzubauen?
2. Worin unterscheidet sich [runnable] von [project script]?
3. Warum darf man in capstone/ nicht high_memory_usage und autoscale_200pct als zwei gleichberechtigte Fälle mischen?
4. Warum muss das abschließende capstone/ ohne Chatverlauf verständlich sein?